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

NAME

6       explain_getc - explain getc(3) errors
7

SYNOPSIS

9       #include <libexplain/getc.h>
10       const char *explain_getc(FILE *fp);
11       const char *explain_errno_getc(int errnum, FILE *fp);
12       void explain_message_getc(char *message, int message_size, FILE *fp);
13       void  explain_message_errno_getc(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 getc(3) system call.
19
20   explain_getc
21       const char *explain_getc(FILE *fp);
22
23       The  explain_getc function is used to obtain an explanation of an error
24       returned by the getc(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 = getc(fp);
34              if (c == EOF && ferror(fp))
35              {
36                  fprintf(stderr, "%s\n", explain_getc(fp));
37                  exit(EXIT_FAILURE);
38              }
39
40       fp      The original fp, exactly as passed to the getc(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_getc
53       const char *explain_errno_getc(int errnum, FILE *fp);
54
55       The  explain_errno_getc function is used to obtain an explanation of an
56       error returned by the getc(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 = getc(fp);
63              if (c == EOF && ferror(fp))
64              {
65                  int err = errno;
66                  fprintf(stderr, "%s\n", explain_errno_getc(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 getc(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_getc
89       void explain_message_getc(char *message, int message_size, FILE *fp);
90
91       The explain_message_getc function may be used to  obtain an explanation
92       of an error returned by the getc(3) system call.  The least the message
93       will contain is the value of strerror(errno), but usually  it  will  do
94       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 = getc(fp);
102              if (c == EOF && ferror(fp))
103              {
104                  char message[3000];
105                  explain_message_getc(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 getc(3) system call.
119
120   explain_message_errno_getc
121       void explain_message_errno_getc(char *message,  int  message_size,  int
122       errnum, FILE *fp);
123
124       The explain_message_errno_getc function may be used to obtain an expla‐
125       nation of an error returned by the getc(3) system call.  The least  the
126       message  will  contain is the value of strerror(errnum), but usually it
127       will do much better, and indicate the underlying cause in more detail.
128
129       This function is intended to be used in a fashion similar to  the  fol‐
130       lowing example:
131              int c = getc(fp);
132              if (c == EOF && ferror(fp))
133              {
134                  int err = errno;
135                  char message[3000];
136                  explain_message_errno_getc(message, sizeof(message), err, fp);
137                  fprintf(stderr, "%s\n", message);
138                  exit(EXIT_FAILURE);
139              }
140
141       message The  location  in  which  to  store the returned message.  If a
142               suitable message return buffer is supplied,  this  function  is
143               thread safe.
144
145       message_size
146               The  size  in  bytes  of  the  location  in  which to store the
147               returned message.
148
149       errnum  The error value to be decoded, usually obtained from the  errno
150               global  variable  just before this function is called.  This is
151               necessary if you need to call any code between the system  call
152               to  be explained and this function, because many libc functions
153               will alter the value of errno.
154
155       fp      The original fp, exactly as passed to the getc(3) system call.
156

SEE ALSO

158       getc(3) input of characters
159
160       explain_getc_or_die(3)
161               input of characters and report errors
162
164       libexplain version 0.40
165       Copyright (C) 2008 Peter Miller
166
167
168
169                                                               explain_getc(3)
Impressum