1explain_ustat(3) Library Functions Manual explain_ustat(3)
2
6 explain_ustat - explain ustat(2) errors
7
9 #include <libexplain/ustat.h>
10 const char *explain_ustat(dev_t dev, struct ustat *ubuf);
11 const char *explain_errno_ustat(int errnum, dev_t dev, struct ustat
12 *ubuf);
13 void explain_message_ustat(char *message, int message_size, dev_t dev,
14 struct ustat *ubuf);
15 void explain_message_errno_ustat(char *message, int message_size, int
16 errnum, dev_t dev, struct ustat *ubuf);
17
19 These functions may be used to obtain explanations for errors returned
20 by the ustat(2) system call.
21 explain_ustat
23 const char *explain_ustat(dev_t dev, struct ustat *ubuf);
24 The explain_ustat function is used to obtain an explanation of an error
26 returned by the ustat(2) system call. The least the message will con‐
27 tain is the value of strerror(errno), but usually it will do much bet‐
28 ter, and indicate the underlying cause in more detail.
29 The errno global variable will be used to obtain the error value to be
31 decoded.
32 dev The original dev, exactly as passed to the ustat(2) system
34 call.
35 ubuf The original ubuf, exactly as passed to the ustat(2) system
37 call.
38 Returns:
40 The message explaining the error. This message buffer is shared
41 by all libexplain functions which do not supply a buffer in
42 their argument list. This will be overwritten by the next call
43 to any libexplain function which shares this buffer, including
44 other threads.
45 Note: This function is not thread safe, because it shares a return buf‐
47 fer across all threads, and many other functions in this library.
48 Example: This function is intended to be used in a fashion similar to
50 the following example:
51 if (ustat(dev, ubuf) < 0)
52 {
53 fprintf(stderr, "%s\n", explain_ustat(dev, ubuf));
54 exit(EXIT_FAILURE);
55 }
56 The above code example is available pre‐packaged as the
58 explain_ustat_or_die(3) function.
59 explain_errno_ustat
61 const char *explain_errno_ustat(int errnum, dev_t dev, struct ustat
62 *ubuf);
63 The explain_errno_ustat function is used to obtain an explanation of an
65 error returned by the ustat(2) system call. The least the message will
66 contain is the value of strerror(errno), but usually it will do much
67 better, and indicate the underlying cause in more detail.
68 errnum The error value to be decoded, usually obtained from the errno
70 global variable just before this function is called. This is
71 necessary if you need to call any code between the system call
72 to be explained and this function, because many libc functions
73 will alter the value of errno.
74 dev The original dev, exactly as passed to the ustat(2) system
76 call.
77 ubuf The original ubuf, exactly as passed to the ustat(2) system
79 call.
80 Returns:
82 The message explaining the error. This message buffer is shared
83 by all libexplain functions which do not supply a buffer in
84 their argument list. This will be overwritten by the next call
85 to any libexplain function which shares this buffer, including
86 other threads.
87 Note: This function is not thread safe, because it shares a return buf‐
89 fer across all threads, and many other functions in this library.
90 Example: This function is intended to be used in a fashion similar to
92 the following example:
93 if (ustat(dev, ubuf) < 0)
94 {
95 int err = errno;
96 fprintf(stderr, "%s\n", explain_errno_ustat(err, dev,
97 ubuf));
98 exit(EXIT_FAILURE);
99 }
100 The above code example is available pre‐packaged as the
102 explain_ustat_or_die(3) function.
103 explain_message_ustat
105 void explain_message_ustat(char *message, int message_size, dev_t dev,
106 struct ustat *ubuf);
107 The explain_message_ustat function is used to obtain an explanation of
109 an error returned by the ustat(2) system call. The least the message
110 will contain is the value of strerror(errno), but usually it will do
111 much better, and indicate the underlying cause in more detail.
112 The errno global variable will be used to obtain the error value to be
114 decoded.
115 message The location in which to store the returned message. If a suit‐
117 able message return buffer is supplied, this function is thread
118 safe.
119 message_size
121 The size in bytes of the location in which to store the
122 returned message.
123 dev The original dev, exactly as passed to the ustat(2) system
125 call.
126 ubuf The original ubuf, exactly as passed to the ustat(2) system
128 call.
129 Example: This function is intended to be used in a fashion similar to
131 the following example:
132 if (ustat(dev, ubuf) < 0)
133 {
134 char message[3000];
135 explain_message_ustat(message, sizeof(message), dev, ubuf);
136 fprintf(stderr, "%s\n", message);
137 exit(EXIT_FAILURE);
138 }
139 The above code example is available pre‐packaged as the
141 explain_ustat_or_die(3) function.
142 explain_message_errno_ustat
144 void explain_message_errno_ustat(char *message, int message_size, int
145 errnum, dev_t dev, struct ustat *ubuf);
146 The explain_message_errno_ustat function is used to obtain an explana‐
148 tion of an error returned by the ustat(2) system call. The least the
149 message will contain is the value of strerror(errno), but usually it
150 will do much better, and indicate the underlying cause in more detail.
151 message The location in which to store the returned message. If a suit‐
153 able message return buffer is supplied, this function is thread
154 safe.
155 message_size
157 The size in bytes of the location in which to store the
158 returned message.
159 errnum The error value to be decoded, usually obtained from the errno
161 global variable just before this function is called. This is
162 necessary if you need to call any code between the system call
163 to be explained and this function, because many libc functions
164 will alter the value of errno.
165 dev The original dev, exactly as passed to the ustat(2) system
167 call.
168 ubuf The original ubuf, exactly as passed to the ustat(2) system
170 call.
171 Example: This function is intended to be used in a fashion similar to
173 the following example:
174 if (ustat(dev, ubuf) < 0)
175 {
176 int err = errno;
177 char message[3000];
178 explain_message_errno_ustat(message, sizeof(message), err,
179 dev, ubuf);
180 fprintf(stderr, "%s\n", message);
181 exit(EXIT_FAILURE);
182 }
183 The above code example is available pre‐packaged as the
185 explain_ustat_or_die(3) function.
186
188 ustat(2)
189 get file system statistics
190 explain_ustat_or_die(3)
192 get file system statistics and report errors
193
195 libexplain version 1.4
196 Copyright (C) 2009 Peter Miller
197 explain_ustat(3)