diff options
author | pjd <pjd@FreeBSD.org> | 2004-02-11 10:06:18 +0000 |
---|---|---|
committer | pjd <pjd@FreeBSD.org> | 2004-02-11 10:06:18 +0000 |
commit | dbc7255199dc5592095e7b60e310c520a91641bb (patch) | |
tree | 343cd26c39251e0b38b336e71722a99c8b1510da /share | |
parent | d2298f1b5c0d5a034a5957fc6dd651a04fb8626f (diff) | |
download | FreeBSD-src-dbc7255199dc5592095e7b60e310c520a91641bb.zip FreeBSD-src-dbc7255199dc5592095e7b60e310c520a91641bb.tar.gz |
Added first part of GEOM kernel API manuals pages.
Documented function and macros are:
- DECLARE_GEOM_CLASS(),
- g_attach(),
- g_detach(),
- g_new_bio(),
- g_clone_bio(),
- g_destroy_bio(),
- g_new_consumer(),
- g_destroy_consumer(),
- g_read_data(),
- g_write_data(),
- g_post_event(),
- g_waitfor_event(),
- g_cancel_event(),
- g_new_geomf(),
- g_destroy_geom(),
- g_new_providerf(),
- g_destroy_provider(),
- g_error_provider(),
- g_provider_by_name(),
- g_wither_geom().
and more to come.
I want to thanks following people for help with those documents:
Slawek Zak <zaks@prioris.mini.pw.edu.pl>
Simon L. Nielsen <simon@FreeBSD.org>
Pieter de Boer <g.p.de.boer@st.hanze.nl>
and of course
Poul-Henning Kamp <phk@FreeBSD.org>
Reviewed by: phk, scottl
Approved by: phk, scottl (mentor)
Diffstat (limited to 'share')
-rw-r--r-- | share/man/man9/DECLARE_GEOM_CLASS.9 | 175 | ||||
-rw-r--r-- | share/man/man9/g_attach.9 | 138 | ||||
-rw-r--r-- | share/man/man9/g_bio.9 | 224 | ||||
-rw-r--r-- | share/man/man9/g_consumer.9 | 141 | ||||
-rw-r--r-- | share/man/man9/g_data.9 | 111 | ||||
-rw-r--r-- | share/man/man9/g_event.9 | 179 | ||||
-rw-r--r-- | share/man/man9/g_geom.9 | 202 | ||||
-rw-r--r-- | share/man/man9/g_provider.9 | 144 | ||||
-rw-r--r-- | share/man/man9/g_provider_by_name.9 | 74 | ||||
-rw-r--r-- | share/man/man9/g_wither_geom.9 | 85 |
10 files changed, 1473 insertions, 0 deletions
diff --git a/share/man/man9/DECLARE_GEOM_CLASS.9 b/share/man/man9/DECLARE_GEOM_CLASS.9 new file mode 100644 index 0000000..4972caa --- /dev/null +++ b/share/man/man9/DECLARE_GEOM_CLASS.9 @@ -0,0 +1,175 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 16, 2004 +.Dt DECLARE_GEOM_CLASS 9 +.Os +.Sh NAME +.Nm DECLARE_GEOM_CLASS +.Nd "GEOM class declaration macro" +.Sh SYNOPSIS +.In geom/geom.h +.Fn DECLARE_GEOM_CLASS "class" "mod_name" +.Sh DESCRIPTION +The +.Fn DECLARE_GEOM_CLASS +macro registers a GEOM class in GEOM. +A GEOM class itself implements one particular kind of transformation. +Typical examples are: MBR disk partition, BSD disklabel and RAID5 classes. +.Fn DECLARE_GEOM_CLASS +can be used both for compiled in and loaded as +.Xr kld 4 +modules GEOM classes and it is the only official way for class registration. +.Pp +The arguments to +.Fn DECLARE_GEOM_CLASS +are: +.Bl -inset -offset indent +.It Em class +is the +.Vt g_class +structure which describes a GEOM class. +.It Em mod_name +is a kernel module name (not a class name!). +.El +.Pp +Structure +.Vt g_class +contains data describing the class. +They are: +.Bl -inset -offset indent +.It Vt "const char *" Va name +Class name. +.It Vt "g_taste_t *" Va taste +Pointer to function used for taste event handling. +If it is +.No non- Ns Dv NULL +it is called in three situations: +.Bl -dash -offset indent -compact +.It +On class activation, all existing providers are offered for tasting. +.It +When new provider is created it is offered for tasting. +.It +After last write access to a provider is closed it is offered for retasting +(on first write open event +.Dq spoil +was sent). +.El +.It Vt "g_config_t *" Va config +This field is not used anymore, its functionality was replaced by the +.Va ctlreq +field. +.It Vt "g_ctl_req_t *" Va ctlreq +Pointer to function used for handling events from userland applications. +.It Vt "g_init_t *" Va init +Pointer to function which is called right after class registration. +.It Vt "g_fini_t *" Va fini +Pointer to function which is called right before class deregistration. +.It Vt "g_ctl_destroy_geom_t *" Va destroy_geom +Pointer to a function which is called for every geom on class unload. +If this field is not set, the class can not be unloaded. +.El +.Pp +Only field +.Fa name +is required, the rest is optional. +.Pp +.Sh RESTRICTIONS/CONDITIONS +In the +.Vt g_class +initialization one must use C99 initialization (just like in the example below). +.Pp +.Sh EXAMPLES +Example class declaration. +.Bd -literal -offset indent +static struct geom * +g_example_taste(struct g_class *mp, struct g_provider *pp, + int flags __unused) +{ + g_topology_assert(); + + [...] +} + +static void +g_example_ctlreq(struct gctl_req *req, struct g_class *cp, + char const *verb) +{ + + [...] +} + +static int +g_example_destroy_geom(struct gctl_req *req, struct g_class *cp, + struct g_geom *gp) +{ + + g_topology_assert(); + + [...] +} + +static void +g_example_init(struct g_class *mp) +{ + + [...] +} + +static void +g_example_fini(struct g_class *mp) +{ + + [...] +} + +struct g_class example_class = { + .name = "EXAMPLE", + .taste = g_example_taste, + .ctlreq = g_example_ctlreq, + .init = g_example_init, + .fini = g_example_fini, + .destroy_geom = g_example_destroy_geom +}; + +DECLARE_GEOM_CLASS(example_class, g_example); +.Ed +.Sh SEE ALSO +.Xr geom 4 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org . diff --git a/share/man/man9/g_attach.9 b/share/man/man9/g_attach.9 new file mode 100644 index 0000000..9ed77f0 --- /dev/null +++ b/share/man/man9/g_attach.9 @@ -0,0 +1,138 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 16, 2004 +.Dt g_attach 9 +.Os +.Sh NAME +.Nm g_attach , +.Nm g_detach +.Nd "attach/detach consumer to/from provider" +.Sh SYNOPSIS +.In geom/geom.h +.Ft int +.Fn g_attach "struct g_consumer *cp" "struct g_provider *pp" +.Ft void +.Fn g_detach "struct g_consumer *cp" +.Sh DESCRIPTION +The +.Fn g_attach +function attaches given consumer to given provider. +For real provider access (ie. I/O operations), one still need to call the +.Fn g_access_rel +function on consumer to gain access to attached provider. +.Pp +The +.Fn g_detach +function detaches the given consumer from the corresponding provider. +This function is used when we do not want to communicate with the +provider anymore. +.Sh RESTRICTIONS/CONDITIONS +.Fn g_attach : +.Bl -item -offset indent +.It +The consumer can not be attached already. +.It +The operation should not create a topology loop. +.It +The topology lock has to be held. +.El +.Pp +.Fn g_detach : +.Bl -item -offset indent +.It +The consumer has to be attached. +.It +The access count has to be 0. +.It +There must be no active requests. +.It +The topology lock has to be held. +.El +.Sh RETURN VALUES +.Fn g_attach +returns the value 0 if successful; otherwise an error code is returned. +.Sh ERRORS +Possible errors: +.Bl -tag -width Er +.It Bq Er ELOOP +The operation creates a topology loop. +.El +.Sh EXAMPLES +Create consumer, attach it to given provider, gain read access and clean up. +.Bd -literal -offset indent +void +some_function(struct g_geom *mygeom, struct g_provider *pp) +{ + struct g_consumer *cp; + + g_topology_assert(); + + /* Create new consumer on 'mygeom' geom. */ + cp = g_new_consumer(mygeom); + if (cp == NULL) + return; + /* Attach newly created consumer to given provider. */ + if (g_attach(cp, pp) != 0) { + g_destroy_consumer(cp); + return; + } + /* Open provider for reading through our consumer. */ + if (g_access_rel(cp, 1, 0, 0) != 0) { + g_detach(cp); + g_destroy_consumer(cp); + return; + } + + g_topology_unlock(); + /* + * Read data from provider. + */ + g_topology_lock(); + + /* Disconnect from provider (release access count). */ + g_access_rel(cp, -1, 0, 0); + /* Detach from provider. */ + g_detach(cp); + /* Destroy consumer. */ + g_destroy_consumer(cp); +} +.Ed +.Sh SEE ALSO +.Xr DECLARE_GEOM_CLASS 9 , +.Xr geom 4 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org . diff --git a/share/man/man9/g_bio.9 b/share/man/man9/g_bio.9 new file mode 100644 index 0000000..d602665 --- /dev/null +++ b/share/man/man9/g_bio.9 @@ -0,0 +1,224 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 16, 2004 +.Dt g_bio 9 +.Os +.Sh NAME +.Nm g_new_bio , +.Nm g_clone_bio , +.Nm g_destroy_bio +.Nd "bio controlling functions" +.Sh SYNOPSIS +.In sys/bio.h +.In geom/geom.h +.Ft "struct bio *" +.Fn g_new_bio void +.Ft "struct bio *" +.Fn g_clone_bio "struct bio *bp" +.Ft void +.Fn g_destroy_bio "struct bio *bp" +.Sh DESCRIPTION +The +.Fa bio +structure is used by GEOM to describe I/O requests. +Most important fields of +.Fa struct bio +are described below: +.Bl -tag -width ".Va bio_attribute" +.It Va bio_cmd +I/O request number. +There are four I/O requests available in GEOM: +.Bl -tag -width BIO_GETATTR +.It Dv BIO_READ +Self explanatory. +.It Dv BIO_WRITE +Self explanatory. +.It Dv BIO_DELETE +Delete indicates that a certain range of data is no longer used and that +it can be erased or freed as the underlying technology supports. +Technologies like flash adaptation layers can arrange to erase the relevant +blocks before they will become reassigned and cryptographic devices may +want to fill random bits into the range to reduce the amount of data +available for attack. +.It Dv BIO_GETATTR +Get attribute supports inspection and manipulation of out\-of\-band +attributes on a particular provider or path. +Attributes are named by ascii strings and are stored in the +.Va bio_attribute +field. +.El +.It Va bio_offset +Offset into provider. +.It Va bio_data +Pointer to data buffer. +.It Va bio_flags +Available flags: +.Bl -tag -width BIO_GETATTR +.It Dv BIO_ERROR +Request failed (error value is stored in +.Va bio_error ) +field. +.It Dv BIO_DONE +Request finished. +.It Dv BIO_FLAG1 +Avaliable for private use. +.It Dv BIO_FLAG2 +Avaliable for private use. +.El +.It Va bio_error +Error value when BIO_ERROR is set. +.It Va bio_done +Pointer to function which will be called on request finish. +.It Va bio_driver1 +Private use by the callee (ie: the provider). +.It Va bio_driver2 +Private use by the callee (ie: the provider). +.It Va bio_caller1 +Private use by the caller (ie: the consumer). +.It Va bio_caller2 +Private use by the caller (ie: the consumer). +.It Va bio_attribute +Attribute string for BIO_GETATTR request. +.It Va bio_from +Consumer to use for request (attached to provider stored in +.Va bio_to +field) (typically read\-only for a class). +.It Va bio_to +Destination provider (typically read\-only for a class). +.It Va bio_length +Request length in bytes. +.It Va bio_completed +Number of bytes completed, but they may not be completed from +the front of the request. +.It Va bio_children +Number of bio clones (typically read\-only for a class). +.It Va bio_inbed +Number of finished bio clones. +.It Va bio_parent +Pointer to parent bio. +.El +.Pp +The +.Fn g_new_bio +function allocates a new, empty +.Vt bio +structure. +.Pp +The +.Fn g_clone_bio +function allocates a new +.Vt bio +structure and copies those fields from the +.Vt bio +structure given as an argument to clone: +.Va bio_cmd , +.Va bio_length , +.Va bio_offset , +.Va bio_data , +.Va bio_attribute . +The field +.Va bio_parent +in clone is set to source +.Vt bio +and the field +.Va bio_children +in parent is increased. +.Pp +This function should be used for every request which enters through +the provider of a particular geom and needs to be scheduled down. +Proper order is: +.Pp +.Bl -enum -compact +.It +Clone +.Vt "struct bio" . +.It +Modify the clone. +.It +Schedule the clone on its own consumer. +.El +.Pp +The +.Fn g_destroy_bio +function kills the given +.Vt bio +structure. +.Sh EXAMPLES +Implementation of +.Dq Dv NULL Ns \-transformation , +meaning that an I/O request is cloned and scheduled down without any +modifications. +Let's assume that field +.Va ex_consumer +in structure +.Vt example_softc +contains a consumer attached to the provider we want to operate on. +.Bd -literal -offset indent +void +example_start(struct bio *bp) +{ + struct example_softc *sc; + struct bio *cbp; + + sc = bp->bio_to->geom->softc; + if (sc == NULL) { + g_io_deliver(bp, ENXIO); + return; + } + + /* Let's clone our bio request. */ + cbp = g_clone_bio(bp); + if (cbp == NULL) { + g_io_deliver(bp, ENOMEM); + return; + } + cbp->bio_done = g_std_done; /* Standard 'done' function. */ + + /* Ok, schedule it down. */ + /* + * The consumer can be obtained from + * LIST_FIRST(&bp->bio_to->geom->consumers) as well, + * if there is only one in our geom. + */ + g_io_request(cbp, sc->ex_consumer); +} +.Ed +.Sh SEE ALSO +.Xr DECLARE_GEOM_CLASS 9 , +.Xr geom 4 , +.Xr g_attach 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org . diff --git a/share/man/man9/g_consumer.9 b/share/man/man9/g_consumer.9 new file mode 100644 index 0000000..17b6c11 --- /dev/null +++ b/share/man/man9/g_consumer.9 @@ -0,0 +1,141 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 16, 2004 +.Dt g_consumer 9 +.Os +.Sh NAME +.Nm g_new_consumer , +.Nm g_destroy_consumer +.Nd "GEOM consumers management" +.Sh SYNOPSIS +.In geom/geom.h +.Ft "struct g_consumer *" +.Fn g_new_consumer "struct g_geom *gp" +.Ft void +.Fn g_destroy_consumer "struct g_consumer *cp" +.Sh DESCRIPTION +The GEOM consumer is the backdoor through which a geom connects to +another GEOM provider and through which I/O requests are sent. +.Pp +The +.Fn g_new_consumer +function creates a new consumer releated to geom +.Fa gp . +The consumer is unusable prior attaching to a provider and gaining access +to it. +To serve its purpose, the consumer has to be attached to a provider +with the +.Xr g_attach 9 +function. +.Pp +The +.Fn g_destroy_consumer +function destroys given consumer and cancels all related pending events. +This function is the last stage of killing an unwanted consumer. +.Pp +.Sh RESTRICTIONS/CONDITIONS +.Fn g_new_consumer : +.Bl -item -offset indent +.It +The geom related to the created consumer must have the +.Fa start +and +.Fa access +fields defined. +.It +The topology lock has to be held. +.El +.Pp +.Fn g_destroy_consumer : +.Bl -item -offset indent +.It +The consumer can not be attached. +.It +The access count has to be 0. +.It +The topology lock has to be held. +.El +.Sh RETURN VALUES +.Fn g_new_consumer +returns a pointer to the newly created consumer or +.Dv NULL +if an error occured. +.Sh EXAMPLES +Create consumer, attach it to given provider, gain read access and clean up. +.Bd -literal -offset indent +void +some_function(struct g_geom *mygeom, struct g_provider *pp) +{ + struct g_consumer *cp; + + g_topology_assert(); + + /* Create new consumer on 'mygeom' geom. */ + cp = g_new_consumer(mygeom); + if (cp == NULL) + return; + /* Attach newly created consumer to given provider. */ + if (g_attach(cp, pp) != 0) { + g_destroy_consumer(cp); + return; + } + /* Open provider for reading through our consumer. */ + if (g_access_rel(cp, 1, 0, 0) != 0) { + g_detach(cp); + g_destroy_consumer(cp); + return; + } + + g_topology_unlock(); + /* + * Read data from provider. + */ + g_topology_lock(); + + /* Disconnect from provider (release access count). */ + g_access_rel(cp, -1, 0, 0); + /* Detach from provider. */ + g_detach(cp); + /* Destroy consumer. */ + g_destroy_consumer(cp); +} +.Ed +.Sh SEE ALSO +.Xr DECLARE_GEOM_CLASS 9 , +.Xr geom 4 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org . diff --git a/share/man/man9/g_data.9 b/share/man/man9/g_data.9 new file mode 100644 index 0000000..c274cef --- /dev/null +++ b/share/man/man9/g_data.9 @@ -0,0 +1,111 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 16, 2004 +.Dt g_data 9 +.Os +.Sh NAME +.Nm g_read_data , +.Nm g_write_data +.Nd "read/write data through consumer" +.Sh SYNOPSIS +.In geom/geom.h +.Ft "void *" +.Fn g_read_data "struct g_consumer *cp" "off_t offset" "off_t length" "int *error" +.Ft int +.Fn g_write_data "struct g_consumer *cp" "off_t offset" "void *ptr" "off_t length" +.Sh DESCRIPTION +The +.Fn g_read_data +reads +.Fa length +bytes of data from a provider through attached consumer +.Fa cp +starting at offset +.Fa offset . +Memory for data is allocated inside +.Fn g_read_data +with +.Fn g_malloc , +and should therefor be freed by the caller with the +.Fn g_free +function after use. +If the operation fails, an error value will be stored in the +.Fa error +argument if it is not +.Dv NULL . +.Pp +The +.Fn g_write_data +writes +.Fa length +bytes of data from address +.Fa ptr +starting at offset +.Fa offset +to a provider through the attached consumer +.Fa cp . +.Sh RESTRICTIONS/CONDITIONS +Length of data should be a multiple of the sectorsize for the provider +and less than or equal to +.Dv DFLTPHYS +.Dv ( DFLTPHYS is defined in +.In sys/param.h ) . +.Pp +The topology lock must not be held. +.Sh RETURN VALUES +.Fn g_read_data +returns a pointer to the read data or +.Dv NULL +if an error occured. +In that case an error value is stored in the +.Fa error +argument unsless it is +.Dv NULL . +.Pp +.Fn g_write_data +returns the value 0 if successful; otherwise an error code is returned. +.Sh ERRORS +Possible errors: +.Bl -tag -width Er +.It Bq Er EIO +Can not read data. +.El +.Sh SEE ALSO +.Xr DECLARE_GEOM_CLASS 9 , +.Xr geom 4 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org . diff --git a/share/man/man9/g_event.9 b/share/man/man9/g_event.9 new file mode 100644 index 0000000..04d62118 --- /dev/null +++ b/share/man/man9/g_event.9 @@ -0,0 +1,179 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 16, 2004 +.Dt g_event 9 +.Os +.Sh NAME +.Nm g_post_event , +.Nm g_waitfor_event , +.Nm g_cancel_event +.Nd "events management" +.Sh SYNOPSIS +.In geom/geom.h +.Ft int +.Fn g_post_event "g_event_t *func" "void *arg" "int flag" ... +.Ft int +.Fn g_waitfor_event "g_event_t *func" "void *arg" "int flag" ... +.Ft void +.Fn g_cancel_event "void *ref" +.Sh DESCRIPTION +The GEOM has its own event queue to inform classes about important things. +The event queue can be also used by classes, mostly for running away +from I/O path. +Sleeping, heavy weight tasks, etc. are not permitted on I/O path and +events are the cure to avoid such situations. +.Pp +The +.Fn g_post_event +function tells GEOM to call function +.Fa func +with argument +.Fa arg +from the event queue. +The +.Fa flag +argument is a flag for +.Xr malloc 9 +that should be used by GEOM. +Only the flags +.Dv M_WAITOK +or +.Dv M_NOWAIT +can be used. +The rest of the arguments are used as references. +An event can be canceled by using any of given references as an +argument to the +.Fn g_cancel_event +function. +The list of references has to end with a +.Dv NULL +value. +.Pp +The +.Fn g_waitfor_event +function is a blocking version of the +.Fn g_post_event +function. +It waits until the event is finished or canceled and then returns. +.Pp +The +.Fn g_cancel_event +function cancels event(s) identified by +.Fa ref . +Cancellation is equivalent to calling the requested function +with requested arguments and argument +.Fa flag +set to +.Dv EV_CANCEL . +.Sh RESTRICTIONS/CONDITIONS +.Fn g_post_event : +.Bl -item -offset indent +.It +The argument +.Fa flag +has to be +.Dv M_WAITOK +or +.Dv M_NOWAIT . +.It +The list of references has to end with a +.Dv NULL +value. +.El +.Pp +.Fn g_waitfor_event : +.Bl -item -offset indent +.It +The argument +.Fa flag +has to be +.Dv M_WAITOK +or +.Dv M_NOWAIT . +.It +The list of references has to end with a +.Dv NULL +value. +.It +The +.Fn g_waitfor_event +function can not be called from an event, since doing so would result +in a deadlock. +.El +.Sh RETURN VALUES +.Fn g_post_event +and +.Fn g_waitfor_event +returns the value 0 if successful; otherwise an error code is returned. +.Sh ERRORS +Possible errors for +.Fn g_post_event +function: +.Bl -tag -width Er +.It Bq Er ENOMEM +There was insufficient memory. +.El +.Pp +Possible errors for +.Fn g_waitfor_event +function: +.Bl -tag -width Er +.It Bq Er EAGAIN +The event was canceled. +.It Bq Er ENOMEM +There was insufficient memory. +.El +.Sh EXAMPLES +Example of a function called from the event queue. +.Bd -literal -offset indent +void +example_event(void *arg, int flag) +{ + + if (flag == EV_CANCEL) { + printf("Event with argument %p canceled.\\n", arg); + return; + } + + printf("Event with argument %p called.\\n", arg); +} +.Ed +.Sh SEE ALSO +.Xr DECLARE_GEOM_CLASS 9 , +.Xr geom 4 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org . diff --git a/share/man/man9/g_geom.9 b/share/man/man9/g_geom.9 new file mode 100644 index 0000000..febc55b --- /dev/null +++ b/share/man/man9/g_geom.9 @@ -0,0 +1,202 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 16, 2004 +.Dt g_geom 9 +.Os +.Sh NAME +.Nm g_new_geomf , +.Nm g_destroy_geom +.Nd "geom management" +.Sh SYNOPSIS +.In geom/geom.h +.Ft "struct g_geom *" +.Fn g_new_geomf "struct g_class *mp" "const char *fmt" ... +.Ft void +.Fn g_destroy_geom "struct g_geom *gp" +.Sh DESCRIPTION +The geom (do not confuse +.Dq geom +with +.Dq GEOM ) +is an instance of a GEOM class. +For example: in a typical i386 FreeBSD system, there will be one geom +of class MBR for each disk. +The geom's name is not really important, it is only used in the XML +dump and for debugging purposes. +There can be many geoms with the same name. +.Pp +The +.Fn g_new_geomf +function creates a new geom, which will be an instance of the class +.Fa mp . +The geom name is created in a printf\-like way from the rest of the arguments. +.Pp +The +.Fn g_destroy_geom +function destroys the given geom imediately and cancels all related pending +events. +.Pp +Structure +.Vt g_geom +contains fields, that should be set by the caller after geom creation, but before +creating any providers or consumers related to this geom (not all are required): +.Bl -inset -offset indent +.It Vt "g_start_t *" Va start +Pointer to a function used for I/O processing. +.It Vt "g_spoiled_t *" Va spoiled +Pointer to a function used for consumers spoiling. +.It Vt "g_dumpconf_t *" Va dumpconf +Pointer to a function used for configuration in XML format dumping. +.It Vt "g_access_t *" Va access +Pointer to a function used for access control. +.It Vt "g_orphan_t *" Va orphan +Pointer to a function used to inform about orphaned consumer. +.It Vt "g_ioctl_t *" Va ioctl +Pointer to a function used for handling ioctl requests. +.It Vt "void *" Va softc +Field for private use. +.El +.Sh RESTRICTIONS/CONDITIONS +If you intend to use providers in this geom you must set field +.Va start +of your geom. +.Pp +If you are planning to use consumers in your geom you must set fields +.Va orphan +and +.Va access +for it. +.Pp +.Fn g_new_geomf : +.Bl -item -offset indent +.It +Class +.Fa mp +must be valid (registered in GEOM). +.It +The topology lock has to be held. +.El +.Pp +.Fn g_destroy_geom : +.Bl -item -offset indent +.It +The geom can not posses any providers. +.It +The geom can not posses any consumers. +.It +The topology lock has to be held. +.El +.Sh RETURN VALUES +.Fn g_new_geomf +returns a pointer to the newly created geom or +.Dv NULL +if an error occured. +.Sh EXAMPLES +Create an example geom. +.Bd -literal -offset indent +static struct geom * +g_example_start(struct bio *bp) +{ + + [...] +} + +static void +g_example_orphan(struct g_consumer *cp) +{ + + g_topology_assert(); + + [...] +} + +static void +g_example_spoiled(struct g_consumer *cp) +{ + + g_topology_assert(); + + [...] +} + +static void +g_example_access(struct g_provider *pp, int dr, int dw, int de) +{ + + [...] +} + +static struct g_geom * +create_example_geom(struct g_class *myclass) +{ + struct g_geom *gp; + + g_topology_lock(); + gp = g_new_geomf(myclass, "example_geom"); + g_topology_unlock(); + if (gp != NULL) { + gp->start = g_example_start; + gp->orphan = g_example_orphan; + gp->spoiled = g_example_spoiled; + gp->access = g_example_access; + gp->softc = NULL; + } + + return (gp); +} + +static int +destroy_example_geom(struct g_geom *gp) +{ + + g_topology_lock(); + if (!LIST_EMPTY(&gp->provider) || + !LIST_EMPTY(&gp->consumer)) { + g_topology_unlock(); + return (EBUSY); + } + g_destroy_geom(gp); + g_topology_unlock(); + + return (0); +} +.Ed +.Sh SEE ALSO +.Xr DECLARE_GEOM_CLASS 9 , +.Xr geom 4 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org . diff --git a/share/man/man9/g_provider.9 b/share/man/man9/g_provider.9 new file mode 100644 index 0000000..5318b8a --- /dev/null +++ b/share/man/man9/g_provider.9 @@ -0,0 +1,144 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 16, 2004 +.Dt g_provider 9 +.Os +.Sh NAME +.Nm g_new_providerf , +.Nm g_destroy_provider , +.Nm g_error_provider +.Nd "GEOM providers management" +.Sh SYNOPSIS +.In geom/geom.h +.Ft "struct g_provider *" +.Fn g_new_providerf "struct g_geom *gp" "const char *fmt" ... +.Ft void +.Fn g_destroy_provider "struct g_provider *pp" +.Ft void +.Fn g_error_provider "struct g_provider *pp" "int error" +.Sh DESCRIPTION +The GEOM provider is the front gate at which a geom offers service. +A provider is +.Dq a disk\-like thing which appears in Pa /dev +\- a logical disk in other words. +All providers have three main properties: name, sectorsize and size. +.Pp +The +.Fn g_new_providerf +function creates a new provider and attaches it to geom +.Fa gp . +The provider name is created in a printf\-like way from the rest of +the arguments. +After creation, the provider is unusable, because +.Fn g_new_providerf +sets its error to +.Er ENXIO . +The function +.Fn g_error_provider +should be used to reset this error, but before it is called, two +fields should be set in the provider structure: +.Va mediasize +and +.Va sectorsize +as well as other initialization things should be done first. +.Pp +The +.Fn g_destroy_provider +function destroys the given provider, cancels all related pending events and +removes corresponding devfs entry. +.Pp +The +.Fn g_error_provider +function is used to set a provider error value. +If it set to a nonzero value, all I/O requests will be denied, +increasing its access count will not be possible (error +.Fa error +will be returned). +.Sh RESTRICTIONS/CONDITIONS +.Fn g_new_provider : +.Bl -item -offset indent +.It +The provider name should be unique, but this is not enforced by GEOM. +If the name is not unique, one will end up with two (or more) files +with the same name, which is programmer error. +.It +The geom related to the created provider must have +.Fa start +field defined. +.It +The topology lock has to be held. +.El +.Pp +.Fn g_destroy_provider : +.Bl -item -offset indent +.It +No consumers have to be attached. +.It +The access count has to be 0. +.It +The topology lock has to be held. +.El +.Sh RETURN VALUES +.Fn g_new_providerf +returns a pointer to the newly created provider or +.Dv NULL +if an error occured. +.Sh EXAMPLES +Create an example provider, set its parameters and make it usable. +.Bd -literal -offset indent +struct g_provider * +create_example_provider(struct g_geom *gp) +{ + struct g_provider *pp; + + g_topology_lock(); + pp = g_new_providerf(gp, "example_provider"); + g_topology_unlock(); + if (pp != NULL) { + pp->mediasize = 65536; + pp->sectorsize = 512; + g_error_provider(pp, 0); + } + + return (pp); +} +.Ed +.Sh SEE ALSO +.Xr DECLARE_GEOM_CLASS 9 , +.Xr geom 4 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org . diff --git a/share/man/man9/g_provider_by_name.9 b/share/man/man9/g_provider_by_name.9 new file mode 100644 index 0000000..92a78b4 --- /dev/null +++ b/share/man/man9/g_provider_by_name.9 @@ -0,0 +1,74 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 16, 2004 +.Dt g_provider_by_name 9 +.Os +.Sh NAME +.Nm g_provider_by_name +.Nd "find provider with given name" +.Sh SYNOPSIS +.In geom/geom.h +.Ft "struct g_provider *" +.Fn g_provider_by_name "const char *name" +.Sh DESCRIPTION +The +.Fn g_provider_by_name +searches for a provider called +.Fa name +and returns the structure +.Fa g_provider +bound to it. +Argument +.Fa name +should be a name, not a full path (ie. +.Dq Pa da0 , +instead of +.Dq Pa /dev/da0 ) . +.Sh RESTRICTIONS/CONDITIONS +The topology lock has to be held. +.Sh RETURN VALUES +.Fn g_provider_by_name +returns a pointer to the provider called +.Fa name +or +.Dv NULL +if there is no such provider. +.Sh SEE ALSO +.Xr DECLARE_GEOM_CLASS 9 , +.Xr geom 4 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org . diff --git a/share/man/man9/g_wither_geom.9 b/share/man/man9/g_wither_geom.9 new file mode 100644 index 0000000..390fb4d --- /dev/null +++ b/share/man/man9/g_wither_geom.9 @@ -0,0 +1,85 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 16, 2004 +.Dt g_wither_geom 9 +.Os +.Sh NAME +.Nm g_wither_geom +.Nd "destroy geom and releated providers and consumers when you get a chance" +.Sh SYNOPSIS +.In geom/geom.h +.Ft void +.Fn g_wither_geom "struct g_geom *gp" "int error" +.Sh DESCRIPTION +The +.Fn g_wither_geom +function tells GEOM that geom +.Fa gp +is to be destroyed. +GEOM sets an error for every provider related to the given geom (in +orphan process) and waits for a chance to destroy the geom. +If access count of any possessed consumer goes to 0, consumer will be +detached and destroyed automatically. +If last consumer attached to any possesed provider will be detached, +provider will be destroyed. +If there are no more providers nor consumers, the geom will be +destroyed. +.Pp +This is an automatic +.Dq garbage collect +to avoid duplicated code in all classes. +Before it is called, field +.Va softc +should be disposed off and set to +.Dv NULL . +Note that the +.Fn g_wither_geom +function gives no guarantee that geom will be immediately destroyed, mostly +because access counts of corresponding consumers and providers may not be 0. +That is why calling this function for every geom from given class is not enough +to be sure that class can be unloaded. +.Sh RESTRICTIONS/CONDITIONS +The argument +.Fa error +must be nonzero. +.Pp +The topology lock has to be held. +.Sh SEE ALSO +.Xr DECLARE_GEOM_CLASS 9 , +.Xr geom 4 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org . |