1explain_setbuffer(3) Library Functions Manual explain_setbuffer(3)
2
6 explain_setbuffer - explain setbuffer(3) errors
7
9 #include <libexplain/setbuffer.h>
10 const char *explain_setbuffer(FILE *fp, char *data, size_t size);
11 const char *explain_errno_setbuffer(int errnum, FILE *fp, char *data,
12 size_t size);
13 void explain_message_setbuffer(char *message, int message_size, FILE
14 *fp, char *data, size_t size);
15 void explain_message_errno_setbuffer(char *message, int message_size,
16 int errnum, FILE *fp, char *data, size_t size);
17
19 These functions may be used to obtain explanations for errors returned
20 by the setbuffer(3) system call.
21 explain_setbuffer
23 const char *explain_setbuffer(FILE *fp, char *data, size_t size);
24 The explain_setbuffer function is used to obtain an explanation of an
26 error returned by the setbuffer(3) system call. The least the message
27 will contain is the value of strerror(errno), but usually it will do
28 much better, and indicate the underlying cause in more detail.
29 The errno global variable will be used to obtain the error value to be
31 decoded.
32 fp The original fp, exactly as passed to the setbuffer(3) system
34 call.
35 data The original data, exactly as passed to the setbuffer(3) system
37 call.
38 size The original size, exactly as passed to the setbuffer(3) system
40 call.
41 Returns:
43 The message explaining the error. This message buffer is shared
44 by all libexplain functions which do not supply a buffer in
45 their argument list. This will be overwritten by the next call
46 to any libexplain function which shares this buffer, including
47 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 Example: This function is intended to be used in a fashion similar to
53 the following example:
54 void result = setbuffer(fp, data, size);
55 if (result < 0)
56 {
57 fprintf(stderr, "%s\n", explain_setbuffer(fp, data, size));
58 exit(EXIT_FAILURE);
59 }
60 The above code example is available pre‐packaged as the explain_set‐
62 buffer_or_die(3) function.
63 explain_errno_setbuffer
65 const char *explain_errno_setbuffer(int errnum, FILE *fp, char *data,
66 size_t size);
67 The explain_errno_setbuffer function is used to obtain an explanation
69 of an error returned by the setbuffer(3) system call. The least the
70 message will contain is the value of strerror(errno), but usually it
71 will do much better, and indicate the underlying cause in more detail.
72 errnum The error value to be decoded, usually obtained from the errno
74 global variable just before this function is called. This is
75 necessary if you need to call any code between the system call
76 to be explained and this function, because many libc functions
77 will alter the value of errno.
78 fp The original fp, exactly as passed to the setbuffer(3) system
80 call.
81 data The original data, exactly as passed to the setbuffer(3) system
83 call.
84 size The original size, exactly as passed to the setbuffer(3) system
86 call.
87 Returns:
89 The message explaining the error. This message buffer is shared
90 by all libexplain functions which do not supply a buffer in
91 their argument list. This will be overwritten by the next call
92 to any libexplain function which shares this buffer, including
93 other threads.
94 Note: This function is not thread safe, because it shares a return buf‐
96 fer across all threads, and many other functions in this library.
97 Example: This function is intended to be used in a fashion similar to
99 the following example:
100 void result = setbuffer(fp, data, size);
101 if (result < 0)
102 {
103 int err = errno;
104 fprintf(stderr, "%s\n", explain_errno_setbuffer(err, fp,
105 data, size));
106 exit(EXIT_FAILURE);
107 }
108 The above code example is available pre‐packaged as the explain_set‐
110 buffer_or_die(3) function.
111 explain_message_setbuffer
113 void explain_message_setbuffer(char *message, int message_size, FILE
114 *fp, char *data, size_t size);
115 The explain_message_setbuffer function is used to obtain an explanation
117 of an error returned by the setbuffer(3) system call. The least the
118 message will contain is the value of strerror(errno), but usually it
119 will do much better, and indicate the underlying cause in more detail.
120 The errno global variable will be used to obtain the error value to be
122 decoded.
123 message The location in which to store the returned message. If a suit‐
125 able message return buffer is supplied, this function is thread
126 safe.
127 message_size
129 The size in bytes of the location in which to store the
130 returned message.
131 fp The original fp, exactly as passed to the setbuffer(3) system
133 call.
134 data The original data, exactly as passed to the setbuffer(3) system
136 call.
137 size The original size, exactly as passed to the setbuffer(3) system
139 call.
140 Example: This function is intended to be used in a fashion similar to
142 the following example:
143 void result = setbuffer(fp, data, size);
144 if (result < 0)
145 {
146 char message[3000];
147 explain_message_setbuffer(message, sizeof(message), fp,
148 data, size);
149 fprintf(stderr, "%s\n", message);
150 exit(EXIT_FAILURE);
151 }
152 The above code example is available pre‐packaged as the explain_set‐
154 buffer_or_die(3) function.
155 explain_message_errno_setbuffer
157 void explain_message_errno_setbuffer(char *message, int message_size,
158 int errnum, FILE *fp, char *data, size_t size);
159 The explain_message_errno_setbuffer function is used to obtain an
161 explanation of an error returned by the setbuffer(3) system call. The
162 least the message will contain is the value of strerror(errno), but
163 usually it will do much better, and indicate the underlying cause in
164 more detail.
165 message The location in which to store the returned message. If a suit‐
167 able message return buffer is supplied, this function is thread
168 safe.
169 message_size
171 The size in bytes of the location in which to store the
172 returned message.
173 errnum The error value to be decoded, usually obtained from the errno
175 global variable just before this function is called. This is
176 necessary if you need to call any code between the system call
177 to be explained and this function, because many libc functions
178 will alter the value of errno.
179 fp The original fp, exactly as passed to the setbuffer(3) system
181 call.
182 data The original data, exactly as passed to the setbuffer(3) system
184 call.
185 size The original size, exactly as passed to the setbuffer(3) system
187 call.
188 Example: This function is intended to be used in a fashion similar to
190 the following example:
191 void result = setbuffer(fp, data, size);
192 if (result < 0)
193 {
194 int err = errno;
195 char message[3000];
196 explain_message_errno_setbuffer(message, sizeof(message),
197 err, fp, data, size);
198 fprintf(stderr, "%s\n", message);
199 exit(EXIT_FAILURE);
200 }
201 The above code example is available pre‐packaged as the explain_set‐
203 buffer_or_die(3) function.
204
206 setbuffer(3)
207 stream buffering operations
208 explain_setbuffer_or_die(3)
210 stream buffering operations and report errors
211
213 libexplain version 1.4
214 Copyright (C) 2010 Peter Miller
215 explain_setbuffer(3)