1explain_putw(3) Library Functions Manual explain_putw(3)
2
6 explain_putw - explain putw(3) errors
7
9 #include <libexplain/putw.h>
10 const char *explain_putw(int value, FILE *fp);
11 const char *explain_errno_putw(int errnum, int value, FILE *fp);
12 void explain_message_putw(char *message, int message_size, int value,
13 FILE *fp);
14 void explain_message_errno_putw(char *message, int message_size, int
15 errnum, int value, FILE *fp);
16
18 These functions may be used to obtain explanations for errors returned
19 by the putw(3) system call.
20 explain_putw
22 const char *explain_putw(int value, FILE *fp);
23 The explain_putw function is used to obtain an explanation of an error
25 returned by the putw(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 value The original value, exactly as passed to the putw(3) system
33 call.
34 fp The original fp, exactly as passed to the putw(3) system call.
36 Returns:
38 The message explaining the error. This message buffer is shared
39 by all libexplain functions which do not supply a buffer in
40 their argument list. This will be overwritten by the next call
41 to any libexplain function which shares this buffer, including
42 other threads.
43 Note: This function is not thread safe, because it shares a return buf‐
45 fer across all threads, and many other functions in this library.
46 Example: This function is intended to be used in a fashion similar to
48 the following example:
49 if (putw(value, fp) < 0)
50 {
51 fprintf(stderr, "%s\n", explain_putw(value, fp));
52 exit(EXIT_FAILURE);
53 }
54 The above code example is available pre‐packaged as the
56 explain_putw_or_die(3) function.
57 explain_errno_putw
59 const char *explain_errno_putw(int errnum, int value, FILE *fp);
60 The explain_errno_putw function is used to obtain an explanation of an
62 error returned by the putw(3) system call. The least the message will
63 contain is the value of strerror(errno), but usually it will do much
64 better, and indicate the underlying cause in more detail.
65 errnum The error value to be decoded, usually obtained from the errno
67 global variable just before this function is called. This is
68 necessary if you need to call any code between the system call
69 to be explained and this function, because many libc functions
70 will alter the value of errno.
71 value The original value, exactly as passed to the putw(3) system
73 call.
74 fp The original fp, exactly as passed to the putw(3) system call.
76 Returns:
78 The message explaining the error. This message buffer is shared
79 by all libexplain functions which do not supply a buffer in
80 their argument list. This will be overwritten by the next call
81 to any libexplain function which shares this buffer, including
82 other threads.
83 Note: This function is not thread safe, because it shares a return buf‐
85 fer across all threads, and many other functions in this library.
86 Example: This function is intended to be used in a fashion similar to
88 the following example:
89 if (putw(value, fp) < 0)
90 {
91 int err = errno;
92 fprintf(stderr, "%s\n", explain_errno_putw(err, value, fp));
93 exit(EXIT_FAILURE);
94 }
95 The above code example is available pre‐packaged as the
97 explain_putw_or_die(3) function.
98 explain_message_putw
100 void explain_message_putw(char *message, int message_size, int value,
101 FILE *fp);
102 The explain_message_putw function is used to obtain an explanation of
104 an error returned by the putw(3) system call. The least the message
105 will contain is the value of strerror(errno), but usually it will do
106 much better, and indicate the underlying cause in more detail.
107 The errno global variable will be used to obtain the error value to be
109 decoded.
110 message The location in which to store the returned message. If a suit‐
112 able message return buffer is supplied, this function is thread
113 safe.
114 message_size
116 The size in bytes of the location in which to store the
117 returned message.
118 value The original value, exactly as passed to the putw(3) system
120 call.
121 fp The original fp, exactly as passed to the putw(3) system call.
123 Example: This function is intended to be used in a fashion similar to
125 the following example:
126 if (putw(value, fp) < 0)
127 {
128 char message[3000];
129 explain_message_putw(message, sizeof(message), value, fp);
130 fprintf(stderr, "%s\n", message);
131 exit(EXIT_FAILURE);
132 }
133 The above code example is available pre‐packaged as the
135 explain_putw_or_die(3) function.
136 explain_message_errno_putw
138 void explain_message_errno_putw(char *message, int message_size, int
139 errnum, int value, FILE *fp);
140 The explain_message_errno_putw function is used to obtain an explana‐
142 tion of an error returned by the putw(3) system call. The least the
143 message will contain is the value of strerror(errno), but usually it
144 will do much better, and indicate the underlying cause in more detail.
145 message The location in which to store the returned message. If a suit‐
147 able message return buffer is supplied, this function is thread
148 safe.
149 message_size
151 The size in bytes of the location in which to store the
152 returned message.
153 errnum The error value to be decoded, usually obtained from the errno
155 global variable just before this function is called. This is
156 necessary if you need to call any code between the system call
157 to be explained and this function, because many libc functions
158 will alter the value of errno.
159 value The original value, exactly as passed to the putw(3) system
161 call.
162 fp The original fp, exactly as passed to the putw(3) system call.
164 Example: This function is intended to be used in a fashion similar to
166 the following example:
167 if (putw(value, fp) < 0)
168 {
169 int err = errno;
170 char message[3000];
171 explain_message_errno_putw(message, sizeof(message), err,
172 value, fp);
173 fprintf(stderr, "%s\n", message);
174 exit(EXIT_FAILURE);
175 }
176 The above code example is available pre‐packaged as the
178 explain_putw_or_die(3) function.
179
181 putw(3) output a word (int)
182 explain_putw_or_die(3)
184 output a word (int) and report errors
185
187 libexplain version 0.40
188 Copyright (C) 2010 Peter Miller
189 explain_putw(3)