Deleted Added
sdiff udiff text old ( 79754 ) new ( 81133 )
full compact
devstat.3 (79754) devstat.3 (81133)
1.\"
1.\"
2.\" Copyright (c) 1998, 1999 Kenneth D. Merry.
2.\" Copyright (c) 1998, 1999, 2001 Kenneth D. Merry.
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

--- 9 unchanged lines hidden (view full) ---

20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
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

--- 9 unchanged lines hidden (view full) ---

20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\" $FreeBSD: head/lib/libdevstat/devstat.3 79754 2001-07-15 07:53:42Z dd $
28.\" $FreeBSD: head/lib/libdevstat/devstat.3 81133 2001-08-04 18:25:48Z tmm $
29.\"
29.\"
30.Dd May 21, 1998
30.Dd July 15, 2001
31.Dt DEVSTAT 3
32.Os
33.Sh NAME
34.Nm devstat ,
31.Dt DEVSTAT 3
32.Os
33.Sh NAME
34.Nm devstat ,
35.Nm devstat_getnumdevs ,
36.Nm devstat_getgeneration ,
37.Nm devstat_getversion ,
38.Nm devstat_checkversion ,
39.Nm devstat_getdevs ,
40.Nm devstat_selectdevs ,
41.Nm devstat_buildmatch ,
42.Nm devstat_compute_statistics ,
43.Nm devstat_compute_etime ,
35.Nm getnumdevs ,
36.Nm getgeneration ,
37.Nm getversion ,
38.Nm checkversion ,
39.Nm getdevs ,
40.Nm selectdevs ,
41.Nm buildmatch ,
42.Nm compute_stats ,
43.Nm compute_etime
44.Nd device statistics utility library
45.Sh LIBRARY
46.Lb libdevstat
47.Sh SYNOPSIS
48.Fd #include <sys/dkstat.h>
49.Fd #include <devstat.h>
50.Ft int
44.Nm getnumdevs ,
45.Nm getgeneration ,
46.Nm getversion ,
47.Nm checkversion ,
48.Nm getdevs ,
49.Nm selectdevs ,
50.Nm buildmatch ,
51.Nm compute_stats ,
52.Nm compute_etime
53.Nd device statistics utility library
54.Sh LIBRARY
55.Lb libdevstat
56.Sh SYNOPSIS
57.Fd #include <sys/dkstat.h>
58.Fd #include <devstat.h>
59.Ft int
60.Fo devstat_getnumdevs
61.Fa "kvm_t *kd"
62.Fc
63.Ft long
64.Fo devstat_getgeneration
65.Fa "kvm_t *kd"
66.Fc
67.Ft int
68.Fo devstat_getversion
69.Fa "kvm_t *kd"
70.Fc
71.Ft int
72.Fo devstat_checkversion
73.Fa "kvm_t *kd"
74.Fc
75.Ft int
76.Fo devstat_getdevs
77.Fa "kvm_t *kd"
78.Fa "struct statinfo *stats"
79.Fc
80.Ft int
81.Fo devstat_selectdevs
82.Fa "struct device_selection **dev_select"
83.Fa "int *num_selected"
84.Fa "int *num_selections"
85.Fa "long *select_generation"
86.Fa "long current_generation"
87.Fa "struct devstat *devices"
88.Fa "int numdevs"
89.Fa "struct devstat_match *matches"
90.Fa "int num_matches"
91.Fa "char **dev_selections"
92.Fa "int num_dev_selections"
93.Fa "devstat_select_mode select_mode"
94.Fa "int maxshowdevs"
95.Fa "int perf_select"
96.Fc
97.Ft int
98.Fo devstat_buildmatch
99.Fa "char *match_str"
100.Fa "struct devstat_match **matches"
101.Fa "int *num_matches"
102.Fc
103.Ft int
104.Fo devstat_compute_statistics
105.Fa "struct devstat *current"
106.Fa "struct devstat *previous"
107.Fa "long double *etime"
108.Fa "..."
109.Fc
110.Ft long double
111.Fo devstat_compute_etime
112.Fa "struct timeval cur_time"
113.Fa "struct timeval prev_time"
114.Fc
115.Ft int
51.Fn getnumdevs "void"
52.Ft long
53.Fn getgeneration "void"
54.Ft int
55.Fn getversion "void"
56.Ft int
57.Fn checkversion "void"
58.Ft int

--- 41 unchanged lines hidden (view full) ---

100.Fa "struct timeval prev_time"
101.Fc
102.Sh DESCRIPTION
103The
104.Nm
105library is a library of helper functions for dealing with the kernel
106.Xr devstat 9
107interface, which is accessible to users via
116.Fn getnumdevs "void"
117.Ft long
118.Fn getgeneration "void"
119.Ft int
120.Fn getversion "void"
121.Ft int
122.Fn checkversion "void"
123.Ft int

--- 41 unchanged lines hidden (view full) ---

165.Fa "struct timeval prev_time"
166.Fc
167.Sh DESCRIPTION
168The
169.Nm
170library is a library of helper functions for dealing with the kernel
171.Xr devstat 9
172interface, which is accessible to users via
173.Xr sysctl 3
174and
175.Xr kvm 3 .
176All functions that that take a
177.Vt kvm_t *
178as first argument can be passed
179.Dv NULL
180instead of a kvm handle as this argument,
181which causes the data to be read via
108.Xr sysctl 3 .
182.Xr sysctl 3 .
183Otherwise, it is read via
184.Xr kvm 3
185using the supplied handle.
186.Fn devstat_checkversion
187should be called with each kvm handle that is going to be used (or with
188.Dv NULL
189if
190.Xr sysctl 3
191is going to be used).
109.Pp
192.Pp
110.Fn getnumdevs
193.Fn devstat_getnumdevs
111returns the number of devices registered with the
112.Nm
113subsystem in the kernel.
114.Pp
194returns the number of devices registered with the
195.Nm
196subsystem in the kernel.
197.Pp
115.Fn getgeneration
198.Fn getnumdevs
199is a deprecated version of
200.Fn devstat_getnumdevs
201which always uses
202.Xr sysctl 3 .
203.Pp
204.Fn devstat_getgeneration
116returns the current generation of the
117.Nm
118list of devices in the kernel.
119.Pp
205returns the current generation of the
206.Nm
207list of devices in the kernel.
208.Pp
120.Fn getversion
209.Fn getgeneration
210is a deprecated version of
211.Fn devstat_getgeneration
212which always uses
213.Xr sysctl 3 .
214.Pp
215.Fn devstat_getversion
121returns the current kernel
122.Nm
123version.
124.Pp
216returns the current kernel
217.Nm
218version.
219.Pp
125.Fn checkversion
126checks the userland devstat version against the kernel devstat version. If
127the two are identical, it returns zero. Otherwise, it prints an
128appropriate error in
220.Fn getversion
221is a deprecated version of
222.Fn devstat_getversion
223which always uses
224.Xr sysctl 3 .
225.Pp
226.Fn devstat_checkversion
227checks the userland devstat version against the kernel devstat version.
228If the two are identical, it returns zero.
229Otherwise, it prints an appropriate error in
129.Va devstat_errbuf
130and returns -1.
131.Pp
230.Va devstat_errbuf
231and returns -1.
232.Pp
132.Fn getdevs
233.Fn checkversion
234is a deprecated version of
235.Fn devstat_checkversion
236which always uses
237.Xr sysctl 3 .
238.Pp
239.Fn devstat_getdevs
133fetches the current list of devices and statistics into the supplied
134.Va statinfo
240fetches the current list of devices and statistics into the supplied
241.Va statinfo
135structure. The
242structure.
243The
136.Va statinfo
137structure can be found in
138.Aq Pa devstat.h :
139.Bd -literal -offset indent
140struct statinfo {
141 long cp_time[CPUSTATES];
142 long tk_nin;
143 long tk_nout;
144 struct devinfo *dinfo;
145 struct timeval busy_time;
146};
147.Ed
148.Pp
244.Va statinfo
245structure can be found in
246.Aq Pa devstat.h :
247.Bd -literal -offset indent
248struct statinfo {
249 long cp_time[CPUSTATES];
250 long tk_nin;
251 long tk_nout;
252 struct devinfo *dinfo;
253 struct timeval busy_time;
254};
255.Ed
256.Pp
149.Fn getdevs
257.Fn devstat_getdevs
150expects the
151.Va statinfo
152structure to be allocated, and it also expects the
153.Va dinfo
154subelement to be allocated and zeroed prior to the first invocation of
258expects the
259.Va statinfo
260structure to be allocated, and it also expects the
261.Va dinfo
262subelement to be allocated and zeroed prior to the first invocation of
155.Fn getdevs .
263.Fn devstat_getdevs .
156The
157.Va dinfo
158subelement is used to store state between calls, and should not be modified
159after the first call to
264The
265.Va dinfo
266subelement is used to store state between calls, and should not be modified
267after the first call to
160.Fn getdevs .
268.Fn devstat_getdevs .
161The
162.Va dinfo
163subelement contains the following elements:
164.Bd -literal -offset indent
165struct devinfo {
166 struct devstat *devices;
167 u_int8_t *mem_ptr;
168 long generation;
169 int numdevs;
170};
171.Ed
172.Pp
173The
174.Va kern.devstat.all
175.Nm sysctl
176variable contains an array of
177.Nm
178structures, but at the head of the array is the current
179.Nm
269The
270.Va dinfo
271subelement contains the following elements:
272.Bd -literal -offset indent
273struct devinfo {
274 struct devstat *devices;
275 u_int8_t *mem_ptr;
276 long generation;
277 int numdevs;
278};
279.Ed
280.Pp
281The
282.Va kern.devstat.all
283.Nm sysctl
284variable contains an array of
285.Nm
286structures, but at the head of the array is the current
287.Nm
180generation. The reason the generation is at the head of the buffer is so
181that userland software accessing the devstat statistics information can
182atomically get both the statistics information and the corresponding
183generation number. If client software were forced to get the generation
184number via a separate
288generation.
289The reason the generation is at the head of the buffer is so that userland
290software accessing the devstat statistics information can atomically get
291both the statistics information and the corresponding generation number.
292If client software were forced to get the generation number via a separate
185.Nm sysctl
186variable (which is available for convenience), the list of devices could
187change between the time the client gets the generation and the time the
188client gets the device list.
189.Pp
190The
191.Va mem_ptr
192subelement of the
193.Va devinfo
194structure is a pointer to memory that is allocated, and resized if
195necessary, by
293.Nm sysctl
294variable (which is available for convenience), the list of devices could
295change between the time the client gets the generation and the time the
296client gets the device list.
297.Pp
298The
299.Va mem_ptr
300subelement of the
301.Va devinfo
302structure is a pointer to memory that is allocated, and resized if
303necessary, by
196.Fn getdevs .
304.Fn devstat_getdevs .
197The devices subelement of the
198.Va devinfo
199structure is basically a pointer to the beginning of the array of devstat
200structures from the
201.Va kern.devstat.all
202.Nm sysctl
305The devices subelement of the
306.Va devinfo
307structure is basically a pointer to the beginning of the array of devstat
308structures from the
309.Va kern.devstat.all
310.Nm sysctl
203variable. The generation subelement of the
311variable (or the corresponding values read via
312.Xr kvm 3 ) .
313The generation subelement of the
204.Va devinfo
314.Va devinfo
205structure contains the generation number from the
206.Va kern.devstat.all
207.Nm sysctl
208variable.
315structure contains the corresponding generation number.
209The
210.Va numdevs
211subelement of the
212.Va devinfo
213structure contains the current
214number of devices registered with the kernel
215.Nm
216subsystem.
217.Pp
316The
317.Va numdevs
318subelement of the
319.Va devinfo
320structure contains the current
321number of devices registered with the kernel
322.Nm
323subsystem.
324.Pp
218.Fn selectdevs
325.Fn getdevs
326is a deprecated version of
327.Fn devstat_getdevs
328which always uses
329.Xr sysctl 3 .
330.Pp
331.Fn devstat_selectdevs
219selects devices to display based upon a number of criteria:
220.Bl -tag -width flag
221.It specified devices
332selects devices to display based upon a number of criteria:
333.Bl -tag -width flag
334.It specified devices
222Specified devices are the first selection priority. These are generally
223devices specified by name by the user. e.g. da0, da1, cd0.
335Specified devices are the first selection priority.
336These are generally devices specified by name by the user e.g. da0, da1, cd0.
224.It match patterns
225These are pattern matching expressions generated by
337.It match patterns
338These are pattern matching expressions generated by
226.Fn buildmatch
339.Fn devstat_buildmatch
227from user input.
228.It performance
229If performance mode is enabled, devices will be sorted based on the
230.Va bytes
231field in the
232.Va device_selection
233structure passed in to
340from user input.
341.It performance
342If performance mode is enabled, devices will be sorted based on the
343.Va bytes
344field in the
345.Va device_selection
346structure passed in to
234.Fn selectdevs .
347.Fn devstat_selectdevs .
235The
236.Va bytes
348The
349.Va bytes
237value currently must be maintained by the user. In the future,
238this may be done for him in a
350value currently must be maintained by the user.
351In the future, this may be done for him in a
239.Nm
240library routine.
241If no devices have been selected by name or by pattern, the performance
242tracking code will select every device in the system, and sort them by
352.Nm
353library routine.
354If no devices have been selected by name or by pattern, the performance
355tracking code will select every device in the system, and sort them by
243performance. If devices have been selected by name or pattern, the
244performance tracking code will honor those selections and will only sort
245among the selected devices.
356performance.
357If devices have been selected by name or pattern, the performance tracking
358code will honor those selections and will only sort among the selected
359devices.
246.It order in the devstat list
247If the selection mode is set to DS_SELECT_ADD, and if there are still less
248than
249.Va maxshowdevs
250devices selected,
360.It order in the devstat list
361If the selection mode is set to DS_SELECT_ADD, and if there are still less
362than
363.Va maxshowdevs
364devices selected,
251.Fn selectdevs
365.Fn devstat_selectdevs
252will automatically select up to
253.Va maxshowdevs
254devices.
255.El
256.Pp
366will automatically select up to
367.Va maxshowdevs
368devices.
369.El
370.Pp
257.Fn selectdevs
371.Fn devstat_selectdevs
258performs selections in four different modes:
259.Bl -tag -width DS_SELECT_ADDONLY
260.It DS_SELECT_ADD
261In add mode,
372performs selections in four different modes:
373.Bl -tag -width DS_SELECT_ADDONLY
374.It DS_SELECT_ADD
375In add mode,
262.Fn selectdevs
376.Fn devstat_selectdevs
263will select any unselected devices specified by name or matching pattern.
264It will also select more devices, in devstat list order, until the number
265of selected devices is equal to
266.Va maxshowdevs
267or until all devices are
268selected.
269.It DS_SELECT_ONLY
270In only mode,
377will select any unselected devices specified by name or matching pattern.
378It will also select more devices, in devstat list order, until the number
379of selected devices is equal to
380.Va maxshowdevs
381or until all devices are
382selected.
383.It DS_SELECT_ONLY
384In only mode,
271.Fn selectdevs
385.Fn devstat_selectdevs
272will clear all current selections, and will only select devices specified
273by name or by matching pattern.
274.It DS_SELECT_REMOVE
275In remove mode,
386will clear all current selections, and will only select devices specified
387by name or by matching pattern.
388.It DS_SELECT_REMOVE
389In remove mode,
276.Fn selectdevs
277will remove devices specified by name or by matching pattern. It will not
278select any additional devices.
390.Fn devstat_selectdevs
391will remove devices specified by name or by matching pattern.
392It will not select any additional devices.
279.It DS_SELECT_ADDONLY
280In add only mode,
393.It DS_SELECT_ADDONLY
394In add only mode,
281.Fn selectdevs
395.Fn devstat_selectdevs
282will select any unselected devices specified by name or matching pattern.
396will select any unselected devices specified by name or matching pattern.
283In this respect it is identical to add mode. It will not, however, select
284any devices other than those specified.
397In this respect it is identical to add mode.
398It will not, however, select any devices other than those specified.
285.El
286.Pp
287In all selection modes,
399.El
400.Pp
401In all selection modes,
288.Fn selectdevs
402.Fn devstat_selectdevs
289will not select any more than
290.Va maxshowdevs
403will not select any more than
404.Va maxshowdevs
291devices. One exception to
292this is when you are in
405devices.
406One exception to this is when you are in
293.Dq top
407.Dq top
294mode and no devices have been selected. In
295this case,
296.Fn selectdevs
297will select every device in the system. Client programs must pay attention
298to selection order when deciding whether to pay attention to a particular
299device. This may be the wrong behavior, and probably requires additional
300thought.
408mode and no devices have been selected.
409In this case,
410.Fn devstat_selectdevs
411will select every device in the system.
412Client programs must pay attention to selection order when deciding whether
413to pay attention to a particular device.
414This may be the wrong behavior, and probably requires additional thought.
301.Pp
415.Pp
302.Fn selectdevs
416.Fn devstat_selectdevs
303handles allocation and resizing of the
304.Va dev_select
305structure passed in
306by the client.
417handles allocation and resizing of the
418.Va dev_select
419structure passed in
420by the client.
307.Fn selectdevs
421.Fn devstat_selectdevs
308uses the
309.Va numdevs
310and
311.Va current_generation
312fields to track the
313current
314.Nm
422uses the
423.Va numdevs
424and
425.Va current_generation
426fields to track the
427current
428.Nm
315generation and number of devices. If
429generation and number of devices.
430If
316.Va num_selections
317is not the same
318as
319.Va numdevs
320or if
321.Va select_generation
322is not the same as
323.Va current_generation ,
431.Va num_selections
432is not the same
433as
434.Va numdevs
435or if
436.Va select_generation
437is not the same as
438.Va current_generation ,
324.Fn selectdevs
439.Fn devstat_selectdevs
325will resize the selection list as necessary, and re-initialize the
326selection array.
327.Pp
440will resize the selection list as necessary, and re-initialize the
441selection array.
442.Pp
328.Fn buildmatch
329takes a comma separated match string and compiles it into a
443.Fn selectdevs
444is the old name of
445.Fn devstat_selectdevs ,
446and is deprecated.
447.Pp
448.Fn devstat_buildmatch
449take a comma separated match string and compile it into a
330\fBdevstat_match\fR structure that is understood by
331.Fn selectdevs .
332Match strings have the following format:
333.Pp
334.Bd -literal -offset indent
335device,type,if
336.Ed
337.Pp
450\fBdevstat_match\fR structure that is understood by
451.Fn selectdevs .
452Match strings have the following format:
453.Pp
454.Bd -literal -offset indent
455device,type,if
456.Ed
457.Pp
338.Fn buildmatch
458.Fn devstat_buildmatch
339takes care of allocating and reallocating the match list as necessary.
340Currently known match types include:
341.Pp
342.Bl -tag -width indent -compact
343.It device type:
344.Bl -tag -width 9n -compact
345.It da
346Direct Access devices

--- 35 unchanged lines hidden (view full) ---

382.Pp
383.It passthrough:
384.Bl -tag -width 9n -compact
385.It pass
386Passthrough devices
387.El
388.El
389.Pp
459takes care of allocating and reallocating the match list as necessary.
460Currently known match types include:
461.Pp
462.Bl -tag -width indent -compact
463.It device type:
464.Bl -tag -width 9n -compact
465.It da
466Direct Access devices

--- 35 unchanged lines hidden (view full) ---

502.Pp
503.It passthrough:
504.Bl -tag -width 9n -compact
505.It pass
506Passthrough devices
507.El
508.El
509.Pp
510.Fn buildmatch
511is the old name of
512.Fn devstat_buildmatch ,
513and is deprecated.
514.Pp
515.Fn devstat_compute_statistics
516is an updated version of
390.Fn compute_stats
517.Fn compute_stats
391provides an easy way to obtain various device statistics. Only two
392arguments are mandatory:
518that provides more complete statistics calculation.
519There are four arguments for which values \fBmust\fR be supplied:
520.Va current ,
521.Va previous ,
522.Va etime ,
523and the terminating argument for the varargs list,
524.Va DSM_NONE .
525For most applications, the user will want to supply valid devstat
526structures for both
393.Va current
394and
527.Va current
528and
529.Va previous .
530In some instances, for instance when calculating statistics since system
531boot, the user may pass in a NULL pointer for the
532.Va previous
533argument.
534In that case,
535.Fn devstat_compute_statistics
536will use the total stats in the
537.Va current
538structure to calculate statistics over
395.Va etime .
539.Va etime .
396Every other argument is optional. For most applications, the user will
397want to supply both
540For each statistic to be calculated, the user should supply the proper
541enumerated type (listed below), and a variable of the indicated type.
542All statistics are either integer values, for which a u_int64_t is used,
543or floating point, for which a long double is used.
544The statistics that may be calculated are:
545.Bl -tag -width DSM_TRANSFERS_PER_SECOND_OTHER
546.It DSM_NONE
547type: N/A
548.Pp
549This \fBmust\fR
550be the last argument passed to
551.Fn devstat_compute_statistics .
552It is an argument list terminator.
553.It DSM_TOTAL_BYTES
554type: u_int64_t *
555.Pp
556The total number of bytes transferred between the acquisition of
557.Va previous
558and
559.Va current .
560.It DSM_TOTAL_BYTES_READ
561type: u_int64_t *
562.Pp
563The total number of bytes read between the acquisition of
564.Va previous
565and
566.Va current .
567.It DSM_TOTAL_BYTES_WRITE
568type: u_int64_t *
569.Pp
570The total number of bytes written between the acquisition of
571.Va previous
572and
573.Va current .
574.It DSM_TOTAL_TRANSFERS
575type: u_int64_t *
576.Pp
577The total number of transfers between the acquisition of
578.Va previous
579and
580.Va current .
581.It DSM_TOTAL_TRANSFERS_READ
582type: u_int64_t *
583.Pp
584The total number of reads between the acquisition of
585.Va previous
586and
587.Va current .
588.It DSM_TOTAL_TRANSFERS_WRITE
589type: u_int64_t *
590.Pp
591The total number of writes between the acquisition of
592.Va previous
593and
594.Va current .
595.It DSM_TOTAL_TRANSFERS_OTHER
596type: u_int64_t *
597.Pp
598The total number of transactions that are not reads or writes that occurred
599between the acquisition of
600.Va previous
601and
602.Va current .
603.It DSM_TOTAL_BLOCKS
604type: u_int64_t *
605.Pp
606The total number of blocks transferred between the acquisition of
607.Va previous
608and
609.Va current .
610This number is in terms of the blocksize reported by the device.
611If no blocksize has been reported (i.e. the block size is 0), a default
612blocksize of 512 bytes will be used in the calculation.
613.It DSM_TOTAL_BLOCKS_READ
614type: u_int64_t *
615.Pp
616The total number of blocks read between the acquisition of
617.Va previous
618and
619.Va current .
620This number is in terms of the blocksize reported by the device.
621If no blocksize has been reported (i.e. the block size is 0), a default
622blocksize of 512 bytes will be used in the calculation.
623.It DSM_TOTAL_BLOCKS_WRITE
624type: u_int64_t *
625.Pp
626The total number of blocks written between the acquisition of
627.Va previous
628and
629.Va current .
630This number is in terms of the blocksize reported by the device.
631If no blocksize has been reported (i.e. the block size is 0), a default
632blocksize of 512 bytes will be used in the calculation.
633.It DSM_KB_PER_TRANSFER
634type: long double *
635.Pp
636The average number of kilobytes per transfer between the acquisition of
637.Va previous
638and
639.Va current .
640.It DSM_KB_PER_TRANSFER_READ
641type: long double *
642.Pp
643The average number of kilobytes per read transaction between the acquisition of
644.Va previous
645and
646.Va current .
647.It DSM_KB_PER_TRANSFER_WRITE
648type: long double *
649.Pp
650The average number of kilobytes per write transaction between the acquisition of
651.Va previous
652and
653.Va current .
654.It DSM_TRANSFERS_PER_SECOND
655type: long double *
656.Pp
657The average number of transfers per second between the acquisition of
658.Va previous
659and
660.Va current .
661.It DSM_TRANSFERS_PER_SECOND_READ
662type: long double *
663.Pp
664The average number of reads per second between the acquisition of
665.Va previous
666and
667.Va current .
668.It DSM_TRANSFERS_PER_SECOND_WRITE
669type: long double *
670.Pp
671The average number of writes per second between the acquisition of
672.Va previous
673and
674.Va current .
675.It DSM_TRANSFERS_PER_SECOND_OTHER
676type: long double *
677.Pp
678The average number of non-read, non-write transactions per second between
679the acquisition of
680.Va previous
681and
682.Va current .
683.It DSM_MB_PER_SECOND
684type: long double *
685.Pp
686The average number of megabytes transferred per second between the
687acquisition of
688.Va previous
689and
690.Va current .
691.It DSM_MB_PER_SECOND_READ
692type: long double *
693.Pp
694The average number of megabytes read per second between the acquisition of
695.Va previous
696and
697.Va current .
698.It DSM_MB_PER_SECOND_WRITE
699type: long double *
700.Pp
701The average number of megabytes written per second between the acquisition of
702.Va previous
703and
704.Va current .
705.It DSM_BLOCKS_PER_SECOND
706type: long double *
707.Pp
708The average number of blocks transferred per second between the acquisition of
709.Va previous
710and
711.Va current .
712This number is in terms of the blocksize reported by the device.
713If no blocksize has been reported (i.e. the block size is 0), a default
714blocksize of 512 bytes will be used in the calculation.
715.It DSM_BLOCKS_PER_SECOND_READ
716type: long double *
717.Pp
718The average number of blocks read per second between the acquisition of
719.Va previous
720and
721.Va current .
722This number is in terms of the blocksize reported by the device.
723If no blocksize has been reported (i.e. the block size is 0), a default
724blocksize of 512 bytes will be used in the calculation.
725.It DSM_BLOCKS_PER_SECOND_WRITE
726type: long double *
727.Pp
728The average number of blocks written per second between the acquisition of
729.Va previous
730and
731.Va current .
732This number is in terms of the blocksize reported by the device.
733If no blocksize has been reported (i.e. the block size is 0), a default
734blocksize of 512 bytes will be used in the calculation.
735.It DSM_MS_PER_TRANSACTION
736type: long double *
737.Pp
738The average rate of transaction completion between the acquisition of
739.Va previous
740and
741.Va current .
742Note that this isn't a true reflection of the average number of
743milliseconds per transaction, but rather is the average rate of transaction
744completion.
745The number is derived by dividing the time elapsed by the number of
746transactions completed.
747.It DSM_MS_PER_TRANSACTION_READ
748type: long double *
749.Pp
750The average rate of read completions between the acquisition of
751.Va previous
752and
753.Va current .
754As above, this is not the true number of milliseconds per transaction, but
755rather the average rate of read transaction completion.
756.It DSM_MS_PER_TRANSACTION_WRITE
757type: long double *
758.Pp
759The average rate of write transaction completion between the acquisition of
760.Va previous
761and
762.Va current .
763As above, this is not the true number of milliseconds per transaction, but
764rather the average rate of write transaction completion.
765.El
766.Pp
767.Fn compute_stats
768is deprecated; use
769.Fn devstat_compute_statistics
770instead.
771.Fn compute_stats
772provides an easy way to obtain various device statistics.
773Only two arguments are mandatory:
398.Va current
399and
774.Va current
775and
776.Va etime .
777Every other argument is optional.
778For most applications, the user will want to supply both
779.Va current
780and
400.Va previous
401devstat structures so that statistics may be calculated over a given period
781.Va previous
782devstat structures so that statistics may be calculated over a given period
402of time. In some instances, for instance when calculating statistics since
403system boot, the user may pass in a NULL pointer for the
783of time.
784In some instances, for instance when calculating statistics since system boot,
785the user may pass in a NULL pointer for the
404.Va previous
786.Va previous
405argument. In that case,
787argument.
788In that case,
406.Fn compute_stats
407will use the total stats in the
408.Va current
409structure to calculate statistics over
410.Va etime .
411The various statistics that may be calculated by
412.Fn compute_stats
413should be mostly explained by the function declaration itself, but for

--- 18 unchanged lines hidden (view full) ---

432.Va current .
433If
434.Va previous
435is NULL, the result will be the total number of transactions listed in
436.Va current .
437.It total_blocks
438This is basically
439.Va total_bytes
789.Fn compute_stats
790will use the total stats in the
791.Va current
792structure to calculate statistics over
793.Va etime .
794The various statistics that may be calculated by
795.Fn compute_stats
796should be mostly explained by the function declaration itself, but for

--- 18 unchanged lines hidden (view full) ---

815.Va current .
816If
817.Va previous
818is NULL, the result will be the total number of transactions listed in
819.Va current .
820.It total_blocks
821This is basically
822.Va total_bytes
440divided by the device blocksize. If the device blocksize is listed as
823divided by the device blocksize.
824If the device blocksize is listed as
441.Sq 0 ,
442the device blocksize will default to 512 bytes.
443.It kb_per_transfer
444This is the average number of kilobytes per transfer during the measurement
445period.
446.It transfers_per_second
447This is the average number of transfers per second.
448.It mb_per_second
449This is average megabytes per second.
450.It blocks_per_second
825.Sq 0 ,
826the device blocksize will default to 512 bytes.
827.It kb_per_transfer
828This is the average number of kilobytes per transfer during the measurement
829period.
830.It transfers_per_second
831This is the average number of transfers per second.
832.It mb_per_second
833This is average megabytes per second.
834.It blocks_per_second
451This is average blocks per second. If the device blocksize is
835This is average blocks per second.
836If the device blocksize is
452.Sq 0 ,
453a default blocksize of 512 bytes will be used instead.
454.It ms_per_transaction
455The average number of milliseconds per transaction.
456.El
457.Pp
837.Sq 0 ,
838a default blocksize of 512 bytes will be used instead.
839.It ms_per_transaction
840The average number of milliseconds per transaction.
841.El
842.Pp
458.Fn compute_etime
843.Fn devstat_compute_etime
459provides an easy way to find the difference in seconds between two
460.Va timeval
844provides an easy way to find the difference in seconds between two
845.Va timeval
461structures. This is most commonly used in conjunction with the time
462recorded by the
463.Fn getdevs
846structures.
847This is most commonly used in conjunction with the time recorded by the
848.Fn devstat_getdevs
464function (in struct
465.Va statinfo )
466each time it fetches the current
467.Nm
468list.
849function (in struct
850.Va statinfo )
851each time it fetches the current
852.Nm
853list.
854.Pp
855.Fn compute_etime
856is the old name of
857.Fn devstat_compute_etime ,
858and is deprecated.
469.Sh RETURN VALUES
859.Sh RETURN VALUES
470.Fn getnumdevs ,
471.Fn getgeneration ,
860.Fn devstat_getnumdevs ,
861.Fn devstat_getgeneration ,
472and
862and
473.Fn getversion
863.Fn devstat_getversion
474return the indicated \fBsysctl\fR variable, or -1 if there is an error
475fetching the variable.
476.Pp
864return the indicated \fBsysctl\fR variable, or -1 if there is an error
865fetching the variable.
866.Pp
477.Fn checkversion
867.Fn devstat_checkversion
478returns 0 if the kernel and userland
479.Nm
868returns 0 if the kernel and userland
869.Nm
480versions match. If they do not match, it returns -1.
870versions match.
871If they do not match, it returns -1.
481.Pp
872.Pp
482.Fn getdevs
873.Fn devstat_getdevs
483and
874and
484.Fn selectdevs
875.Fn devstat_selectdevs
485return -1 in case of an error, 0 if there is no error and 1 if the device
876return -1 in case of an error, 0 if there is no error and 1 if the device
486list or selected devices have changed. A return value of 1 from
487.Fn getdevs
877list or selected devices have changed.
878A return value of 1 from
879.Fn devstat_getdevs
488is usually a hint to re-run
880is usually a hint to re-run
489.Fn selectdevs
881.Fn devstat_selectdevs
490because the device list has changed.
491.Pp
882because the device list has changed.
883.Pp
492.Fn buildmatch
884.Fn devstat_buildmatch
493returns -1 for error, and 0 if there is no error.
494.Pp
495.Fn compute_stats
496returns -1 for error, and 0 for success.
497.Pp
885returns -1 for error, and 0 if there is no error.
886.Pp
887.Fn compute_stats
888returns -1 for error, and 0 for success.
889.Pp
498.Fn compute_etime
890.Fn devstat_compute_etime
499returns the computed elapsed time.
500.Pp
891returns the computed elapsed time.
892.Pp
893.Fn devstat_compute_statistics
894returns -1 for error, and 0 for success.
895.Pp
501If an error is returned from one of the
502.Nm
503library functions, the reason for the error is generally printed in
504the global string
505.Va devstat_errbuf
506which is
507.Dv DEVSTAT_ERRBUF_SIZE
508characters long.
509.Sh SEE ALSO
896If an error is returned from one of the
897.Nm
898library functions, the reason for the error is generally printed in
899the global string
900.Va devstat_errbuf
901which is
902.Dv DEVSTAT_ERRBUF_SIZE
903characters long.
904.Sh SEE ALSO
905.Xr sysctl 1 ,
510.Xr systat 1 ,
906.Xr systat 1 ,
907.Xr kvm 3 ,
908.Xr sysctl 3 ,
511.Xr iostat 8 ,
512.Xr rpc.rstatd 8 ,
513.Xr vmstat 8 ,
514.Xr devstat 9
515.Sh HISTORY
516The
517.Nm
518statistics system first appeared in
519.Fx 3.0 .
909.Xr iostat 8 ,
910.Xr rpc.rstatd 8 ,
911.Xr vmstat 8 ,
912.Xr devstat 9
913.Sh HISTORY
914The
915.Nm
916statistics system first appeared in
917.Fx 3.0 .
918The new interface (the functions prefixed with devstat_) first appeared in
919.Fx 5.0 .
520.Sh AUTHORS
521.An Kenneth Merry Aq ken@FreeBSD.org
522.Sh BUGS
523There should probably be an interface to de-allocate memory allocated by
920.Sh AUTHORS
921.An Kenneth Merry Aq ken@FreeBSD.org
922.Sh BUGS
923There should probably be an interface to de-allocate memory allocated by
524.Fn getdevs ,
525.Fn selectdevs ,
924.Fn devstat_getdevs ,
925.Fn devstat_selectdevs ,
526and
926and
527.Fn buildmatch .
927.Fn devstat_buildmatch .
528.Pp
928.Pp
529.Fn selectdevs
929.Fn devstat_selectdevs
530should probably not select more than
531.Va maxshowdevs
532devices in
533.Dq top
534mode when no devices have been selected previously.
535.Pp
536There should probably be functions to perform the statistics buffer
537swapping that goes on in most of the clients of this library.
538.Pp
539The
540.Va statinfo
541and
542.Va devinfo
543structures should probably be cleaned up and thought out a little more.
930should probably not select more than
931.Va maxshowdevs
932devices in
933.Dq top
934mode when no devices have been selected previously.
935.Pp
936There should probably be functions to perform the statistics buffer
937swapping that goes on in most of the clients of this library.
938.Pp
939The
940.Va statinfo
941and
942.Va devinfo
943structures should probably be cleaned up and thought out a little more.