mirror/freebsd
1
0
Fork 0
mirror of https://git.FreeBSD.org/src.git synced 2024-11-29 08:08:37 +00:00
Code Issues Releases Activity

Added first part of GEOM kernel API manuals pages.

Browse Source 
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)
This commit is contained in:
Pawel Jakub Dawidek 2004-02-11 10:06:18 +00:00
parent 45d370ee8b
commit f827ccb9a3
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=125699
10 changed files with 1473 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

175
share/man/man9/DECLARE_GEOM_CLASS.9 Normal file
View File

@ -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 .

138
share/man/man9/g_attach.9 Normal file
View File

@ -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 .

224
share/man/man9/g_bio.9 Normal file
View File

@ -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 .

141
share/man/man9/g_consumer.9 Normal file
View File

@ -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 .

111
share/man/man9/g_data.9 Normal file
View File

@ -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 .

179
share/man/man9/g_event.9 Normal file
View File

@ -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 .

202
share/man/man9/g_geom.9 Normal file
View File

@ -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 .

144
share/man/man9/g_provider.9 Normal file
View File

@ -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 .

74
share/man/man9/g_provider_by_name.9 Normal file
View File

@ -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 .

85
share/man/man9/g_wither_geom.9 Normal file
View File

@ -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 .