1explain_ustat(3)           Library Functions Manual           explain_ustat(3)
2
3
4

NAME

6       explain_ustat - explain ustat(2) errors
7

SYNOPSIS

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

DESCRIPTION

19       These functions may be used to obtain explanations for errors  returned
20       by the ustat(2) system call.
21
22   explain_ustat
23       const char *explain_ustat(dev_t dev, struct ustat *ubuf);
24
25       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
30       The errno global variable will be used to obtain the error value to  be
31       decoded.
32
33       dev     The  original  dev,  exactly  as  passed to the ustat(2) system
34               call.
35
36       ubuf    The original ubuf, exactly as passed  to  the  ustat(2)  system
37               call.
38
39       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
46       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
49       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
57       The   above   code   example   is   available   pre‐packaged   as   the
58       explain_ustat_or_die(3) function.
59
60   explain_errno_ustat
61       const char *explain_errno_ustat(int errnum, dev_t dev, struct ustat
62       *ubuf);
63
64       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
69       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
75       dev     The original dev, exactly as  passed  to  the  ustat(2)  system
76               call.
77
78       ubuf    The  original  ubuf,  exactly  as passed to the ustat(2) system
79               call.
80
81       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
88       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
91       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
101       The   above   code   example   is   available   pre‐packaged   as   the
102       explain_ustat_or_die(3) function.
103
104   explain_message_ustat
105       void explain_message_ustat(char *message, int message_size, dev_t dev,
106       struct ustat *ubuf);
107
108       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
113       The errno global variable will be used to obtain the error value to  be
114       decoded.
115
116       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
120       message_size
121               The  size  in  bytes  of  the  location  in  which to store the
122               returned message.
123
124       dev     The original dev, exactly as  passed  to  the  ustat(2)  system
125               call.
126
127       ubuf    The  original  ubuf,  exactly  as passed to the ustat(2) system
128               call.
129
130       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
140       The   above   code   example   is   available   pre‐packaged   as   the
141       explain_ustat_or_die(3) function.
142
143   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
147       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
152       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
156       message_size
157               The size in bytes  of  the  location  in  which  to  store  the
158               returned message.
159
160       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
166       dev     The  original  dev,  exactly  as  passed to the ustat(2) system
167               call.
168
169       ubuf    The original ubuf, exactly as passed  to  the  ustat(2)  system
170               call.
171
172       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
184       The   above   code   example   is   available   pre‐packaged   as   the
185       explain_ustat_or_die(3) function.
186

SEE ALSO

188       ustat(2)
189               get file system statistics
190
191       explain_ustat_or_die(3)
192               get file system statistics and report errors
193
195       libexplain version 0.40
196       Copyright (C) 2009 Peter Miller
197
198
199
200                                                              explain_ustat(3)
Impressum