1explain_open(3) Library Functions Manual explain_open(3)
2
6 explain_open - explain open(2) errors
7
9 #include <libexplain/open.h>
10 const char *explain_open(const char *pathname, int flags, int mode);
11 const char *explain_errno_open(int errnum, const char *pathname, int
12 flags, int mode);
13 void explain_message_open(char *message, int message_size, const char
14 *pathname, int flags, int mode);
15 void explain_message_errno_open(char *message, int message_size, int
16 errnum, const char *pathname, int flags, int mode);
17
19 These functions may be used to obtains explanations for open(2) errors.
20 explain_open(const char *pathname, int flags, int mode);
22 const char *explain_open(const char *pathname, int flags, int mode);
23 The explain_open function is used to obtain an explanation of an error
25 returned by the open(2) system call. The least the message will con‐
26 tain is the value of strerror(errno), but usually it will do much bet‐
27 ter, and indicate the underlying cause in more detail.
28 The errno global variable will be used to obtain the error value to be
30 decoded.
31 This function is intended to be used in a fashion similar to the fol‐
33 lowing example:
34 int fd = open(pathname, flags, mode);
35 if (fd < 0)
36 {
37 fprintf(stderr, '%s0, explain_open(pathname, flags, mode));
38 exit(EXIT_FAILURE);
39 }
40 pathname
42 The original pathname, exactly as passed to the open(2) system
43 call.
44 flags The original flags, exactly as passed to the open(2) system
46 call.
47 mode The original mode, exactly as passed to the open(2) system call
49 (or zero if the original call didn't need a mode argument).
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_errno_open
62 const char *explain_errno_open(int errnum, const char *pathname, int
63 flags, int mode);
64 The explain_errno_open function is used to obtain an explanation of an
66 error returned by the open(2) system call. The least the message will
67 contain is the value of strerror(errnum), but usually it will do much
68 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 int fd = open(pathname, flags, mode);
73 if (fd < 0)
74 {
75 int err = errno;
76 fprintf(stderr, '%s0, explain_errno_open(err, pathname,
77 flags, mode));
78 exit(EXIT_FAILURE);
79 }
80 errnum The error value to be decoded, usually obtained from the errno
82 global variable just before this function is called. This is
83 necessary if you need to call any code between the system call
84 to be explained and this function, because many libc functions
85 will alter the value of errno.
86 pathname
88 The original pathname, exactly as passed to the open(2) system
89 call.
90 flags The original flags, exactly as passed to the open(2) system
92 call.
93 mode The original mode, exactly as passed to the open(2) system call
95 (or zero if the original call didn't need a mode argument).
96 Returns:
98 The message explaining the error. This message buffer is
99 shared by all libexplain functions which do not supply a buffer
100 in their argument list. This will be overwritten by the next
101 call to any libexplain function which shares this buffer,
102 including other threads.
103 Note: This function is not thread safe, because it shares a return buf‐
105 fer across all threads, and many other functions in this library.
106 explain_message_open
108 void explain_message_open(char *message, int message_size, const char
109 *pathname, int flags, int mode);
110 The explain_message_open function is used to obtain an explanation of
112 an error returned by the open(2) system call. The least the message
113 will contain is the value of strerror(errno), but usually it will do
114 much better, and indicate the underlying cause in more detail.
115 The errno global variable will be used to obtain the error value to be
117 decoded.
118 This function is intended to be used in a fashion similar to the fol‐
120 lowing example:
121 int fd = open(pathname, flags, mode);
122 if (fd < 0)
123 {
124 char message[3000];
125 explain_message_open(message, sizeof(message), pathname, flags,
126 mode);
127 fprintf(stderr, '%s0, message);
128 exit(EXIT_FAILURE);
129 }
130 message The location in which to store the returned message. Because a
132 message return buffer has been supplied, this function is
133 thread safe.
134 message_size
136 The size in bytes of the location in which to store the
137 returned message.
138 pathname
140 The original pathname, exactly as passed to the open(2) system
141 call.
142 flags The original flags, exactly as passed to the open(2) system
144 call.
145 mode The original mode, exactly as passed to the open(2) system call
147 (or zero if the original call didn't need a mode argument).
148 explain_message_errno_open
150 void explain_message_errno_open(char *message, int message_size, int
151 errnum, const char *pathname, int flags, int mode);
152 The explain_message_errno_open function is used to obtain an explana‐
154 tion of an error returned by the open(2) system call. The least the
155 message will contain is the value of strerror(errnum), but usually it
156 will do much better, and indicate the underlying cause in more detail.
157 This function is intended to be used in a fashion similar to the fol‐
159 lowing exameple:
160 int fd = open(pathname, flags, mode);
161 if (fd < 0)
162 {
163 int err = errno;
164 char message[3000];
165 explain_message_errno_open(message, sizeof(message), err, pathname,
166 flags, mode);
167 fprintf(stderr, '%s0, message);
168 exit(EXIT_FAILURE);
169 }
170 message The location in which to store the returned message. Because a
172 message return buffer has been supplied, this function is
173 thread safe.
174 message_size
176 The size in bytes of the location in which to store the
177 returned message.
178 errnum The error value to be decoded, usually obtained from the errno
180 global variable just before this function is called. This is
181 necessary if you need to call any code between the system call
182 to be explained and this function, because many libc functions
183 will alter the value of errno.
184 pathname
186 The original pathname, exactly as passed to the open(2) system
187 call.
188 flags The original flags, exactly as passed to the open(2) system
190 call.
191 mode The original mode, exactly as passed to the open(2) system call
193 (or zero if the original call didn't need a mode argument).
194
196 libexplain version 1.4
197 Copyright (C) 2008 Peter Miller
198
200 Written by Peter Miller <pmiller@opensource.org.au>
201 explain_open(3)