1explain_puts(3) Library Functions Manual explain_puts(3)
2
6 explain_puts - explain puts(3) errors
7
9 #include <libexplain/puts.h>
10 const char *explain_puts(const char *s);
11 const char *explain_errno_puts(int errnum, const char *s);
12 void explain_message_puts(char *message, int message_size, const char
13 *s);
14 void explain_message_errno_puts(char *message, int message_size, int
15 errnum, const char *s);
16
18 These functions may be used to obtain explanations for errors returned
19 by the puts(3) system call.
20 explain_puts
22 const char *explain_puts(const char *s);
23 The explain_puts function is used to obtain an explanation of an error
25 returned by the puts(3) system call. The least the message will contain
26 is the value of strerror(errno), but usually it will do much better,
27 and indicate the underlying cause in more detail.
28 The errno global variable will be used to obtain the error value to be
30 decoded.
31 s The original s, exactly as passed to the puts(3) system call.
33 Returns:
35 The message explaining the error. This message buffer is shared
36 by all libexplain functions which do not supply a buffer in
37 their argument list. This will be overwritten by the next call
38 to any libexplain function which shares this buffer, including
39 other threads.
40 Note: This function is not thread safe, because it shares a return buf‐
42 fer across all threads, and many other functions in this library.
43 Example: This function is intended to be used in a fashion similar to
45 the following example:
46 if (puts(s) < 0)
47 {
48 fprintf(stderr, "%s\n", explain_puts(s));
49 exit(EXIT_FAILURE);
50 }
51 The above code example is available pre‐packaged as the
53 explain_puts_or_die(3) function.
54 explain_errno_puts
56 const char *explain_errno_puts(int errnum, const char *s);
57 The explain_errno_puts function is used to obtain an explanation of an
59 error returned by the puts(3) system call. The least the message will
60 contain is the value of strerror(errno), but usually it will do much
61 better, and indicate the underlying cause in more detail.
62 errnum The error value to be decoded, usually obtained from the errno
64 global variable just before this function is called. This is
65 necessary if you need to call any code between the system call
66 to be explained and this function, because many libc functions
67 will alter the value of errno.
68 s The original s, exactly as passed to the puts(3) system call.
70 Returns:
72 The message explaining the error. This message buffer is shared
73 by all libexplain functions which do not supply a buffer in
74 their argument list. This will be overwritten by the next call
75 to any libexplain function which shares this buffer, including
76 other threads.
77 Note: This function is not thread safe, because it shares a return buf‐
79 fer across all threads, and many other functions in this library.
80 Example: This function is intended to be used in a fashion similar to
82 the following example:
83 if (puts(s) < 0)
84 {
85 int err = errno;
86 fprintf(stderr, "%s\n", explain_errno_puts(err, s));
87 exit(EXIT_FAILURE);
88 }
89 The above code example is available pre‐packaged as the
91 explain_puts_or_die(3) function.
92 explain_message_puts
94 void explain_message_puts(char *message, int message_size, const char
95 *s);
96 The explain_message_puts function is used to obtain an explanation of
98 an error returned by the puts(3) system call. The least the message
99 will contain is the value of strerror(errno), but usually it will do
100 much better, and indicate the underlying cause in more detail.
101 The errno global variable will be used to obtain the error value to be
103 decoded.
104 message The location in which to store the returned message. If a suit‐
106 able message return buffer is supplied, this function is thread
107 safe.
108 message_size
110 The size in bytes of the location in which to store the
111 returned message.
112 s The original s, exactly as passed to the puts(3) system call.
114 Example: This function is intended to be used in a fashion similar to
116 the following example:
117 if (puts(s) < 0)
118 {
119 char message[3000];
120 explain_message_puts(message, sizeof(message), s);
121 fprintf(stderr, "%s\n", message);
122 exit(EXIT_FAILURE);
123 }
124 The above code example is available pre‐packaged as the
126 explain_puts_or_die(3) function.
127 explain_message_errno_puts
129 void explain_message_errno_puts(char *message, int message_size, int
130 errnum, const char *s);
131 The explain_message_errno_puts function is used to obtain an explana‐
133 tion of an error returned by the puts(3) system call. The least the
134 message will contain is the value of strerror(errno), but usually it
135 will do much better, and indicate the underlying cause in more detail.
136 message The location in which to store the returned message. If a suit‐
138 able message return buffer is supplied, this function is thread
139 safe.
140 message_size
142 The size in bytes of the location in which to store the
143 returned message.
144 errnum The error value to be decoded, usually obtained from the errno
146 global variable just before this function is called. This is
147 necessary if you need to call any code between the system call
148 to be explained and this function, because many libc functions
149 will alter the value of errno.
150 s The original s, exactly as passed to the puts(3) system call.
152 Example: This function is intended to be used in a fashion similar to
154 the following example:
155 if (puts(s) < 0)
156 {
157 int err = errno;
158 char message[3000];
159 explain_message_errno_puts(message, sizeof(message), err,
160 s);
161 fprintf(stderr, "%s\n", message);
162 exit(EXIT_FAILURE);
163 }
164 The above code example is available pre‐packaged as the
166 explain_puts_or_die(3) function.
167
169 puts(3) write a string and a trailing newline to stdout
170 explain_puts_or_die(3)
172 write a string and a trailing newline to stdout and report
173 errors
174
176 libexplain version 1.4
177 Copyright (C) 2009 Peter Miller
178 explain_puts(3)