From 6f39ea8888c644f4f6a4099c08a1cdab65b5d274 Mon Sep 17 00:00:00 2001 From: Ruslan Ermilov Date: Tue, 6 Jul 2004 08:21:12 +0000 Subject: [PATCH] Tiny markup fixes. --- share/man/man9/DECLARE_GEOM_CLASS.9 | 17 ++++++----- share/man/man9/g_access.9 | 11 ++++--- share/man/man9/g_attach.9 | 2 +- share/man/man9/g_bio.9 | 47 ++++++++++++++++++----------- share/man/man9/g_consumer.9 | 9 +++--- share/man/man9/g_data.9 | 17 ++++++++--- share/man/man9/g_event.9 | 14 ++++++--- share/man/man9/g_geom.9 | 18 +++++++---- share/man/man9/g_provider.9 | 14 ++++++--- share/man/man9/g_provider_by_name.9 | 8 +++-- share/man/man9/g_wither_geom.9 | 2 +- 11 files changed, 99 insertions(+), 60 deletions(-) diff --git a/share/man/man9/DECLARE_GEOM_CLASS.9 b/share/man/man9/DECLARE_GEOM_CLASS.9 index 4972caa9e851..7c21587338d4 100644 --- a/share/man/man9/DECLARE_GEOM_CLASS.9 +++ b/share/man/man9/DECLARE_GEOM_CLASS.9 @@ -38,7 +38,9 @@ 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. +Typical examples are: MBR disk partition, +.Bx +disklabel and RAID5 classes. .Fn DECLARE_GEOM_CLASS can be used both for compiled in and loaded as .Xr kld 4 @@ -48,11 +50,11 @@ The arguments to .Fn DECLARE_GEOM_CLASS are: .Bl -inset -offset indent -.It Em class +.It Fa class is the .Vt g_class structure which describes a GEOM class. -.It Em mod_name +.It Fa mod_name is a kernel module name (not a class name!). .El .Pp @@ -60,15 +62,16 @@ Structure .Vt g_class contains data describing the class. They are: -.Bl -inset -offset indent +.Bl -tag -offset indent -width 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 +.Pf non- Dv NULL it is called in three situations: -.Bl -dash -offset indent -compact +.Pp +.Bl -dash -compact .It On class activation, all existing providers are offered for tasting. .It @@ -97,12 +100,10 @@ If this field is not set, the class can not be unloaded. 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 diff --git a/share/man/man9/g_access.9 b/share/man/man9/g_access.9 index a7f501800b7e..5bb8d5261f6e 100644 --- a/share/man/man9/g_access.9 +++ b/share/man/man9/g_access.9 @@ -25,7 +25,7 @@ .\" $FreeBSD$ .\" .Dd January 16, 2004 -.Dt g_access 9 +.Dt G_ACCESS 9 .Os .Sh NAME .Nm g_access @@ -52,7 +52,7 @@ A provider's access count is the sum of the access counts of all attached consumers. .Pp After attaching a consumer to a provider with -.Fn g_attach , +.Xr g_attach 9 , the .Fn g_access function has to be called on the consumer before starting I/O requests. @@ -61,16 +61,17 @@ 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 +No-operation is not permitted .Fa ( dcr = .Fa dcw = .Fa dce = -.Va 0 ) . +.Li 0 ) . .Pp -The provider's geom must have an access method defined (e.g.\& gp->access). +The provider's geom must have an access method defined (e.g., +.Va gp->access ) . .Pp The topology lock has to be held. .Sh RETURN VALUES diff --git a/share/man/man9/g_attach.9 b/share/man/man9/g_attach.9 index 0cf8661095d0..96ba0ebc4402 100644 --- a/share/man/man9/g_attach.9 +++ b/share/man/man9/g_attach.9 @@ -25,7 +25,7 @@ .\" $FreeBSD$ .\" .Dd January 16, 2004 -.Dt g_attach 9 +.Dt G_ATTACH 9 .Os .Sh NAME .Nm g_attach , diff --git a/share/man/man9/g_bio.9 b/share/man/man9/g_bio.9 index ce01f306a03c..5c0751be8fae 100644 --- a/share/man/man9/g_bio.9 +++ b/share/man/man9/g_bio.9 @@ -25,7 +25,7 @@ .\" $FreeBSD$ .\" .Dd January 16, 2004 -.Dt g_bio 9 +.Dt G_BIO 9 .Os .Sh NAME .Nm g_new_bio , @@ -46,14 +46,14 @@ .Fn g_print_bio "struct bio *bp" .Sh DESCRIPTION A -.Fa struct bio +.Vt "struct bio" 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 command. There are four I/O requests available in GEOM: -.Bl -tag -width BIO_GETATTR +.Bl -tag -width ".Dv BIO_GETATTR" .It Dv BIO_READ A read request. .It Dv BIO_WRITE @@ -78,7 +78,7 @@ Offset into provider. Pointer to data buffer. .It Va bio_flags Available flags: -.Bl -tag -width BIO_GETATTR +.Bl -tag -width ".Dv BIO_GETATTR" .It Dv BIO_ERROR Request failed (error value is stored in .Va bio_error @@ -91,36 +91,45 @@ Available for private use. Available for private use. .El .It Va bio_error -Error value when BIO_ERROR is set. +Error value when +.Dv BIO_ERROR +is set. .It Va bio_done Pointer to function which will be called when the request is finished. .It Va bio_driver1 -Private use by the callee (ie: the provider). +Private use by the callee (i.e., the provider). .It Va bio_driver2 -Private use by the callee (ie: the provider). +Private use by the callee (i.e., the provider). .It Va bio_caller1 -Private use by the caller (ie: the consumer). +Private use by the caller (i.e., the consumer). .It Va bio_caller2 -Private use by the caller (ie: the consumer). +Private use by the caller (i.e., the consumer). .It Va bio_attribute -Attribute string for BIO_GETATTR request. +Attribute string for +.Dv 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). +field) (typically read-only for a class). .It Va bio_to -Destination provider (typically read\-only for a class). +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). +Number of +.Vt bio +clones (typically read-only for a class). .It Va bio_inbed -Number of finished bio clones. +Number of finished +.Vt bio +clones. .It Va bio_parent -Pointer to parent bio. +Pointer to parent +.Vt bio . .El .Pp The @@ -183,13 +192,15 @@ and .Fn g_clone_bio functions return a pointer to the allocated .Vt bio , -or NULL if an error occurred. +or +.Dv NULL +if an error occurred. .Sh EXAMPLES Implementation of -.Dq Dv NULL Ns \-transformation , +.Dq Dv NULL Ns -transformation , meaning that an I/O request is cloned and scheduled down without any modifications. -Let's assume that field +Let us assume that field .Va ex_consumer in structure .Vt example_softc diff --git a/share/man/man9/g_consumer.9 b/share/man/man9/g_consumer.9 index 90de11fb01b7..aa1e33a02856 100644 --- a/share/man/man9/g_consumer.9 +++ b/share/man/man9/g_consumer.9 @@ -25,7 +25,7 @@ .\" $FreeBSD$ .\" .Dd January 16, 2004 -.Dt g_consumer 9 +.Dt G_CONSUMER 9 .Os .Sh NAME .Nm g_new_consumer , @@ -54,7 +54,6 @@ The .Fn g_destroy_consumer 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 @@ -62,9 +61,9 @@ This function is the last stage of killing an unwanted consumer. The geom .Fa gp has to have -.Fa start +.Va start and -.Fa access +.Va access methods defined. .It The topology lock has to be held. @@ -80,7 +79,9 @@ The access count has to be 0. The topology lock has to be held. .El .Sh RETURN VALUES +The .Fn g_new_consumer +function returns a pointer to the newly created consumer. .Sh EXAMPLES Create consumer, attach it to given provider, gain read access and clean up. diff --git a/share/man/man9/g_data.9 b/share/man/man9/g_data.9 index 37292720eab8..6b9441ea4486 100644 --- a/share/man/man9/g_data.9 +++ b/share/man/man9/g_data.9 @@ -25,7 +25,7 @@ .\" $FreeBSD$ .\" .Dd January 16, 2004 -.Dt g_data 9 +.Dt G_DATA 9 .Os .Sh NAME .Nm g_read_data , @@ -34,9 +34,13 @@ .Sh SYNOPSIS .In geom/geom.h .Ft "void *" -.Fn g_read_data "struct g_consumer *cp" "off_t offset" "off_t length" "int *error" +.Fo g_read_data +.Fa "struct g_consumer *cp" "off_t offset" "off_t length" "int *error" +.Fc .Ft int -.Fn g_write_data "struct g_consumer *cp" "off_t offset" "void *ptr" "off_t length" +.Fo g_write_data +.Fa "struct g_consumer *cp" "off_t offset" "void *ptr" "off_t length" +.Fc .Sh DESCRIPTION The .Fn g_read_data @@ -69,11 +73,14 @@ to the provider attached to consumer starting at offset .Fa offset . .Sh RESTRICTIONS/CONDITIONS +The .Fa length +argument should be a multiple of the provider's sectorsize and less than or equal to .Dv DFLTPHYS -.Dv ( DFLTPHYS is defined in +.Dv ( DFLTPHYS +is defined in .In sys/param.h ) . .Pp The topology lock must not be held. @@ -95,7 +102,7 @@ function returns 0 if successful; otherwise an error code is returned. Possible errors: .Bl -tag -width Er .It Bq Er EIO -Can not read data. +Cannot read data. .El .Sh SEE ALSO .Xr geom 4 , diff --git a/share/man/man9/g_event.9 b/share/man/man9/g_event.9 index 42a2e2fa614b..0cb574dd3e03 100644 --- a/share/man/man9/g_event.9 +++ b/share/man/man9/g_event.9 @@ -25,7 +25,7 @@ .\" $FreeBSD$ .\" .Dd January 16, 2004 -.Dt g_event 9 +.Dt G_EVENT 9 .Os .Sh NAME .Nm g_post_event , @@ -120,13 +120,15 @@ value. .It The .Fn g_waitfor_event -function can not be called from an event, since doing so would result +function cannot be called from an event, since doing so would result in a deadlock. .El .Sh RETURN VALUES +The .Fn g_post_event and .Fn g_waitfor_event +functions return 0 if successful; otherwise an error code is returned. .Sh ERRORS Possible errors for the @@ -136,7 +138,9 @@ function: .It Bq Er ENOMEM The .Fa flag -argument was set to M_NOWAIT and there was insufficient memory. +argument was set to +.Dv M_NOWAIT +and there was insufficient memory. .El .Pp Possible errors for the @@ -148,7 +152,9 @@ The event was canceled. .It Bq Er ENOMEM The .Fa flag -argument was set to M_NOWAIT and there was insufficient memory. +argument was set to +.Dv M_NOWAIT +and there was insufficient memory. .El .Sh EXAMPLES Example of a function called from the event queue. diff --git a/share/man/man9/g_geom.9 b/share/man/man9/g_geom.9 index ff21c16b31d6..19c491098018 100644 --- a/share/man/man9/g_geom.9 +++ b/share/man/man9/g_geom.9 @@ -25,7 +25,7 @@ .\" $FreeBSD$ .\" .Dd January 16, 2004 -.Dt g_geom 9 +.Dt G_GEOM 9 .Os .Sh NAME .Nm g_new_geomf , @@ -43,7 +43,9 @@ The geom (do not confuse with .Dq GEOM ) is an instance of a GEOM class. -For example: in a typical i386 FreeBSD system, there will be one geom +For example: in a typical i386 +.Fx +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. @@ -53,7 +55,9 @@ The .Fn g_new_geomf function creates a new geom, which will be an instance of the class .Fa mp . -The geom's name is created in a printf-like way from the rest of the arguments. +The geom's name is created in a +.Xr printf 3 Ns +-like way from the rest of the arguments. .Pp The .Fn g_destroy_geom @@ -65,7 +69,7 @@ The structure 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 +.Bl -tag -offset indent -width indent .It Vt "g_start_t *" Va start Pointer to a function used for I/O processing. .It Vt "g_spoiled_t *" Va spoiled @@ -105,14 +109,16 @@ The topology lock has to be held. .Fn g_destroy_geom : .Bl -item -offset indent .It -The geom can not posses any providers. +The geom cannot posses any providers. .It -The geom can not posses any consumers. +The geom cannot posses any consumers. .It The topology lock has to be held. .El .Sh RETURN VALUES +The .Fn g_new_geomf +function returns a pointer to the newly created geom. .Sh EXAMPLES Create an example geom. diff --git a/share/man/man9/g_provider.9 b/share/man/man9/g_provider.9 index 914338b7e716..05e4addabf36 100644 --- a/share/man/man9/g_provider.9 +++ b/share/man/man9/g_provider.9 @@ -25,7 +25,7 @@ .\" $FreeBSD$ .\" .Dd January 16, 2004 -.Dt g_provider 9 +.Dt G_PROVIDER 9 .Os .Sh NAME .Nm g_new_providerf , @@ -43,16 +43,20 @@ .Sh DESCRIPTION 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. +.Dq a disk-like thing which appears in Pa /dev +\[en] 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 on given geom .Fa gp . -The name of the provider, which will appear as device in devfs, is created -in a printf-like way from the rest of +The name of the provider, which will appear as device in +.Xr devfs 5 , +is created +in a +.Xr printf 3 Ns +-like way from the rest of the arguments. After creation, the caller has to set the provider's .Va mediasize diff --git a/share/man/man9/g_provider_by_name.9 b/share/man/man9/g_provider_by_name.9 index 7a5bb0c63b1b..58da421a243d 100644 --- a/share/man/man9/g_provider_by_name.9 +++ b/share/man/man9/g_provider_by_name.9 @@ -25,7 +25,7 @@ .\" $FreeBSD$ .\" .Dd January 16, 2004 -.Dt g_provider_by_name 9 +.Dt G_PROVIDER_BY_NAME 9 .Os .Sh NAME .Nm g_provider_by_name @@ -40,18 +40,20 @@ The function searches for a provider called .Fa name and returns the structure -.Fa g_provider +.Vt g_provider bound to it. Argument .Fa name -should be a name, not a full path (ie. +should be a name, not a full path (i.e., .Dq Pa da0 , instead of .Dq Pa /dev/da0 ) . .Sh RESTRICTIONS/CONDITIONS The topology lock has to be held. .Sh RETURN VALUES +The .Fn g_provider_by_name +function returns a pointer to the provider called .Fa name or diff --git a/share/man/man9/g_wither_geom.9 b/share/man/man9/g_wither_geom.9 index 9f22a79208e1..2c4b10eeaa34 100644 --- a/share/man/man9/g_wither_geom.9 +++ b/share/man/man9/g_wither_geom.9 @@ -25,7 +25,7 @@ .\" $FreeBSD$ .\" .Dd January 16, 2004 -.Dt g_wither_geom 9 +.Dt G_WITHER_GEOM 9 .Os .Sh NAME .Nm g_wither_geom