1explain_putchar(3) Library Functions Manual explain_putchar(3)
2
6 explain_putchar - explain putchar(3) errors
7
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
17 These functions may be used to obtain explanations for errors returned
18 by the putchar(3) system call.
19 explain_putchar
21 const char *explain_putchar(int c);
22 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 The errno global variable will be used to obtain the error value to be
29 decoded.
30 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 c The original c, exactly as passed to the putchar(3) system
40 call.
41 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 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 explain_errno_putchar
53 const char *explain_errno_putchar(int errnum, int c);
54 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 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 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 c The original c, exactly as passed to the putchar(3) system
76 call.
77 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 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 explain_message_putchar
89 void explain_message_putchar(char *message, int message_size, int c);
90 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 The errno global variable will be used to obtain the error value to be
97 decoded.
98 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 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 message_size
114 The size in bytes of the location in which to store the
115 returned message.
116 c The original c, exactly as passed to the putchar(3) system
118 call.
119 explain_message_errno_putchar
121 void explain_message_errno_putchar(char *message, int message_size, int
122 errnum, int c);
123 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 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 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 message_size
146 The size in bytes of the location in which to store the
147 returned message.
148 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 c The original c, exactly as passed to the putchar(3) system
156 call.
157
159 putchar(3)
160 output of characters
161 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 explain_putchar(3)