1explain_fgets(3) Library Functions Manual explain_fgets(3)
2
6 explain_fgets - explain fgets(3) errors
7
9 #include <libexplain/fgets.h>
10 const char *explain_fgets(char *data, int data_size, FILE *fp);
11 const char *explain_errno_fgets(int errnum, char *data, int data_size,
12 FILE *fp);
13 void explain_message_fgets(char *message, int message_size, char *data,
14 int data_size, FILE *fp);
15 void explain_message_errno_fgets(char *message, int message_size, int
16 errnum, char *data, int data_size, FILE *fp);
17
19 These functions may be used to obtain explanations for errors returned
20 by the fgets(3) system call.
21 explain_fgets
23 const char *explain_fgets(char *data, int data_size, FILE *fp);
24 The explain_fgets function is used to obtain an explanation of an error
26 returned by the fgets(3) 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 This function is intended to be used in a fashion similar to the fol‐
34 lowing example:
35 if (fgets(data, data_size, fp) < 0)
36 {
37 fprintf(stderr, "%s\n", explain_fgets(data, data_size, fp));
38 exit(EXIT_FAILURE);
39 }
40 data The original data, exactly as passed to the fgets(3) system
42 call.
43 data_size
45 The original data_size, exactly as passed to the fgets(3) sys‐
46 tem call.
47 fp The original fp, exactly as passed to the fgets(3) system call.
49 Returns:
51 The message explaining the error. This message buffer is
52 shared by all libexplain functions which do not supply a buffer
53 in their argument list. This will be overwritten by the next
54 call to any libexplain function which shares this buffer,
55 including other threads.
56 Note: This function is not thread safe, because it shares a return buf‐
58 fer across all threads, and many other functions in this library.
59 explain_errno_fgets
61 const char *explain_errno_fgets(int errnum, char *data, int data_size,
62 FILE *fp);
63 The explain_errno_fgets function is used to obtain an explanation of an
65 error returned by the fgets(3) system call. The least the message will
66 contain is the value of strerror(errnum), but usually it will do much
67 better, and indicate the underlying cause in more detail.
68 This function is intended to be used in a fashion similar to the fol‐
70 lowing example:
71 if (fgets(data, data_size, fp) < 0)
72 {
73 int err = errno;
74 fprintf(stderr, "%s\n", explain_errno_fgets(err, data, data_size, fp));
75 exit(EXIT_FAILURE);
76 }
77 errnum The error value to be decoded, usually obtained from the errno
79 global variable just before this function is called. This is
80 necessary if you need to call any code between the system call
81 to be explained and this function, because many libc functions
82 will alter the value of errno.
83 data The original data, exactly as passed to the fgets(3) system
85 call.
86 data_size
88 The original data_size, exactly as passed to the fgets(3) sys‐
89 tem call.
90 fp The original fp, exactly as passed to the fgets(3) system call.
92 Returns:
94 The message explaining the error. This message buffer is
95 shared by all libexplain functions which do not supply a buffer
96 in their argument list. This will be overwritten by the next
97 call to any libexplain function which shares this buffer,
98 including other threads.
99 Note: This function is not thread safe, because it shares a return buf‐
101 fer across all threads, and many other functions in this library.
102 explain_message_fgets
104 void explain_message_fgets(char *message, int message_size, char *data,
105 int data_size, FILE *fp);
106 The explain_message_fgets function may be used to obtain an explana‐
108 tion of an error returned by the fgets(3) system call. The least the
109 message will contain is the value of strerror(errno), but usually it
110 will do much better, and indicate the underlying cause in more detail.
111 The errno global variable will be used to obtain the error value to be
113 decoded.
114 This function is intended to be used in a fashion similar to the fol‐
116 lowing example:
117 if (fgets(data, data_size, fp) < 0)
118 {
119 char message[3000];
120 explain_message_fgets(message, sizeof(message), data, data_size, fp);
121 fprintf(stderr, "%s\n", message);
122 exit(EXIT_FAILURE);
123 }
124 message The location in which to store the returned message. If a
126 suitable message return buffer is supplied, this function is
127 thread safe.
128 message_size
130 The size in bytes of the location in which to store the
131 returned message.
132 data The original data, exactly as passed to the fgets(3) system
134 call.
135 data_size
137 The original data_size, exactly as passed to the fgets(3) sys‐
138 tem call.
139 fp The original fp, exactly as passed to the fgets(3) system call.
141 explain_message_errno_fgets
143 void explain_message_errno_fgets(char *message, int message_size, int
144 errnum, char *data, int data_size, FILE *fp);
145 The explain_message_errno_fgets function may be used to obtain an
147 explanation of an error returned by the fgets(3) system call. The
148 least the message will contain is the value of strerror(errnum), but
149 usually it will do much better, and indicate the underlying cause in
150 more detail.
151 This function is intended to be used in a fashion similar to the fol‐
153 lowing example:
154 if (fgets(data, data_size, fp) < 0)
155 {
156 int err = errno;
157 char message[3000];
158 explain_message_errno_fgets(message, sizeof(message), err,
159 data, data_size, fp);
160 fprintf(stderr, "%s\n", message);
161 exit(EXIT_FAILURE);
162 }
163 message The location in which to store the returned message. If a
165 suitable message return buffer is supplied, this function is
166 thread safe.
167 message_size
169 The size in bytes of the location in which to store the
170 returned message.
171 errnum The error value to be decoded, usually obtained from the errno
173 global variable just before this function is called. This is
174 necessary if you need to call any code between the system call
175 to be explained and this function, because many libc functions
176 will alter the value of errno.
177 data The original data, exactly as passed to the fgets(3) system
179 call.
180 data_size
182 The original data_size, exactly as passed to the fgets(3) sys‐
183 tem call.
184 fp The original fp, exactly as passed to the fgets(3) system call.
186
188 fgets(3)
189 input of strings
190 explain_fgets_or_die(3)
192 input of strings and report errors
193
195 libexplain version 0.40
196 Copyright (C) 2008 Peter Miller
197 explain_fgets(3)