1explain_ungetc(3) Library Functions Manual explain_ungetc(3)
2
6 explain_ungetc - explain ungetc(3) errors
7
9 #include <libexplain/ungetc.h>
10 const char *explain_ungetc(int c, FILE *fp);
11 const char *explain_errno_ungetc(int errnum, int c, FILE *fp);
12 void explain_message_ungetc(char *message, int message_size, int c,
13 FILE *fp);
14 void explain_message_errno_ungetc(char *message, int message_size, int
15 errnum, int c, FILE *fp);
16
18 These functions may be used to obtain explanations for errors returned
19 by the ungetc(3) system call.
20 explain_ungetc
22 const char *explain_ungetc(int c, FILE *fp);
23 The explain_ungetc function is used to obtain an explanation of an
25 error returned by the ungetc(3) system call. The least the message will
26 contain is the value of strerror(errno), but usually it will do much
27 better, 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 c The original c, exactly as passed to the ungetc(3) system call.
33 fp The original fp, exactly as passed to the ungetc(3) system
35 call.
36 Returns:
38 The message explaining the error. This message buffer is shared
39 by all libexplain functions which do not supply a buffer in
40 their argument list. This will be overwritten by the next call
41 to any libexplain function which shares this buffer, including
42 other threads.
43 Note: This function is not thread safe, because it shares a return buf‐
45 fer across all threads, and many other functions in this library.
46 Example: This function is intended to be used in a fashion similar to
48 the following example:
49 if (ungetc(c, fp) < 0)
50 {
51 fprintf(stderr, "%s\n", explain_ungetc(c, fp));
52 exit(EXIT_FAILURE);
53 }
54 The above code example is available pre‐packaged as the
56 explain_ungetc_or_die(3) function.
57 explain_errno_ungetc
59 const char *explain_errno_ungetc(int errnum, int c, FILE *fp);
60 The explain_errno_ungetc function is used to obtain an explanation of
62 an error returned by the ungetc(3) system call. The least the message
63 will contain is the value of strerror(errno), but usually it will do
64 much better, and indicate the underlying cause in more detail.
65 errnum The error value to be decoded, usually obtained from the errno
67 global variable just before this function is called. This is
68 necessary if you need to call any code between the system call
69 to be explained and this function, because many libc functions
70 will alter the value of errno.
71 c The original c, exactly as passed to the ungetc(3) system call.
73 fp The original fp, exactly as passed to the ungetc(3) system
75 call.
76 Returns:
78 The message explaining the error. This message buffer is shared
79 by all libexplain functions which do not supply a buffer in
80 their argument list. This will be overwritten by the next call
81 to any libexplain function which shares this buffer, including
82 other threads.
83 Note: This function is not thread safe, because it shares a return buf‐
85 fer across all threads, and many other functions in this library.
86 Example: This function is intended to be used in a fashion similar to
88 the following example:
89 if (ungetc(c, fp) < 0)
90 {
91 int err = errno;
92 fprintf(stderr, "%s\n", explain_errno_ungetc(err, c, fp));
93 exit(EXIT_FAILURE);
94 }
95 The above code example is available pre‐packaged as the
97 explain_ungetc_or_die(3) function.
98 explain_message_ungetc
100 void explain_message_ungetc(char *message, int message_size, int c,
101 FILE *fp);
102 The explain_message_ungetc function is used to obtain an explanation of
104 an error returned by the ungetc(3) system call. The least the message
105 will contain is the value of strerror(errno), but usually it will do
106 much better, and indicate the underlying cause in more detail.
107 The errno global variable will be used to obtain the error value to be
109 decoded.
110 message The location in which to store the returned message. If a suit‐
112 able message return buffer is supplied, this function is thread
113 safe.
114 message_size
116 The size in bytes of the location in which to store the
117 returned message.
118 c The original c, exactly as passed to the ungetc(3) system call.
120 fp The original fp, exactly as passed to the ungetc(3) system
122 call.
123 Example: This function is intended to be used in a fashion similar to
125 the following example:
126 if (ungetc(c, fp) < 0)
127 {
128 char message[3000];
129 explain_message_ungetc(message, sizeof(message), c, fp);
130 fprintf(stderr, "%s\n", message);
131 exit(EXIT_FAILURE);
132 }
133 The above code example is available pre‐packaged as the
135 explain_ungetc_or_die(3) function.
136 explain_message_errno_ungetc
138 void explain_message_errno_ungetc(char *message, int message_size, int
139 errnum, int c, FILE *fp);
140 The explain_message_errno_ungetc function is used to obtain an explana‐
142 tion of an error returned by the ungetc(3) system call. The least the
143 message will contain is the value of strerror(errno), but usually it
144 will do much better, and indicate the underlying cause in more detail.
145 message The location in which to store the returned message. If a suit‐
147 able message return buffer is supplied, this function is thread
148 safe.
149 message_size
151 The size in bytes of the location in which to store the
152 returned message.
153 errnum The error value to be decoded, usually obtained from the errno
155 global variable just before this function is called. This is
156 necessary if you need to call any code between the system call
157 to be explained and this function, because many libc functions
158 will alter the value of errno.
159 c The original c, exactly as passed to the ungetc(3) system call.
161 fp The original fp, exactly as passed to the ungetc(3) system
163 call.
164 Example: This function is intended to be used in a fashion similar to
166 the following example:
167 if (ungetc(c, fp) < 0)
168 {
169 int err = errno;
170 char message[3000];
171 explain_message_errno_ungetc(message, sizeof(message), err,
172 c, fp);
173 fprintf(stderr, "%s\n", message);
174 exit(EXIT_FAILURE);
175 }
176 The above code example is available pre‐packaged as the
178 explain_ungetc_or_die(3) function.
179
181 ungetc(3)
182 push a character back to a stream
183 explain_ungetc_or_die(3)
185 push a character back to a stream and report errors
186
188 libexplain version 1.4
189 Copyright (C) 2010 Peter Miller
190 explain_ungetc(3)