1explain_fgetc(3) Library Functions Manual explain_fgetc(3)
2
6 explain_fgetc - explain fgetc(3) errors
7
9 #include <libexplain/fgetc.h>
10 const char *explain_fgetc(FILE *fp);
11 const char *explain_errno_fgetc(int errnum, FILE *fp);
12 void explain_message_fgetc(char *message, int message_size, FILE *fp);
13 void explain_message_errno_fgetc(char *message, int message_size, int
14 errnum, FILE *fp);
15
17 These functions may be used to obtain explanations for errors returned
18 by the fgetc(3) system call.
19 explain_fgetc
21 const char *explain_fgetc(FILE *fp);
22 The explain_fgetc function is used to obtain an explanation of an error
24 returned by the fgetc(3) system call. The least the message will con‐
25 tain is the value of strerror(errno), but usually it will do much bet‐
26 ter, and indicate the underlying cause in more detail.
27 The errno global variable will be used to obtain the error value to be
29 decoded.
30 This function is intended to be used in a fashion similar to the fol‐
32 lowing example:
33 int c = fgetc(fp);
34 if (c == EOF && ferror(fp))
35 {
36 fprintf(stderr, "%s\n", explain_fgetc(fp));
37 exit(EXIT_FAILURE);
38 }
39 fp The original fp, exactly as passed to the fgetc(3) system call.
41 Returns:
43 The message explaining the error. This message buffer is
44 shared by all libexplain functions which do not supply a buffer
45 in their argument list. This will be overwritten by the next
46 call to any libexplain function which shares this buffer,
47 including other threads.
48 Note: This function is not thread safe, because it shares a return buf‐
50 fer across all threads, and many other functions in this library.
51 explain_errno_fgetc
53 const char *explain_errno_fgetc(int errnum, FILE *fp);
54 The explain_errno_fgetc function is used to obtain an explanation of an
56 error returned by the fgetc(3) system call. The least the message will
57 contain is the value of strerror(errnum), but usually it will do much
58 better, and indicate the underlying cause in more detail.
59 This function is intended to be used in a fashion similar to the fol‐
61 lowing example:
62 int c = fgetc(fp);
63 if (c == EOF && ferror(fp))
64 {
65 int err = errno;
66 fprintf(stderr, "%s\n", explain_errno_fgetc(err, fp));
67 exit(EXIT_FAILURE);
68 }
69 errnum The error value to be decoded, usually obtained from the errno
71 global variable just before this function is called. This is
72 necessary if you need to call any code between the system call
73 to be explained and this function, because many libc functions
74 will alter the value of errno.
75 fp The original fp, exactly as passed to the fgetc(3) system call.
77 Returns:
79 The message explaining the error. This message buffer is
80 shared by all libexplain functions which do not supply a buffer
81 in their argument list. This will be overwritten by the next
82 call to any libexplain function which shares this buffer,
83 including other threads.
84 Note: This function is not thread safe, because it shares a return buf‐
86 fer across all threads, and many other functions in this library.
87 explain_message_fgetc
89 void explain_message_fgetc(char *message, int message_size, FILE *fp);
90 The explain_message_fgetc function may be used to obtain an explana‐
92 tion of an error returned by the fgetc(3) system call. The least the
93 message will contain is the value of strerror(errno), but usually it
94 will do much better, and indicate the underlying cause in more detail.
95 The errno global variable will be used to obtain the error value to be
97 decoded.
98 This function is intended to be used in a fashion similar to the fol‐
100 lowing example:
101 int c = fgetc(fp);
102 if (c == EOF && ferror(fp))
103 {
104 char message[3000];
105 explain_message_fgetc(message, sizeof(message), fp);
106 fprintf(stderr, "%s\n", message);
107 exit(EXIT_FAILURE);
108 }
109 message The location in which to store the returned message. If a
111 suitable message return buffer is supplied, this function is
112 thread safe.
113 message_size
115 The size in bytes of the location in which to store the
116 returned message.
117 fp The original fp, exactly as passed to the fgetc(3) system call.
119 explain_message_errno_fgetc
121 void explain_message_errno_fgetc(char *message, int message_size, int
122 errnum, FILE *fp);
123 The explain_message_errno_fgetc function may be used to obtain an
125 explanation of an error returned by the fgetc(3) system call. The
126 least the message will contain is the value of strerror(errnum), but
127 usually it will do much better, and indicate the underlying cause in
128 more detail.
129 This function is intended to be used in a fashion similar to the fol‐
131 lowing example:
132 int c = fgetc(fp);
133 if (c == EOF && ferror(fp))
134 {
135 int err = errno;
136 char message[3000];
137 explain_message_errno_fgetc(message, sizeof(message), err, fp);
138 fprintf(stderr, "%s\n", message);
139 exit(EXIT_FAILURE);
140 }
141 message The location in which to store the returned message. If a
143 suitable message return buffer is supplied, this function is
144 thread safe.
145 message_size
147 The size in bytes of the location in which to store the
148 returned message.
149 errnum The error value to be decoded, usually obtained from the errno
151 global variable just before this function is called. This is
152 necessary if you need to call any code between the system call
153 to be explained and this function, because many libc functions
154 will alter the value of errno.
155 fp The original fp, exactly as passed to the fgetc(3) system call.
157
159 fgetc(3)
160 input of characters
161 explain_fgetc_or_die(3)
163 input of characters and report errors
164
166 libexplain version 1.4
167 Copyright (C) 2008 Peter Miller
168 explain_fgetc(3)