xref: /freebsd/lib/libgeom/libgeom.3 (revision 1fdeb1651cdf0032c6cf77ee8bd3fe889ca3d074)
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 December 4, 2010
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_stripeoffset ,
54.Nm g_stripesize ,
55.Nm g_flush ,
56.Nm g_delete ,
57.Nm g_device_path ,
58.Nm g_get_ident ,
59.Nm g_get_name ,
60.Nm g_open_by_ident ,
61.Nm g_providername
62.Nd userland API library for kernel GEOM subsystem
63.Sh LIBRARY
64.Lb libgeom
65.Sh SYNOPSIS
66.In libgeom.h
67.Ss "Statistics Functions"
68.Ft void
69.Fn geom_stats_close void
70.Ft int
71.Fn geom_stats_open void
72.Ft void
73.Fn geom_stats_resync void
74.Ft "void *"
75.Fn geom_stats_snapshot_get void
76.Ft void
77.Fn geom_stats_snapshot_free "void *arg"
78.Ft void
79.Fn geom_stats_snapshot_timestamp "void *arg" "struct timespec *tp"
80.Ft void
81.Fn geom_stats_snapshot_reset "void *arg"
82.Ft "struct devstat *"
83.Fn geom_stats_snapshot_next "void *arg"
84.Ss "Control Functions"
85.Ft "struct gctl_req *"
86.Fn gctl_get_handle "void"
87.Ft void
88.Fn gctl_ro_param "struct gctl_req *req" "const char *name" "int len" "const void *value"
89.Ft void
90.Fn gctl_rw_param "struct gctl_req *req" "const char *name" "int len" "void *value"
91.Ft "const char *"
92.Fn gctl_issue "struct gctl_req *req"
93.Ft void
94.Fn gctl_free "struct gctl_req *req"
95.Ft void
96.Fn gctl_dump "struct gctl_req *req" "FILE *f"
97.Ss "Utility Functions"
98.Ft int
99.Fn g_open "const char *name" "int dowrite"
100.Ft int
101.Fn g_close "int fd"
102.Ft off_t
103.Fn g_mediasize "int fd"
104.Ft ssize_t
105.Fn g_sectorsize "int fd"
106.Ft ssize_t
107.Fn g_stripeoffset "int fd"
108.Ft ssize_t
109.Fn g_stripesize "int fd"
110.Ft int
111.Fn g_flush "int fd"
112.Ft int
113.Fn g_delete "int fd" "off_t offset" "off_t length"
114.Ft "char *"
115.Fn g_device_path "const char *devpath"
116.Ft int
117.Fn g_get_ident "int fd" "char *ident" "size_t size"
118.Ft int
119.Fn g_get_name "const char *ident" "char *name" "size_t size"
120.Ft int
121.Fn g_open_by_ident "const char *ident" "int dowrite" "char *name" "size_t size"
122.Ft "char *"
123.Fn g_providername "int fd"
124.Sh DESCRIPTION
125The
126.Nm geom
127library contains the official and publicized API for
128interacting with the GEOM subsystem in the kernel.
129.Ss "Statistics Functions"
130GEOM collects statistics data for all consumers and providers, but does
131not perform any normalization or presentation on the raw data, this is
132left as an exercise for user-land presentation utilities.
133.Pp
134The
135.Fn geom_stats_open
136and
137.Fn geom_stats_close
138functions open and close the necessary pathways to access the raw
139statistics information in the kernel.
140These functions are likely to
141open one or more files and cache the file descriptors locally.
142The
143.Fn geom_stats_open
144function returns zero on success, and sets
145.Va errno
146if not.
147.Pp
148The
149.Fn geom_stats_resync
150function will check if more statistics collection points have been
151added in the kernel since
152.Fn geom_stats_open
153or the previous call to
154.Fn geom_stats_resync .
155.Pp
156The
157.Fn geom_stats_snapshot_get
158function
159will acquire a snapshot of the raw data from the kernel, and while a
160reasonable effort is made to make this snapshot as atomic and consistent
161as possible, no guarantee is given that it will actually be so.
162The snapshot must be freed again using the
163.Fn geom_stats_snapshot_free
164function.
165The
166.Fn geom_stats_snapshot_get
167function returns
168.Dv NULL
169on failure.
170.Pp
171The
172.Fn geom_stats_snapshot_timestamp
173function
174provides access to the timestamp acquired in the snapshot.
175.Pp
176The
177.Fn geom_stats_snapshot_reset
178and
179.Fn geom_stats_snapshot_next
180functions
181provide an iterator over the statistics slots in the snapshot.
182The
183.Fn geom_stats_snapshot_reset
184function
185forces the internal pointer in the snapshot back to before the first item.
186The
187.Fn geom_stats_snapshot_next
188function
189returns the next item, and
190.Dv NULL
191if there are no more items in the snapshot.
192.Ss "Control Functions"
193The
194.Fn gctl_*
195functions are used to send requests to GEOM classes.
196In order for a GEOM
197class to actually be able to receive these requests, it must have defined a
198"ctlreq" method.
199.Pp
200A
201.Vt "struct gctl_req *" ,
202obtained with
203.Fn gctl_get_handle ,
204can hold any number of parameters, which must be added to it with
205.Fn gctl_ro_param
206(for read-only parameters) or
207.Fn gctl_rw_param
208(for read/write parameters).
209.Pp
210Both
211.Fn gctl_ro_param
212and
213.Fn gctl_rw_param
214take a string
215.Fa name ,
216which is used to identify the parameter, and a
217.Fa value ,
218which contains, in the read-only case, the data to be passed to the
219GEOM class, or, in the read/write case, a pointer to preallocated memory
220that the GEOM class should fill with the desired data.
221If
222.Fa len
223is negative, it is assumed that
224.Fa value
225is an
226.Tn ASCII
227string and the actual length is taken from the string length of
228.Fa value ;
229otherwise it must hold the size of
230.Fa value .
231.Pp
232A parameter with a
233.Fa name
234containing the string
235.Qq Li class
236is mandatory for each request, and the
237corresponding
238.Fa value
239must hold the name of the GEOM class where the request should be sent to.
240.Pp
241Also mandatory for each request is a parameter with a
242.Fa name
243called
244.Qq Li verb ,
245and the corresponding
246.Fa value
247needs to hold the command string that the GEOM class should react upon.
248.Pp
249Once all desired parameters are filled in, the request must be sent to
250the GEOM subsystem with
251.Fn gctl_issue ,
252which returns
253.Dv NULL
254on success, or a string containing the error message
255on failure.
256.Pp
257After the request is finished, the allocated memory should be released with
258.Fn gctl_free .
259.Pp
260The
261.Fn gctl_dump
262function
263can be used to format the contents of
264.Fa req
265to the open file handle pointed to by
266.Fa f ,
267for debugging purposes.
268.Pp
269Error handling for the control functions is postponed until the call
270to
271.Fn gctl_issue ,
272which returns
273.Dv NULL
274on success, or an error message corresponding to the
275first error which happened.
276.Ss "Utility Functions"
277The
278.Fn g_*
279functions are used to communicate with GEOM providers.
280.Pp
281The
282.Fn g_open
283function opens the given provider and returns file descriptor number, which can
284be used with other functions.
285The
286.Fa dowrite
287argument indicates if operations that modify the provider (like
288.Fn g_flush
289or
290.Fn g_delete )
291are going to be called.
292.Pp
293The
294.Fn g_close
295function closes the provider.
296.Pp
297The
298.Fn g_mediasize
299function returns size of the given provider.
300.Pp
301The
302.Fn g_sectorsize
303function returns sector size of the given provider.
304.Pp
305The
306.Fn g_stripeoffset
307function returns stripe offset of the given provider.
308.Pp
309The
310.Fn g_stripesize
311function returns stripe size of the given provider.
312.Pp
313The
314.Fn g_flush
315function sends
316.Dv BIO_FLUSH
317request to flush write cache of the provider.
318.Pp
319The
320.Fn g_delete
321function tells the provider that the given data range is no longer used.
322.Pp
323The
324.Fn g_device_path
325function returns the full path to a provider given a partial or full path to the
326device node.
327If the device can not be found or is not a valid geom provider, NULL is
328returned.
329.Pp
330The
331.Fn g_get_ident
332function returns provider's fixed and unique identifier.
333The
334.Fa ident
335argument should be at least
336.Dv DISK_IDENT_SIZE
337big.
338.Pp
339The
340.Fn g_get_name
341function returns name of the provider, which identifier is equal to the
342.Fa ident
343string.
344.Pp
345The
346.Fn g_open_by_ident
347function opens provider using its ident, unlike
348.Fn g_open
349which uses provider's name.
350If the
351.Fa name
352argument is not
353.Dv NULL ,
354the function will store provider's name there.
355.Pp
356The
357.Fn g_providername
358function returns the provider name of an open file descriptor.
359If the file descriptor does not point to a valid geom provider, NULL is
360returned.
361.Pp
362All functions except
363.Fn g_providername
364and
365.Fn g_device_path
366return a value greater than or equal to
367.Va 0
368on success or
369.Va -1
370on failure.
371.Sh EXAMPLES
372Create a request that is to be sent to the CCD class, and tell
373it to destroy a specific geom:
374.Bd -literal -offset indent
375H = gctl_get_handle();
376gctl_ro_param(H, "verb", -1, "destroy geom");
377gctl_ro_param(H, "class", -1, "CCD");
378sprintf(buf, "ccd%d", ccd);
379gctl_ro_param(H, "geom", -1, buf);
380errstr = gctl_issue(H);
381if (errstr != NULL)
382    err(1, "could not destroy ccd: %s", errstr);
383gctl_free(H);
384.Ed
385.Sh HISTORY
386The
387.Nm geom
388library appeared in
389.Fx 5.1 .
390.Sh AUTHORS
391.An Poul-Henning Kamp Aq phk@FreeBSD.org
392.An Lukas Ertl Aq le@FreeBSD.org
393.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org
394