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

NAME

6       explain_getchar - explain getchar(3) errors
7

SYNOPSIS

9       #include <libexplain/getchar.h>
10       const char *explain_getchar(void);
11       const char *explain_errno_getchar(int errnum, void);
12       void explain_message_getchar(char *message, int message_size);
13       void explain_message_errno_getchar(char *message, int message_size, int
14       errnum);
15

DESCRIPTION

17       These functions may be used to obtain explanations for errors  returned
18       by the getchar(3) system call.
19
20   explain_getchar
21       const char *explain_getchar(void);
22
23       The  explain_getchar  function  is  used to obtain an explanation of an
24       error returned by the getchar(3) system call.  The  least  the  message
25       will  contain  is  the value of strerror(errno), but usually it will do
26       much better, 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 = getchar();
34              if (c == EOF && ferror(stdin))
35              {
36                  fprintf(stderr, "%s\n", explain_getchar());
37                  exit(EXIT_FAILURE);
38              }
39
40       Returns:
41               The message explaining  the  error.   This  message  buffer  is
42               shared by all libexplain functions which do not supply a buffer
43               in their argument list.  This will be overwritten by  the  next
44               call  to  any  libexplain  function  which  shares this buffer,
45               including other threads.
46
47       Note: This function is not thread safe, because it shares a return buf‐
48       fer across all threads, and many other functions in this library.
49
50   explain_errno_getchar
51       const char *explain_errno_getchar(int errnum);
52
53       The  explain_errno_getchar function is used to obtain an explanation of
54       an error returned by the getchar(3) system call.  The least the message
55       will  contain  is the value of strerror(errnum), but usually it will do
56       much better, and indicate the underlying cause in more detail.
57
58       This function is intended to be used in a fashion similar to  the  fol‐
59       lowing example:
60              int c = getchar();
61              if (c == EOF && ferror(stdin))
62              {
63                  int err = errno;
64                  fprintf(stderr, "%s\n", explain_errno_getchar(err, ));
65                  exit(EXIT_FAILURE);
66              }
67
68       errnum  The  error value to be decoded, usually obtained from the errno
69               global variable just before this function is called.   This  is
70               necessary  if you need to call any code between the system call
71               to be explained and this function, because many libc  functions
72               will alter the value of errno.
73
74       Returns:
75               The  message  explaining  the  error.   This  message buffer is
76               shared by all libexplain functions which do not supply a buffer
77               in  their  argument list.  This will be overwritten by the next
78               call to any  libexplain  function  which  shares  this  buffer,
79               including other threads.
80
81       Note: This function is not thread safe, because it shares a return buf‐
82       fer across all threads, and many other functions in this library.
83
84   explain_message_getchar
85       void explain_message_getchar(char *message, int message_size);
86
87       The explain_message_getchar function may be used to  obtain an explana‐
88       tion of an error returned by the getchar(3) system call.  The least the
89       message will contain is the value of strerror(errno),  but  usually  it
90       will do much better, and indicate the underlying cause in more detail.
91
92       The  errno global variable will be used to obtain the error value to be
93       decoded.
94
95       This function is intended to be used in a fashion similar to  the  fol‐
96       lowing example:
97              int c = getchar();
98              if (c == EOF && ferror(stdin))
99              {
100                  char message[3000];
101                  explain_message_getchar(message, sizeof(message), );
102                  fprintf(stderr, "%s\n", message);
103                  exit(EXIT_FAILURE);
104              }
105
106       message The  location  in  which  to  store the returned message.  If a
107               suitable message return buffer is supplied,  this  function  is
108               thread safe.
109
110       message_size
111               The  size  in  bytes  of  the  location  in  which to store the
112               returned message.
113
114   explain_message_errno_getchar
115       void explain_message_errno_getchar(char *message, int message_size, int
116       errnum);
117
118       The  explain_message_errno_getchar  function  may  be used to obtain an
119       explanation of an error returned by the getchar(3)  system  call.   The
120       least  the  message  will contain is the value of strerror(errnum), but
121       usually it will do much better, and indicate the  underlying  cause  in
122       more detail.
123
124       This  function  is intended to be used in a fashion similar to the fol‐
125       lowing example:
126              int c = getchar();
127              if (c == EOF && ferror(stdin))
128              {
129                  int err = errno;
130                  char message[3000];
131                  explain_message_errno_getchar(message, sizeof(message), err, );
132                  fprintf(stderr, "%s\n", message);
133                  exit(EXIT_FAILURE);
134              }
135
136       message The location in which to store  the  returned  message.   If  a
137               suitable  message  return  buffer is supplied, this function is
138               thread safe.
139
140       message_size
141               The size in bytes  of  the  location  in  which  to  store  the
142               returned message.
143
144       errnum  The  error value to be decoded, usually obtained from the errno
145               global variable just before this function is called.   This  is
146               necessary  if you need to call any code between the system call
147               to be explained and this function, because many libc  functions
148               will alter the value of errno.
149

SEE ALSO

151       getchar(3)
152               input of characters
153
154       explain_getchar_or_die(3)
155               input of characters and report errors
156
158       libexplain version 0.40
159       Copyright (C) 2008 Peter Miller
160
161
162
163                                                            explain_getchar(3)
Impressum