1sg_get_fs_stats(3) sg_get_fs_stats(3)
2
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
12 #include <statgrab.h>
13 sg_fs_stats *sg_get_fs_stats (size_t *entries);
16 sg_fs_stats *sg_get_fs_stats_r (size_t *entries);
18 sg_fs_stats *sg_get_fs_stats_diff (size_t *entries);
20 sg_fs_stats *sg_get_fs_stats_diff_between (const sg_fs_stats *cur,
22 const sg_fs_stats *last, size_t *entries);
23 sg_error sg_free_fs_stats (sg_fs_stats *data);
25 const char **sg_get_valid_filesystems (size_t *entries);
27 sg_error sg_set_valid_filesystems (const char *valid_fs[]);
29 int sg_fs_compare_device_name (const void *va, const void *vb);
31 int sg_fs_compare_mnt_point (const void *va, const void *vb);
33
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 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 API Shortcut
46 ┌─────────────────────────┬───────────────┬─────────────────────┐
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 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 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 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 Remove Network FS Example
87 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 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 /* 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 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 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 Additionally two support functions for qsort(3) are available:
131 sg_fs_compare_device_name() and sg_fs_compare_mnt_point().
132 Sort Example
134 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
145 sg_get_fs_stats returns a pointer to a structure of type sg_fs_stats.
146 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 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 device_name
182 The name known to the operating system. (eg. on linux it might
183 be hda)
184 fs_type
186 The file system type of the file system (eg. hpfs or ufs).
187 mnt_point
189 The mount point at which the file system is mounted.
190 device_type
192 The device type of the file system, currently not filled and al‐
193 ways sg_fs_unknown.
194 size The total size, in bytes, of the file system.
196 size = used + free
198 used The amount of space, in bytes, used on the file system.
200 avail The amount of space, in bytes, available on the file system for
202 non-privileged users/processes (free space less reserved space).
203 avail = free - reserved
205 free The amount of space, in bytes, free on the file system.
207 total_inodes
209 The total number of inodes in the file system.
210 used_inodes
212 The number of used inodes in the file system.
213 free_inodes
215 The number of free inodes in the file system.
216 avail_inodes
218 The number of free inodes available to non-privileged processes.
219 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 block_size
225 The size in bytes of the minimum unit of allocation on this file
226 system.
227 total_blocks
229 The total number of blocks in the file system.
230 free_blocks
232 The number of free blocks in the file system.
233 used_blocks
235 The number of used blocks in the file system.
236 avail_blocks
238 The number of free blocks available to non-privileged processes.
239 systime
241 The time in seconds since epoch when the statistic was retrieved
242 from kernel.
243
245 Only mounted file systems are recognised.
246 Some file systems might be reported twice when mounted on different
248 mount points.
249 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 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
260 statgrab(3)
261
263 ⟨http://www.i-scream.org/libstatgrab/⟩
264i-scream 2013-06-20 sg_get_fs_stats(3)