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