d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update several GEOM related manual pages:

Browse Source 
*) Fix spelling errors.
  *) Better english.
  *) Re-phrasing.

Not Reviewed by:  pjd (one week timeout)
Approved by:      grog (mentor)
This commit is contained in:
Lukas Ertl 2004-05-18 11:33:37 +00:00
parent ca2ffd2633
commit eaad868d16
9 changed files with 173 additions and 151 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
share/man/man9/g_access.9
View File

@ -29,7 +29,7 @@
.Os
.Sh NAME
.Nm g_access
.Nd "control access count between given consumer and its provider"
.Nd "control access to GEOM consumers and their providers"
.Sh SYNOPSIS
.In geom/geom.h
.Ft int
@ -37,26 +37,29 @@
.Sh DESCRIPTION
The
.Fn g_access
function allows to open/change access to/close the provider which is
attached to the given consumer
function allows to open, close, and generally change access to the provider
which is attached to the given consumer
.Fa cp .
Arguments
The arguments
.Fa dcr ,
.Fa dcw ,
and
.Fa dce
stand for read, write and exclusive access count change.
Read and write access are self explanatory.
Exclusive access count prevents others write access.
Provider's access count is the sum of all attached consumers counts.
After attaching to the provider with
.Fn g_attach
function, one have to use
.Fn g_access
function before starting I/O requests.
.Sh RESTRICTIONS/CONDITIONS
The consumer must be attached.
represent relative read, write, and exclusive access count changes.
Read and write access counts are self explanatory, and
exclusive access counts deny write access to other interested parties.
A provider's access count is the sum of the access counts of all
attached consumers.
.Pp
Change cannot result in negative access count.
After attaching a consumer to a provider with
.Fn g_attach ,
the
.Fn g_access
function has to be called on the consumer before starting I/O requests.
.Sh RESTRICTIONS/CONDITIONS
The consumer has to be attached to a provider.
.Pp
The intended change must not result in a negative access count.
.Pp
No\-operation is not permitted
.Fa ( dcr
@ -67,17 +70,18 @@ No\-operation is not permitted
=
.Va 0 ) .
.Pp
Access method for provider's geom have to be defined (eg. gp->access).
The provider's geom must have an access method defined (eg. gp->access).
.Pp
The topology lock must be held.
The topology lock has to be held.
.Sh RETURN VALUES
.Fn g_attach
returns the value 0 if successful; otherwise an error code is returned.
Note, that
The
.Fn g_access
function cannot failed when arguments
function returns 0 if successful; otherwise an error code is returned.
Note that
.Fn g_access
cannot fail when the arguments
.Fa dcr ,
.Fa dcw
.Fa dcw ,
and
.Fa dce
are less than or equal to 0.
@ -85,17 +89,17 @@ are less than or equal to 0.
Possible errors:
.Bl -tag -width Er
.It Bq Er EPERM
The function is trying to open with exclusive access count, but provider
is already open for writting.
The function is trying to open a provider with an exclusive access count, but
it is already open for writing.
.It Bq Er EPERM
The function is trying to open for write, but provider is already exclusively
open.
The function is trying to open a provider for writing, but it is already
exclusively open.
.El
.Pp
Any other error, than can be returned by provider's access method.
Any other error that can be returned by the provider's access method.
.Sh EXAMPLES
Create consumer, attach it to given provider, gain read access and read first
sector.
Create a consumer, attach it to a given provider, gain read access and
read first sector.
.Bd -literal -offset indent
void
some_function(struct g_geom *mygeom, struct g_provider *pp)
@ -123,7 +127,7 @@ some_function(struct g_geom *mygeom, struct g_provider *pp)
}
/*
* Don't hold toplogy lock while reading.
* Don't hold topology lock while reading.
*/
g_topology_unlock();
ptr = g_read_data(cp, 0, pp->sectorsize, &error);

28
share/man/man9/g_attach.9
View File

@ -30,7 +30,7 @@
.Sh NAME
.Nm g_attach ,
.Nm g_detach
.Nd "attach/detach consumer to/from provider"
.Nd "attach/detach GEOM consumers to/from providers"
.Sh SYNOPSIS
.In geom/geom.h
.Ft int
@ -40,23 +40,26 @@
.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
function on consumer to gain access to attached provider.
function attaches given consumer
.Fa cp
to given provider
.Fa pp ,
thus establishing a communication channel between the consumer and the
provider that allows to change access counts or perform I/O operations.
.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.
function detaches given consumer
.Fa cp
from its corresponding provider, tearing down the communication channel
between them.
.Sh RESTRICTIONS/CONDITIONS
.Fn g_attach :
.Bl -item -offset indent
.It
The consumer can not be attached already.
The consumer must not be attached to a provider.
.It
The operation should not create a topology loop.
The operation must not create a topology loop.
.It
The topology lock has to be held.
.El
@ -73,8 +76,9 @@ There must be no active requests.
The topology lock has to be held.
.El
.Sh RETURN VALUES
The
.Fn g_attach
returns the value 0 if successful; otherwise an error code is returned.
function returns 0 if successful; otherwise an error code is returned.
.Sh ERRORS
Possible errors:
.Bl -tag -width Er
@ -82,7 +86,7 @@ Possible errors:
The operation creates a topology loop.
.El
.Sh EXAMPLES
Create consumer, attach it to given provider, gain read access and clean up.
Create a consumer, attach it to a given provider, gain read access and clean up.
.Bd -literal -offset indent
void
some_function(struct g_geom *mygeom, struct g_provider *pp)

52
share/man/man9/g_bio.9
View File

@ -32,7 +32,7 @@
.Nm g_clone_bio ,
.Nm g_destroy_bio ,
.Nm g_print_bio
.Nd "bio controlling functions"
.Nd "GEOM bio controlling functions"
.Sh SYNOPSIS
.In sys/bio.h
.In geom/geom.h
@ -45,30 +45,28 @@
.Ft void
.Fn g_print_bio "struct bio *bp"
.Sh DESCRIPTION
The
.Fa bio
structure is used by GEOM to describe I/O requests.
Most important fields of
A
.Fa struct bio
are described below:
is used by GEOM to describe I/O requests, its
most important fields are described below:
.Bl -tag -width ".Va bio_attribute"
.It Va bio_cmd
I/O request number.
I/O request command.
There are four I/O requests available in GEOM:
.Bl -tag -width BIO_GETATTR
.It Dv BIO_READ
Self explanatory.
A read request.
.It Dv BIO_WRITE
Self explanatory.
A write request.
.It Dv BIO_DELETE
Delete indicates that a certain range of data is no longer used and that
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
Inspect and manipulate out\-of\-band
attributes on a particular provider or path.
Attributes are named by ascii strings and are stored in the
.Va bio_attribute
@ -83,8 +81,8 @@ Available flags:
.Bl -tag -width BIO_GETATTR
.It Dv BIO_ERROR
Request failed (error value is stored in
.Va bio_error )
field.
.Va bio_error
field).
.It Dv BIO_DONE
Request finished.
.It Dv BIO_FLAG1
@ -95,7 +93,7 @@ Avaliable for private use.
.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.
Pointer to function which will be called when the request is finished.
.It Va bio_driver1
Private use by the callee (ie: the provider).
.It Va bio_driver2
@ -135,9 +133,9 @@ The
.Fn g_clone_bio
function allocates a new
.Vt bio
structure and copies those fields from the
structure and copies the following fields from the
.Vt bio
structure given as an argument to clone:
given as an argument to clone:
.Va bio_cmd ,
.Va bio_length ,
.Va bio_offset ,
@ -145,11 +143,13 @@ structure given as an argument to clone:
.Va bio_attribute .
The field
.Va bio_parent
in clone is set to source
in the clone points to the passed
.Vt bio
and the field
.Va bio_children
in parent is increased.
in the passed
.Vt bio
is incremented.
.Pp
This function should be used for every request which enters through
the provider of a particular geom and needs to be scheduled down.
@ -157,7 +157,7 @@ Proper order is:
.Pp
.Bl -enum -compact
.It
Clone
Clone the received
.Vt "struct bio" .
.It
Modify the clone.
@ -167,15 +167,23 @@ Schedule the clone on its own consumer.
.Pp
The
.Fn g_destroy_bio
function kills the given
function deallocates and destroys the given
.Vt bio
structure.
.Pp
The
.Fn g_print_bio
function prints informations about given
function prints information about the given
.Vt bio
structure.
structure (for debugging purposes).
.Sh RETURN VALUES
The
.Fn g_new_bio
and
.Fn g_clone_bio
functions return a pointer to the allocated
.Vt bio ,
or NULL if an error occurred.
.Sh EXAMPLES
Implementation of
.Dq Dv NULL Ns \-transformation ,

22
share/man/man9/g_consumer.9
View File

@ -38,34 +38,34 @@
.Ft void
.Fn g_destroy_consumer "struct g_consumer *cp"
.Sh DESCRIPTION
The GEOM consumer is the backdoor through which a geom connects to
A 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
function creates a new consumer on 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
Before using the new consumer, it has to be attached to a provider with
.Xr g_attach 9
function.
and opened with
.Xr g_access 9 .
.Pp
The
.Fn g_destroy_consumer
function destroys given consumer and cancels all related pending events.
function destroys the 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
The geom
.Fa gp
has to have
.Fa start
and
.Fa access
fields defined.
methods defined.
.It
The topology lock has to be held.
.El
@ -73,7 +73,7 @@ The topology lock has to be held.
.Fn g_destroy_consumer :
.Bl -item -offset indent
.It
The consumer can not be attached.
The consumer must not be attached to a provider.
.It
The access count has to be 0.
.It

37
share/man/man9/g_data.9
View File

@ -30,7 +30,7 @@
.Sh NAME
.Nm g_read_data ,
.Nm g_write_data
.Nd "read/write data through consumer"
.Nd "read/write data from/to GEOM consumer"
.Sh SYNOPSIS
.In geom/geom.h
.Ft "void *"
@ -40,19 +40,19 @@
.Sh DESCRIPTION
The
.Fn g_read_data
reads
function reads
.Fa length
bytes of data from a provider through attached consumer
.Fa cp
bytes of data from the provider attached to consumer
.Fa cp ,
starting at offset
.Fa offset .
Memory for data is allocated inside
The buffer returned from
.Fn g_read_data
with
is allocated with
.Fn g_malloc ,
and should therefor be freed by the caller with the
so it should be freed by the caller with
.Fn g_free
function after use.
after use.
If the operation fails, an error value will be stored in the
.Fa error
argument if it is not
@ -60,16 +60,17 @@ argument if it is not
.Pp
The
.Fn g_write_data
writes
function writes
.Fa length
bytes of data from address
bytes of data from the buffer pointed to by
.Fa ptr
to the provider attached to consumer
.Fa cp ,
starting at offset
.Fa offset
to a provider through the attached consumer
.Fa cp .
.Fa offset .
.Sh RESTRICTIONS/CONDITIONS
Length of data should be a multiple of the sectorsize for the provider
.Fa length
should be a multiple of the provider's sectorsize
and less than or equal to
.Dv DFLTPHYS
.Dv ( DFLTPHYS is defined in
@ -77,17 +78,19 @@ and less than or equal to
.Pp
The topology lock must not be held.
.Sh RETURN VALUES
The
.Fn g_read_data
returns a pointer to the read data or
function returns a pointer to a data buffer or
.Dv NULL
if an error occured.
In that case an error value is stored in the
.Fa error
argument unsless it is
argument unless it is
.Dv NULL .
.Pp
The
.Fn g_write_data
returns the value 0 if successful; otherwise an error code is returned.
function returns 0 if successful; otherwise an error code is returned.
.Sh ERRORS
Possible errors:
.Bl -tag -width Er

51
share/man/man9/g_event.9
View File

@ -31,7 +31,7 @@
.Nm g_post_event ,
.Nm g_waitfor_event ,
.Nm g_cancel_event
.Nd "events management"
.Nd "GEOM events management"
.Sh SYNOPSIS
.In geom/geom.h
.Ft int
@ -41,34 +41,33 @@
.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.
The GEOM framework has its own event queue to inform classes about important
events.
The event queue can be also used by GEOM classes themselves, for example
to work around some restrictions in the I/O path, where sleeping, heavy weight
tasks, etc. are not permitted.
.Pp
The
.Fn g_post_event
function tells GEOM to call function
function tells the GEOM framework to call function
.Fa func
with argument
.Fa arg
from the event queue.
The
.Fa flag
argument is a flag for
argument is passed to
.Xr malloc 9
that should be used by GEOM.
Only the flags
for memory allocations inside of
.Fn g_post_event .
The only allowed flags are
.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.
and
.Dv M_NOWAIT .
The rest of the arguments are used as references to identify the event.
An event can be canceled by using any of the given references as an
argument to
.Fn g_cancel_event .
The list of references has to end with a
.Dv NULL
value.
@ -82,7 +81,7 @@ It waits until the event is finished or canceled and then returns.
.Pp
The
.Fn g_cancel_event
function cancels event(s) identified by
function cancels all event(s) identified by
.Fa ref .
Cancellation is equivalent to calling the requested function
with requested arguments and argument
@ -128,24 +127,28 @@ in a deadlock.
.Fn g_post_event
and
.Fn g_waitfor_event
returns the value 0 if successful; otherwise an error code is returned.
return 0 if successful; otherwise an error code is returned.
.Sh ERRORS
Possible errors for
Possible errors for the
.Fn g_post_event
function:
.Bl -tag -width Er
.It Bq Er ENOMEM
There was insufficient memory.
The
.Fa flag
argument was set to M_NOWAIT and there was insufficient memory.
.El
.Pp
Possible errors for
Possible errors for the
.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.
The
.Fa flag
argument was set to M_NOWAIT and there was insufficient memory.
.El
.Sh EXAMPLES
Example of a function called from the event queue.

44
share/man/man9/g_provider.9
View File

@ -41,7 +41,7 @@
.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 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.
@ -49,33 +49,30 @@ 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
function creates a new provider on given geom
.Fa gp .
The provider name is created in a printf\-like way from the rest of
The name of the provider, which will appear as device in devfs, 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:
After creation, the caller has to set the provider's
.Va mediasize
and
.Va sectorsize
as well as other initialization things should be done first.
.Va sectorsize ,
as well as other desired initializations, and then call
.Fn g_error_provider
to reset the provider's error, which is initially set to
.Er ENXIO .
.Pp
The
.Fn g_destroy_provider
function destroys the given provider, cancels all related pending events and
removes corresponding devfs entry.
removes the 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
function is used to set the provider's error value.
If set to a nonzero, all I/O requests will be denied,
as well as increasing its access count will not be possible (error
.Fa error
will be returned).
.Sh RESTRICTIONS/CONDITIONS
@ -84,11 +81,13 @@ will be returned).
.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.
with the same name, which is a programmer error.
.It
The geom related to the created provider must have
The geom
.Fa gp
has to have a
.Fa start
field defined.
method defined.
.It
The topology lock has to be held.
.El
@ -96,15 +95,16 @@ The topology lock has to be held.
.Fn g_destroy_provider :
.Bl -item -offset indent
.It
No consumers have to be attached.
The provider must not have consumers attached.
.It
The access count has to be 0.
.It
The topology lock has to be held.
.El
.Sh RETURN VALUES
The
.Fn g_new_providerf
returns a pointer to the newly created provider.
function returns a pointer to the newly created provider.
.Sh EXAMPLES
Create an example provider, set its parameters and make it usable.
.Bd -literal -offset indent

4
share/man/man9/g_provider_by_name.9
View File

@ -29,7 +29,7 @@
.Os
.Sh NAME
.Nm g_provider_by_name
.Nd "find provider with given name"
.Nd "find GEOM provider with given name"
.Sh SYNOPSIS
.In geom/geom.h
.Ft "struct g_provider *"
@ -37,7 +37,7 @@
.Sh DESCRIPTION
The
.Fn g_provider_by_name
searches for a provider called
function searches for a provider called
.Fa name
and returns the structure
.Fa g_provider

20
share/man/man9/g_wither_geom.9
View File

@ -29,7 +29,7 @@
.Os
.Sh NAME
.Nm g_wither_geom
.Nd "destroy geom and releated providers and consumers when you get a chance"
.Nd "destroy geom and related providers and consumers when you get a chance"
.Sh SYNOPSIS
.In geom/geom.h
.Ft void
@ -40,12 +40,12 @@ The
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
GEOM sets an error on each provider of the given geom (in the
orphaning process) and waits for a chance to destroy the geom.
If the access count of any possessed consumer goes to 0, the consumer will be
detached and destroyed automatically.
If last consumer attached to any possesed provider will be detached,
provider will be destroyed.
If the last consumer attached to any possessed provider will be detached,
the provider will be destroyed.
If there are no more providers nor consumers, the geom will be
destroyed.
.Pp
@ -58,10 +58,10 @@ 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.
function gives no guarantee that the geom will be immediately destroyed, mostly
because the access counts of the geom's consumers and providers may not be 0.
That is why calling this function for every geom from a given class is not enough
to be sure that the class can be unloaded.
.Sh RESTRICTIONS/CONDITIONS
The argument
.Fa error