1sg_get_fs_stats(3)                                          sg_get_fs_stats(3)
2
3
4

NAME

6       sg_get_fs_stats,        sg_get_fs_stats_r,        sg_get_fs_stats_diff,
7       sg_get_fs_stats_diff_between,  sg_free_fs_stats,  sg_get_valid_filesys‐
8       tems,  sg_set_valid_filesystems,  sg_fs_compare_device_name, sg_fs_com‐
9       pare_mnt_point - get file system statistics
10

SYNOPSIS

12       #include <statgrab.h>
13
14
15       sg_fs_stats *sg_get_fs_stats (size_t *entries);
16
17       sg_fs_stats *sg_get_fs_stats_r (size_t *entries);
18
19       sg_fs_stats *sg_get_fs_stats_diff (size_t *entries);
20
21       sg_fs_stats *sg_get_fs_stats_diff_between (const sg_fs_stats *cur,
22                       const sg_fs_stats *last, size_t *entries);
23
24       sg_error sg_free_fs_stats (sg_fs_stats *data);
25
26       const char **sg_get_valid_filesystems (size_t *entries);
27
28       sg_error sg_set_valid_filesystems (const char *valid_fs[]);
29
30       int sg_fs_compare_device_name (const void *va, const void *vb);
31
32       int sg_fs_compare_mnt_point (const void *va, const void *vb);
33

DESCRIPTION

35       The  sg_get_fs_stats  functions provide statistics of mounted file sys‐
36       tems. Both functions take an optional entries parameter,  which  points
37       (when given) to a size_t to take the number of returned vector entries.
38
39       The  sg_get_fs_stats()  and  sg_get_fs_stats_r()  functions deliver the
40       file system statistics of  the  moment  the  function  is  called.  The
41       sg_get_fs_stats_diff()  and  sg_get_fs_stats_diff_between() deliver the
42       difference    between    two    calls    of    sg_get_fs_stats()     or
43       sg_get_fs_stats_r(), respectively.
44
45       API Shortcut
46
47       ┌─────────────────────────┬───────────────┬─────────────────────┐
48       │function                 │ returns       │ data owner          │
49       ├─────────────────────────┼───────────────┼─────────────────────┤
50       │sg_get_fs_stats          │ sg_fs_stats * │ libstatgrab (thread │
51       │                         │               │ local)              │
52       ├─────────────────────────┼───────────────┼─────────────────────┤
53       │sg_get_fs_stats_r        │ sg_fs_stats * │ caller              │
54       ├─────────────────────────┼───────────────┼─────────────────────┤
55       │sg_get_fs_stats_diff     │ sg_fs_stats * │ libstatgrab (thread │
56       │                         │               │ local)              │
57       ├─────────────────────────┼───────────────┼─────────────────────┤
58       │sg_get_fs_stats_diff_be‐ │ sg_fs_stats * │ caller              │
59       │tween                    │               │                     │
60       ├─────────────────────────┼───────────────┼─────────────────────┤
61       │sg_get_valid_filesystems │ char **       │ libstatgrab  (glob‐ │
62       │                         │               │ al)                 │
63       └─────────────────────────┴───────────────┴─────────────────────┘
64       The  sg_fs_stats   vectors   received   from   sg_get_fs_stats_r()   or
65       sg_get_fs_stats_diff_between()  must  be freed using sg_free_fs_stats()
66       when not needed anymore. The caller is responsible for doing it.
67
68       The statgrab library comes with a built-in list of  valid  file  system
69       types depending on the operating system it was compiled for. Some oper‐
70       ating systems additionally provide an API  to  learn  the  file  system
71       types known or valid to the running OS instance, which is used when de‐
72       tected. Nevertheless there are known problems when collecting file sys‐
73       tem  statistics:  network  file  systems  are  mounted  from delaunched
74       servers, file system developers run an experimental driver etc.
75
76       To prevent processes hang in getting file system  statistics  or  allow
77       developers  to test their drivers, the processes may modify the list of
78       valid  file  systems  using  the  sg_get_valid_filesystems()  and   the
79       sg_set_valid_filesystems().  The  list  of char * parameters both func‐
80       tions work with is always finished with an element pointing to NULL.
81
82       The returned list of sg_get_valid_filesystems() must not  be  modified.
83       Always  copy  the  list into an own structure, if you plan to extend or
84       reduce the list:
85
86       Remove Network FS Example
87
88       int compare_fs_type(const void *va, const void *vb) {
89           const char **a = (const char **)va;
90           const char **b = (const char **)vb;
91           return strcmp( *a, *b );
92       }
93
94       void filter_network_fs_types(void) {
95           /* known network file system names on different platforms */
96           const char *nfs_types[] = { "nfs", "nfs3", "nfs4", "cifs", "smbfs", "samba" };
97           const size_t nfs_types_count = sizeof(nfs_types) / sizeof(nfs_types[0])
98           size_t fs_entries = 0;
99           const char **orig_valid_fs = sg_get_valid_filesystems(&fs_entries);
100
101           /* duplicate into own memory to modify list */
102           char **valid_fs = calloc( entries + 1, sizeof(valid_fs[0]) );
103           memcpy( valid_fs, orig_valid_fs, (entries + 1) * sizeof(valid_fs[0]) );
104           size_t i;
105           for( i = 0; i < nfs_types_count; ++i ) {
106               char **inv_fs = bsearch( &nfs_types[i], &valid_fs[0],
107                                        fs_entries, sizeof(valid_fs[0]),
108                                        compare_fs_type );
109               if( NULL != inv_fs ) {
110                   /* copy including trailing NULL pointer */
111                   memmove( inv_fs, inv_fs + 1, fs_entries - (inv_fs - valid_fs) );
112                   --fs_entries;
113               }
114           }
115           sg_set_valid_filesystems( valid_fs );
116           free( valid_fs );
117       }
118
119
120       Note that there's no need to duplicate the  strings  contained  in  the
121       list of valid file systems in the above example - they aren't modified.
122
123       The  list  returned  by sg_get_valid_filesystems() might become invalid
124       when used while the process makes calls to  sg_set_valid_filesystems().
125       None  of  the  sg_fs_stats functions protect the access to the globally
126       used storage where the own copy of the list of the valid  file  systems
127       is held. It's the responsibility of the caller not to mix configuration
128       calls with calls to fetch statistics.
129
130       Additionally  two  support  functions  for  qsort(3)   are   available:
131       sg_fs_compare_device_name() and sg_fs_compare_mnt_point().
132
133       Sort Example
134
135       size_t entries;
136       sg_fs_stats *fs_stats = NULL;
137       while( NULL != ( fs_stats = sg_get_fs_stats_diff(&entries) ) ) {
138           /* order entries alphabetically using the mountpoint */
139           qsort( fs_stats, entries, sizeof(fs_stats[0]), &sg_fs_compare_mnt_point );
140           show_fs_stats( fs_stats );
141       }
142
143

RETURN VALUES

145       sg_get_fs_stats returns a pointer to a structure of type sg_fs_stats.
146
147       typedef enum {
148               sg_fs_unknown  = 0,
149               sg_fs_regular  = 1 << 0,
150               sg_fs_special  = 1 << 1,
151               sg_fs_loopback = 1 << 2,
152               sg_fs_remote   = 1 << 3,
153               sg_fs_local    = (sg_fs_regular | sg_fs_special),
154               sg_fs_alltypes = (sg_fs_regular | sg_fs_special | sg_fs_loopback | sg_fs_remote)
155       } sg_fs_device_type;
156
157
158       typedef struct {
159               char *device_name;
160               char *fs_type;
161               char *mnt_point;
162               sg_fs_device_type device_type;
163               unsigned long long size;
164               unsigned long long used;
165               unsigned long long free;
166               unsigned long long avail;
167               unsigned long long total_inodes;
168               unsigned long long used_inodes;
169               unsigned long long free_inodes;
170               unsigned long long avail_inodes;
171               unsigned long long io_size;
172               unsigned long long block_size;
173               unsigned long long total_blocks;
174               unsigned long long free_blocks;
175               unsigned long long used_blocks;
176               unsigned long long avail_blocks;
177               time_t systime;
178       } sg_fs_stats;
179
180
181       device_name
182              The  name known to the operating system.  (eg. on linux it might
183              be hda)
184
185       fs_type
186              The file system type of the file system (eg. hpfs or ufs).
187
188       mnt_point
189              The mount point at which the file system is mounted.
190
191       device_type
192              The device type of the file system, currently not filled and al‐
193              ways sg_fs_unknown.
194
195       size   The total size, in bytes, of the file system.
196
197              size = used + free
198
199       used   The amount of space, in bytes, used on the file system.
200
201       avail  The  amount of space, in bytes, available on the file system for
202              non-privileged users/processes (free space less reserved space).
203
204              avail = free - reserved
205
206       free   The amount of space, in bytes, free on the file system.
207
208       total_inodes
209              The total number of inodes in the file system.
210
211       used_inodes
212              The number of used inodes in the file system.
213
214       free_inodes
215              The number of free inodes in the file system.
216
217       avail_inodes
218              The number of free inodes available to non-privileged processes.
219
220       io_size
221              A suggested optimal block size for I/O operations --  if  you're
222              reading or writing lots of data, do it in chunks of this size.
223
224       block_size
225              The size in bytes of the minimum unit of allocation on this file
226              system.
227
228       total_blocks
229              The total number of blocks in the file system.
230
231       free_blocks
232              The number of free blocks in the file system.
233
234       used_blocks
235              The number of used blocks in the file system.
236
237       avail_blocks
238              The number of free blocks available to non-privileged processes.
239
240       systime
241              The time in seconds since epoch when the statistic was retrieved
242              from kernel.
243

BUGS

245       Only mounted file systems are recognised.
246
247       Some  file  systems  might  be reported twice when mounted on different
248       mount points.
249
250       The compare functions exist rather for backward compatibility than  for
251       functionality  enhancements.  Limited  flexibility (e.g. reverse order)
252       and lack of optimising opportunities for the compiler leads to the rec‐
253       ommendation to implement the required compare routines locally.
254
255       Calling  sg_set_valid_filesystems with an empty list with clear the in‐
256       ternal list of valid file systems. There's currently no way to reset to
257       the initial list.
258

SEE ALSO

260       statgrab(3)
261

WEBSITE

263http://www.i-scream.org/libstatgrab/
264
265
266
267i-scream                          2013-06-20                sg_get_fs_stats(3)
Impressum