xref: /freebsd/lib/libgeom/libgeom.3 (revision 195ebc7e9e4b129de810833791a19dfb4349d6a9)
1.\" Copyright (c) 2003 Poul-Henning Kamp
2.\" Copyright (c) 2007 Pawel Jakub Dawidek <pjd@FreeBSD.org>
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\" 3. The names of the authors may not be used to endorse or promote
14.\"    products derived from this software without specific prior written
15.\"    permission.
16.\"
17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27.\" SUCH DAMAGE.
28.\"
29.\" $FreeBSD$
30.\"
31.Dd September 8, 2008
32.Dt LIBGEOM 3
33.Os
34.Sh NAME
35.Nm geom_stats_open ,
36.Nm geom_stats_close ,
37.Nm geom_stats_resync ,
38.Nm geom_stats_snapshot_get ,
39.Nm geom_stats_snapshot_free ,
40.Nm geom_stats_snapshot_timestamp ,
41.Nm geom_stats_snapshot_reset ,
42.Nm geom_stats_snapshot_next ,
43.Nm gctl_get_handle ,
44.Nm gctl_ro_param ,
45.Nm gctl_rw_param ,
46.Nm gctl_issue ,
47.Nm gctl_free ,
48.Nm gctl_dump ,
49.Nm g_open ,
50.Nm g_close ,
51.Nm g_mediasize ,
52.Nm g_sectorsize ,
53.Nm g_flush ,
54.Nm g_delete ,
55.Nm g_device_path ,
56.Nm g_get_ident ,
57.Nm g_get_name ,
58.Nm g_open_by_ident ,
59.Nm g_providername
60.Nd userland API library for kernel GEOM subsystem
61.Sh LIBRARY
62.Lb libgeom
63.Sh SYNOPSIS
64.In libgeom.h
65.Ss "Statistics Functions"
66.Ft void
67.Fn geom_stats_close void
68.Ft int
69.Fn geom_stats_open void
70.Ft void
71.Fn geom_stats_resync void
72.Ft "void *"
73.Fn geom_stats_snapshot_get void
74.Ft void
75.Fn geom_stats_snapshot_free "void *arg"
76.Ft void
77.Fn geom_stats_snapshot_timestamp "void *arg" "struct timespec *tp"
78.Ft void
79.Fn geom_stats_snapshot_reset "void *arg"
80.Ft "struct devstat *"
81.Fn geom_stats_snapshot_next "void *arg"
82.Ss "Control Functions"
83.Ft "struct gctl_req *"
84.Fn gctl_get_handle "void"
85.Ft void
86.Fn gctl_ro_param "struct gctl_req *req" "const char *name" "int len" "const void *value"
87.Ft void
88.Fn gctl_rw_param "struct gctl_req *req" "const char *name" "int len" "void *value"
89.Ft "const char *"
90.Fn gctl_issue "struct gctl_req *req"
91.Ft void
92.Fn gctl_free "struct gctl_req *req"
93.Ft void
94.Fn gctl_dump "struct gctl_req *req" "FILE *f"
95.Ss "Utility Functions"
96.Ft int
97.Fn g_open "const char *name" "int dowrite"
98.Ft int
99.Fn g_close "int fd"
100.Ft off_t
101.Fn g_mediasize "int fd"
102.Ft ssize_t
103.Fn g_sectorsize "int fd"
104.Ft int
105.Fn g_flush "int fd"
106.Ft int
107.Fn g_delete "int fd" "off_t offset" "off_t length"
108.Ft "char *"
109.Fn g_device_path "const char *devpath"
110.Ft int
111.Fn g_get_ident "int fd" "char *ident" "size_t size"
112.Ft int
113.Fn g_get_name "const char *ident" "char *name" "size_t size"
114.Ft int
115.Fn g_open_by_ident "const char *ident" "int dowrite" "char *name" "size_t size"
116.Ft "char *"
117.Fn g_providername "int fd"
118.Sh DESCRIPTION
119The
120.Nm geom
121library contains the official and publicized API for
122interacting with the GEOM subsystem in the kernel.
123.Ss "Statistics Functions"
124GEOM collects statistics data for all consumers and providers, but does
125not perform any normalization or presentation on the raw data, this is
126left as an exercise for user-land presentation utilities.
127.Pp
128The
129.Fn geom_stats_open
130and
131.Fn geom_stats_close
132functions open and close the necessary pathways to access the raw
133statistics information in the kernel.
134These functions are likely to
135open one or more files and cache the file descriptors locally.
136The
137.Fn geom_stats_open
138function returns zero on success, and sets
139.Va errno
140if not.
141.Pp
142The
143.Fn geom_stats_resync
144function will check if more statistics collection points have been
145added in the kernel since
146.Fn geom_stats_open
147or the previous call to
148.Fn geom_stats_resync .
149.Pp
150The
151.Fn geom_stats_snapshot_get
152function
153will acquire a snapshot of the raw data from the kernel, and while a
154reasonable effort is made to make this snapshot as atomic and consistent
155as possible, no guarantee is given that it will actually be so.
156The snapshot must be freed again using the
157.Fn geom_stats_snapshot_free
158function.
159The
160.Fn geom_stats_snapshot_get
161function returns
162.Dv NULL
163on failure.
164.Pp
165The
166.Fn geom_stats_snapshot_timestamp
167function
168provides access to the timestamp acquired in the snapshot.
169.Pp
170The
171.Fn geom_stats_snapshot_reset
172and
173.Fn geom_stats_snapshot_next
174functions
175provide an iterator over the statistics slots in the snapshot.
176The
177.Fn geom_stats_snapshot_reset
178function
179forces the internal pointer in the snapshot back to before the first item.
180The
181.Fn geom_stats_snapshot_next
182function
183returns the next item, and
184.Dv NULL
185if there are no more items in the snapshot.
186.Ss "Control Functions"
187The
188.Fn gctl_*
189functions are used to send requests to GEOM classes.
190In order for a GEOM
191class to actually be able to receive these requests, it must have defined a
192"ctlreq" method.
193.Pp
194A
195.Vt "struct gctl_req *" ,
196obtained with
197.Fn gctl_get_handle ,
198can hold any number of parameters, which must be added to it with
199.Fn gctl_ro_param
200(for read-only parameters) or
201.Fn gctl_rw_param
202(for read/write parameters).
203.Pp
204Both
205.Fn gctl_ro_param
206and
207.Fn gctl_rw_param
208take a string
209.Fa name ,
210which is used to identify the parameter, and a
211.Fa value ,
212which contains, in the read-only case, the data to be passed to the
213GEOM class, or, in the read/write case, a pointer to preallocated memory
214that the GEOM class should fill with the desired data.
215If
216.Fa len
217is negative, it is assumed that
218.Fa value
219is an
220.Tn ASCII
221string and the actual length is taken from the string length of
222.Fa value ;
223otherwise it must hold the size of
224.Fa value .
225.Pp
226A parameter with a
227.Fa name
228containing the string
229.Qq Li class
230is mandatory for each request, and the
231corresponding
232.Fa value
233must hold the name of the GEOM class where the request should be sent to.
234.Pp
235Also mandatory for each request is a parameter with a
236.Fa name
237called
238.Qq Li verb ,
239and the corresponding
240.Fa value
241needs to hold the command string that the GEOM class should react upon.
242.Pp
243Once all desired parameters are filled in, the request must be sent to
244the GEOM subsystem with
245.Fn gctl_issue ,
246which returns
247.Dv NULL
248on success, or a string containing the error message
249on failure.
250.Pp
251After the request is finished, the allocated memory should be released with
252.Fn gctl_free .
253.Pp
254The
255.Fn gctl_dump
256function
257can be used to format the contents of
258.Fa req
259to the open file handle pointed to by
260.Fa f ,
261for debugging purposes.
262.Pp
263Error handling for the control functions is postponed until the call
264to
265.Fn gctl_issue ,
266which returns
267.Dv NULL
268on success, or an error message corresponding to the
269first error which happened.
270.Ss "Utility Functions"
271The
272.Fn g_*
273functions are used to communicate with GEOM providers.
274.Pp
275The
276.Fn g_open
277function opens the given provider and returns file descriptor number, which can
278be used with other functions.
279The
280.Fa dowrite
281argument indicates if operations that modify the provider (like
282.Fn g_flush
283or
284.Fn g_delete )
285are going to be called.
286.Pp
287The
288.Fn g_close
289function closes the provider.
290.Pp
291The
292.Fn g_mediasize
293function returns size of the given provider.
294.Pp
295The
296.Fn g_sectorsize
297function returns sector size of the given provider.
298.Pp
299The
300.Fn g_flush
301function sends
302.Dv BIO_FLUSH
303request to flush write cache of the provider.
304.Pp
305The
306.Fn g_delete
307function tells the provider that the given data range is no longer used.
308.Pp
309The
310.Fn g_device_path
311function returns the full path to a provider given a partial or full path to the
312device node.
313If the device can not be found or is not a valid geom provider, NULL is
314returned.
315.Pp
316The
317.Fn g_get_ident
318function returns provider's fixed and unique identifier.
319The
320.Fa ident
321argument should be at least
322.Dv DISK_IDENT_SIZE
323big.
324.Pp
325The
326.Fn g_get_name
327function returns name of the provider, which identifier is equal to the
328.Fa ident
329string.
330.Pp
331The
332.Fn g_open_by_ident
333function opens provider using its ident, unlike
334.Fn g_open
335which uses provider's name.
336If the
337.Fa name
338argument is not
339.Dv NULL ,
340the function will store provider's name there.
341.Pp
342The
343.Fn g_providername
344function returns the provider name of an open file descriptor.
345If the file descriptor does not point to a valid geom provider, NULL is
346returned.
347.Pp
348All functions except
349.Fn g_providername
350and
351.Fn g_device_path
352return a value greater than or equal to
353.Va 0
354on success or
355.Va -1
356on failure.
357.Sh EXAMPLES
358Create a request that is to be sent to the CCD class, and tell
359it to destroy a specific geom:
360.Bd -literal -offset indent
361H = gctl_get_handle();
362gctl_ro_param(H, "verb", -1, "destroy geom");
363gctl_ro_param(H, "class", -1, "CCD");
364sprintf(buf, "ccd%d", ccd);
365gctl_ro_param(H, "geom", -1, buf);
366errstr = gctl_issue(H);
367if (errstr != NULL)
368    err(1, "could not destroy ccd: %s", errstr);
369gctl_free(H);
370.Ed
371.Sh SEE ALSO
372.Pa http://ezine.daemonnews.org/200308/blueprints.html
373.Sh HISTORY
374The
375.Nm geom
376library appeared in
377.Fx 5.1 .
378.Sh AUTHORS
379.An Poul-Henning Kamp Aq phk@FreeBSD.org
380.An Lukas Ertl Aq le@FreeBSD.org
381.An Pawel Jakub Dawidek pjd@FreeBSD.org
382