diff options
Diffstat (limited to 'share/man/man9/g_provider.9')
| -rw-r--r-- | share/man/man9/g_provider.9 | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/share/man/man9/g_provider.9 b/share/man/man9/g_provider.9 new file mode 100644 index 000000000000..05e4addabf36 --- /dev/null +++ b/share/man/man9/g_provider.9 @@ -0,0 +1,145 @@ +.\" +.\" 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 +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 +\[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 +.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 +and +.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 the corresponding devfs entry. +.Pp +The +.Fn g_error_provider +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 +.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 a programmer error. +.It +The geom +.Fa gp +has to have a +.Fa start +method defined. +.It +The topology lock has to be held. +.El +.Pp +.Fn g_destroy_provider : +.Bl -item -offset indent +.It +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 +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 +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(); + pp->mediasize = 65536; + pp->sectorsize = 512; + g_error_provider(pp, 0); + + return (pp); +} +.Ed +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.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 . |