1explain_stat(3) Library Functions Manual explain_stat(3)
2
6 explain_stat - explain stat(2) errors
7
9 #include <libexplain/stat.h>
10 const char *explain_stat(const char *pathname, const struct stat *buf);
11 void explain_message_stat(char *message, int message_size, const char
12 *pathname, const struct stat *buf);
13 const char *explain_errno_stat(int errnum, const char *pathname, const
14 struct stat *buf);
15 void explain_message_errno_stat(char *message, int message_size, int
16 errnum, const char *pathname, const struct stat *buf);
17
19 These functions may be used to obtain explanations for stat(2) errors .
20 explain_errno_stat
22 const char *explain_errno_stat(int errnum, const char *pathname, const
23 struct stat *buf);
24 The explain_errno_stat function is used to obtain an explanation of an
26 error returned by the stat(2) function. The least the message will
27 contain is the value of strerror(errnum), but usually it will do much
28 better, and indicate the underlying cause in more detail.
29 This function is intended to be used in a fashion similar to the fol‐
31 lowing example:
32 if (stat(pathname, &buf) < 0)
33 {
34 int err = errno;
35 fprintf(stderr, "%s\n", explain_errno_stat(err, pathname, &buf));
36 exit(EXIT_FAILURE);
37 }
38 errnum The error value to be decoded, usually obtained from the errno
40 global variable just before this function is called. This is
41 necessary if you need to call any code between the system call
42 to be explained and this function, because many libc functions
43 will alter the value of errno.
44 pathname
46 The original pathname, exactly as passed to the stat(2) system
47 call.
48 buf The original buf, exactly as passed to the stat(2) system call.
50 Returns:
52 The message explaining the error. This message buffer is
53 shared by all libexplain functions which do not supply a buffer
54 in their argument list. This will be overwritten by the next
55 call to any libexplain function which shares this buffer,
56 including other threads.
57 Note: This function is not thread safe, because it shares a return buf‐
59 fer across all threads, and many other functions in this library.
60 explain_message_errno_stat
62 void explain_message_errno_stat(char *message, int message_size, int
63 errnum, const char *pathname, const struct stat *buf);
64 The explain_message_errno_stat function is used to obtain an explana‐
66 tion of an error returned by the stat(2) function. The least the mes‐
67 sage will contain is the value of strerror(errnum), but usually it will
68 do much better, and indicate the underlying cause in more detail.
69 This function is intended to be used in a fashion similar to the fol‐
71 lowing example:
72 if (stat(pathname, &buf) < 0)
73 {
74 int err = errno;
75 char message[3000];
76 explain_message_errno_stat(message, sizeof(message), err,
77 pathname, &buf);
78 fprintf(stderr, "%s\n", message);
79 exit(EXIT_FAILURE);
80 }
81 message The location in which to store the returned message. Because a
83 message return buffer has been supplied, this function is
84 thread safe.
85 message_size
87 The size in bytes of the location in which to store the
88 returned message.
89 errnum The error value to be decoded, usually obtained from the errno
91 global variable just before this function is called. This is
92 necessary if you need to call any code between the system call
93 to be explained and this function, because many libc functions
94 will alter the value of errno.
95 pathname
97 The original pathname, exactly as passed to the stat(2) system
98 call.
99 buf The original buf, exactly as passed to the stat(2) system call.
101 explain_message_stat
103 void explain_message_stat(char *message, int message_size, const char
104 *pathname, const struct stat *buf);
105 The explain_message_stat function is used to obtain an explanation of
107 an error returned by the stat(2) function. The least the message will
108 contain is the value of strerror(errno), but usually it will do much
109 better, and indicate the underlying cause in more detail.
110 The errno global variable will be used to obtain the error value to be
112 decoded.
113 This function is intended to be used in a fashion similar to the fol‐
115 lowing example:
116 if (stat(pathname, &buf) < 0)
117 {
118 char message[3000];
119 explain_message_stat(message, sizeof(message), pathname, &buf);
120 fprintf(stderr, "%s\n", message);
121 exit(EXIT_FAILURE);
122 }
123 message The location in which to store the returned message. Because a
125 message return buffer has been supplied, this function is
126 thread safe.
127 message_size
129 The size in bytes of the location in which to store the
130 returned message.
131 pathname
133 The original pathname, exactly as passed to the stat(2) system
134 call.
135 buf The original buf, exactly as passed to the stat(2) system call.
137 explain_stat
139 const char *explain_stat(const char *pathname, const struct stat *
140 buf);
141 The explain_stat function is used to obtain an explanation of an error
143 returned by the stat(2) function. The least the message will contain
144 is the value of strerror(errno), but usually it will do much better,
145 and indicate the underlying cause in more detail.
146 The errno global variable will be used to obtain the error value to be
148 decoded.
149 This function is intended to be used in a fashion similar to the fol‐
151 lowing example:
152 if (stat(pathname, &buf) < 0)
153 {
154 fprintf(stderr, "%s\n", explain_stat(pathname, &buf));
155 exit(EXIT_FAILURE);
156 }
157 pathname
159 The original pathname, exactly as passed to the stat(2) system
160 call.
161 buf The original buf, exactly as passed to the stat(2) system call.
163 Returns:
165 The message explaining the error. This message buffer is
166 shared by all libexplain functions which do not supply a buffer
167 in their argument list. This will be overwritten by the next
168 call to any libexplain function which shares this buffer,
169 including other threads.
170 Note: This function is not thread safe, because it shares a return buf‐
172 fer across all threads, and many other functions in this library.
173
175 libexplain version 1.4
176 Copyright (C) 2008 Peter Miller
177
179 Written by Peter Miller <pmiller@opensource.org.au>
180 explain_stat(3)