1explain_ungetc(3)          Library Functions Manual          explain_ungetc(3)
2
3
4

NAME

6       explain_ungetc - explain ungetc(3) errors
7

SYNOPSIS

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

DESCRIPTION

18       These  functions may be used to obtain explanations for errors returned
19       by the ungetc(3) system call.
20
21   explain_ungetc
22       const char *explain_ungetc(int c, FILE *fp);
23
24       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
29       The  errno global variable will be used to obtain the error value to be
30       decoded.
31
32       c       The original c, exactly as passed to the ungetc(3) system call.
33
34       fp      The original fp, exactly as  passed  to  the  ungetc(3)  system
35               call.
36
37       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
44       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
47       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
55       The   above   code   example   is   available   pre‐packaged   as   the
56       explain_ungetc_or_die(3) function.
57
58   explain_errno_ungetc
59       const char *explain_errno_ungetc(int errnum, int c, FILE *fp);
60
61       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
66       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
72       c       The original c, exactly as passed to the ungetc(3) system call.
73
74       fp      The  original  fp,  exactly  as  passed to the ungetc(3) system
75               call.
76
77       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
84       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
87       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
96       The   above   code   example   is   available   pre‐packaged   as   the
97       explain_ungetc_or_die(3) function.
98
99   explain_message_ungetc
100       void explain_message_ungetc(char *message, int message_size, int c,
101       FILE *fp);
102
103       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
108       The  errno global variable will be used to obtain the error value to be
109       decoded.
110
111       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
115       message_size
116               The size in bytes  of  the  location  in  which  to  store  the
117               returned message.
118
119       c       The original c, exactly as passed to the ungetc(3) system call.
120
121       fp      The  original  fp,  exactly  as  passed to the ungetc(3) system
122               call.
123
124       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
134       The   above   code   example   is   available   pre‐packaged   as   the
135       explain_ungetc_or_die(3) function.
136
137   explain_message_errno_ungetc
138       void explain_message_errno_ungetc(char *message, int message_size, int
139       errnum, int c, FILE *fp);
140
141       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
146       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
150       message_size
151               The size in bytes  of  the  location  in  which  to  store  the
152               returned message.
153
154       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
160       c       The original c, exactly as passed to the ungetc(3) system call.
161
162       fp      The  original  fp,  exactly  as  passed to the ungetc(3) system
163               call.
164
165       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
177       The   above   code   example   is   available   pre‐packaged   as   the
178       explain_ungetc_or_die(3) function.
179

SEE ALSO

181       ungetc(3)
182               push a character back to a stream
183
184       explain_ungetc_or_die(3)
185               push a character back to a stream and report errors
186
188       libexplain version 0.40
189       Copyright (C) 2010 Peter Miller
190
191
192
193                                                             explain_ungetc(3)
Impressum