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

NAME

6       explain_putchar - explain putchar(3) errors
7

SYNOPSIS

9       #include <libexplain/putchar.h>
10       const char *explain_putchar(int c);
11       const char *explain_errno_putchar(int errnum, int c);
12       void explain_message_putchar(char *message, int message_size, int c);
13       void explain_message_errno_putchar(char *message, int message_size, int
14       errnum, int c);
15

DESCRIPTION

17       These functions may be used to obtain explanations for errors  returned
18       by the putchar(3) system call.
19
20   explain_putchar
21       const char *explain_putchar(int c);
22
23       The  explain_putchar  function  is  used to obtain an explanation of an
24       error returned by the putchar(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              if (putchar(c) == EOF)
34              {
35                  fprintf(stderr, "%s\n", explain_putchar(c));
36                  exit(EXIT_FAILURE);
37              }
38
39       c       The original c, exactly as  passed  to  the  putchar(3)  system
40               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_putchar
53       const char *explain_errno_putchar(int errnum, int c);
54
55       The explain_errno_putchar function is used to obtain an explanation  of
56       an error returned by the putchar(3) system call.  The least the message
57       will contain is the value of strerror(errnum), but usually it  will  do
58       much 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              if (putchar(c) == EOF)
63              {
64                  int err = errno;
65                  fprintf(stderr, "%s\n", explain_errno_putchar(err, c));
66                  exit(EXIT_FAILURE);
67              }
68
69       errnum  The error value to be decoded, usually obtained from the  errno
70               global  variable  just before this function is called.  This is
71               necessary if you need to call any code between the system  call
72               to  be explained and this function, because many libc functions
73               will alter the value of errno.
74
75       c       The original c, exactly as  passed  to  the  putchar(3)  system
76               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_putchar
89       void explain_message_putchar(char *message, int message_size, int c);
90
91       The explain_message_putchar function may be used to  obtain an explana‐
92       tion of an error returned by the putchar(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              if (putchar(c) == EOF)
102              {
103                  char message[3000];
104                  explain_message_putchar(message, sizeof(message), c);
105                  fprintf(stderr, "%s\n", message);
106                  exit(EXIT_FAILURE);
107              }
108
109       message The  location  in  which  to  store the returned message.  If a
110               suitable message return buffer is supplied,  this  function  is
111               thread safe.
112
113       message_size
114               The  size  in  bytes  of  the  location  in  which to store the
115               returned message.
116
117       c       The original c, exactly as  passed  to  the  putchar(3)  system
118               call.
119
120   explain_message_errno_putchar
121       void explain_message_errno_putchar(char *message, int message_size, int
122       errnum, int c);
123
124       The explain_message_errno_putchar function may be  used  to  obtain  an
125       explanation  of  an  error returned by the putchar(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              if (putchar(c) == EOF)
133              {
134                  int err = errno;
135                  char message[3000];
136                  explain_message_errno_putchar(message, sizeof(message), err, c);
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       c       The original c, exactly as  passed  to  the  putchar(3)  system
156               call.
157

SEE ALSO

159       putchar(3)
160               output of characters
161
162       explain_putchar_or_die(3)
163               output of characters and report errors
164
166       libexplain version 1.4
167       Copyright (C) 2008 Peter Miller
168
169
170
171                                                            explain_putchar(3)
Impressum