1explain_freopen(3) Library Functions Manual explain_freopen(3)
2
6 explain_freopen - explain freopen(3) errors
7
9 #include <libexplain/freopen.h>
10 const char *explain_freopen(const char *pathname, const char *flags,
11 FILE *fp);
12 const char *explain_errno_freopen(int errnum, const char *pathname,
13 const char *flags, FILE *fp);
14 void explain_message_freopen(char *message, int message_size, const
15 char *pathname, const char *flags, FILE *fp);
16 void explain_message_errno_freopen(char *message, int message_size, int
17 errnum, const char *pathname, const char *flags, FILE *fp);
18
20 These functions may be used to obtain explanations for freopen(3)
21 errors.
22 explain_freopen
24 const char *explain_freopen(const char *pathname, const char *flags,
25 FILE *fp);
26 The explain_freopen function is used to obtain an explanation of an
28 error returned by the freopen(3) system call. The least the message
29 will contain is the value of strerror(errno), but usually it will do
30 much better, and indicate the underlying cause in more detail.
31 The errno global variable will be used to obtain the error value to be
33 decoded.
34 This function is intended to be used in a fashion similar to the fol‐
36 lowing example:
37 if (!freopen(pathname, flags, fp))
38 {
39 fprintf(stderr, '%s0, explain_freopen(pathname, flags, fp));
40 exit(EXIT_FAILURE);
41 }
42 pathname
44 The original pathname, exactly as passed to the freopen(3) sys‐
45 tem call.
46 flags The original flags, exactly as passed to the freopen(3) system
48 call.
49 fp The original fp, exactly as passed to the freopen(3) system
51 call.
52 Returns:
54 The message explaining the error. This message buffer is
55 shared by all libexplain functions which do not supply a buffer
56 in their argument list. This will be overwritten by the next
57 call to any libexplain function which shares this buffer,
58 including other threads.
59 Note: This function is not thread safe, because it shares a return buf‐
61 fer across all threads, and many other functions in this library.
62 explain_errno_freopen
64 const char *explain_errno_freopen(int errnum, const char *pathname,
65 const char *flags, FILE *fp);
66 The explain_errno_freopen function is used to obtain an explanation of
68 an error returned by the freopen(3) system call. The least the message
69 will contain is the value of strerror(errnum), but usually it will do
70 much better, and indicate the underlying cause in more detail.
71 This function is intended to be used in a fashion similar to the fol‐
73 lowing example:
74 if (freopen(pathname, flags, fp))
75 {
76 int err = errno;
77 fprintf(stderr, '%s0, explain_errno_freopen(err, pathname,
78 flags, fp));
79 exit(EXIT_FAILURE);
80 }
81 errnum The error value to be decoded, usually obtained from the errno
83 global variable just before this function is called. This is
84 necessary if you need to call any code between the system call
85 to be explained and this function, because many libc functions
86 will alter the value of errno.
87 pathname
89 The original pathname, exactly as passed to the freopen(3) sys‐
90 tem call.
91 flags The original flags, exactly as passed to the freopen(3) system
93 call.
94 fp The original fp, exactly as passed to the freopen(3) system
96 call.
97 Returns:
99 The message explaining the error. This message buffer is
100 shared by all libexplain functions which do not supply a buffer
101 in their argument list. This will be overwritten by the next
102 call to any libexplain function which shares this buffer,
103 including other threads.
104 Note: This function is not thread safe, because it shares a return buf‐
106 fer across all threads, and many other functions in this library.
107 explain_message_freopen
109 void explain_message_freopen(char *message, int message_size, const
110 char *pathname, const char *flags, FILE *fp);
111 The explain_message_freopen function is used to obtain an explanation
113 of an error returned by the freopen(3) system call. The least the mes‐
114 sage will contain is the value of strerror(errno), but usually it will
115 do much better, and indicate the underlying cause in more detail.
116 The errno global variable will be used to obtain the error value to be
118 decoded.
119 This function is intended to be used in a fashion similar to the fol‐
121 lowing example:
122 if (!freopen(pathname, flags, fp))
123 {
124 char message[3000];
125 explain_message_freopen(message, sizeof(message), pathname, flags,
126 fp);
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 freopen(3) sys‐
141 tem call.
142 flags The original flags, exactly as passed to the freopen(3) system
144 call.
145 fp The original fp, exactly as passed to the freopen(3) system
147 call.
148 explain_message_errno_freopen
150 void explain_message_errno_freopen(char *message, int message_size, int
151 errnum, const char *pathname, const char *flags, FILE *fp);
152 The explain_message_errno_freopen function is used to obtain an expla‐
154 nation of an error returned by the freopen(3) system call. The least
155 the message will contain is the value of strerror(errnum), but usually
156 it will do much better, and indicate the underlying cause in more
157 detail.
158 This function is intended to be used in a fashion similar to the fol‐
160 lowing example:
161 if (!freopen(pathname, flags, fp))
162 {
163 int err = errno;
164 char message[3000];
165 explain_message_errno_freopen(message, sizeof(message), err,
166 pathname, flags, fp);
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 freopen(3) sys‐
187 tem call.
188 flags The original flags, exactly as passed to the freopen(3) system
190 call.
191 fp The original fp, exactly as passed to the freopen(3) system
193 call.
194
196 libexplain version 1.4
197 Copyright (C) 2008 Peter Miller
198
200 Written by Peter Miller <pmiller@opensource.org.au>
201 explain_freopen(3)