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

NAME

6       explain_fgetc - explain fgetc(3) errors
7

SYNOPSIS

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

DESCRIPTION

17       These functions may be used to obtain explanations for errors  returned
18       by the fgetc(3) system call.
19
20   explain_fgetc
21       const char *explain_fgetc(FILE *fp);
22
23       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
28       The errno global variable will be used to obtain the error value to  be
29       decoded.
30
31       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
40       fp      The original fp, exactly as passed to the fgetc(3) system call.
41
42       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
49       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
52   explain_errno_fgetc
53       const char *explain_errno_fgetc(int errnum, FILE *fp);
54
55       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
60       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
70       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
76       fp      The original fp, exactly as passed to the fgetc(3) system call.
77
78       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
85       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
88   explain_message_fgetc
89       void explain_message_fgetc(char *message, int message_size, FILE *fp);
90
91       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
96       The  errno global variable will be used to obtain the error value to be
97       decoded.
98
99       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
110       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
114       message_size
115               The  size  in  bytes  of  the  location  in  which to store the
116               returned message.
117
118       fp      The original fp, exactly as passed to the fgetc(3) system call.
119
120   explain_message_errno_fgetc
121       void explain_message_errno_fgetc(char *message, int  message_size,  int
122       errnum, FILE *fp);
123
124       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
130       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
142       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
146       message_size
147               The size in bytes  of  the  location  in  which  to  store  the
148               returned message.
149
150       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
156       fp      The original fp, exactly as passed to the fgetc(3) system call.
157

SEE ALSO

159       fgetc(3)
160               input of characters
161
162       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
169
170
171                                                              explain_fgetc(3)
Impressum