1explain_strtoul(3) Library Functions Manual explain_strtoul(3)
2
6 explain_strtoul - explain strtoul(3) errors
7
9 #include <libexplain/strtoul.h>
10 const char *explain_strtoul(const char *nptr, char **endptr, int base);
11 const char *explain_errno_strtoul(int errnum, const char *nptr, char
12 **endptr, int base);
13 void explain_message_strtoul(char *message, int message_size, const
14 char *nptr, char **endptr, int base);
15 void explain_message_errno_strtoul(char *message, int message_size, int
16 errnum, const char *nptr, char **endptr, int base);
17
19 These functions may be used to obtain explanations for errors returned
20 by the strtoul(3) system call.
21 explain_strtoul
23 const char *explain_strtoul(const char *nptr, char **endptr, int base);
24 The explain_strtoul function is used to obtain an explanation of an
26 error returned by the strtoul(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 nptr The original nptr, exactly as passed to the strtoul(3) system
34 call.
35 endptr The original endptr, exactly as passed to the strtoul(3) system
37 call.
38 base The original base, exactly as passed to the strtoul(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 unsigned long result = strtoul(nptr, endptr, base);
55 if (result < 0)
56 {
57 fprintf(stderr, "%s\n", explain_strtoul(nptr, endptr,
58 base));
59 exit(EXIT_FAILURE);
60 }
61 The above code example is available pre‐packaged as the explain_str‐
63 toul_or_die(3) function.
64 explain_errno_strtoul
66 const char *explain_errno_strtoul(int errnum, const char *nptr, char
67 **endptr, int base);
68 The explain_errno_strtoul function is used to obtain an explanation of
70 an error returned by the strtoul(3) system call. The least the message
71 will contain is the value of strerror(errno), but usually it will do
72 much better, and indicate the underlying cause in more detail.
73 errnum The error value to be decoded, usually obtained from the errno
75 global variable just before this function is called. This is
76 necessary if you need to call any code between the system call
77 to be explained and this function, because many libc functions
78 will alter the value of errno.
79 nptr The original nptr, exactly as passed to the strtoul(3) system
81 call.
82 endptr The original endptr, exactly as passed to the strtoul(3) system
84 call.
85 base The original base, exactly as passed to the strtoul(3) system
87 call.
88 Returns:
90 The message explaining the error. This message buffer is shared
91 by all libexplain functions which do not supply a buffer in
92 their argument list. This will be overwritten by the next call
93 to any libexplain function which shares this buffer, including
94 other threads.
95 Note: This function is not thread safe, because it shares a return buf‐
97 fer across all threads, and many other functions in this library.
98 Example: This function is intended to be used in a fashion similar to
100 the following example:
101 unsigned long result = strtoul(nptr, endptr, base);
102 if (result < 0)
103 {
104 int err = errno;
105 fprintf(stderr, "%s\n", explain_errno_strtoul(err, nptr,
106 endptr, base));
107 exit(EXIT_FAILURE);
108 }
109 The above code example is available pre‐packaged as the explain_str‐
111 toul_or_die(3) function.
112 explain_message_strtoul
114 void explain_message_strtoul(char *message, int message_size, const
115 char *nptr, char **endptr, int base);
116 The explain_message_strtoul function is used to obtain an explanation
118 of an error returned by the strtoul(3) system call. The least the mes‐
119 sage will contain is the value of strerror(errno), but usually it will
120 do much better, and indicate the underlying cause in more detail.
121 The errno global variable will be used to obtain the error value to be
123 decoded.
124 message The location in which to store the returned message. If a suit‐
126 able message return buffer is supplied, this function is thread
127 safe.
128 message_size
130 The size in bytes of the location in which to store the
131 returned message.
132 nptr The original nptr, exactly as passed to the strtoul(3) system
134 call.
135 endptr The original endptr, exactly as passed to the strtoul(3) system
137 call.
138 base The original base, exactly as passed to the strtoul(3) system
140 call.
141 Example: This function is intended to be used in a fashion similar to
143 the following example:
144 unsigned long result = strtoul(nptr, endptr, base);
145 if (result < 0)
146 {
147 char message[3000];
148 explain_message_strtoul(message, sizeof(message), nptr,
149 endptr, base);
150 fprintf(stderr, "%s\n", message);
151 exit(EXIT_FAILURE);
152 }
153 The above code example is available pre‐packaged as the explain_str‐
155 toul_or_die(3) function.
156 explain_message_errno_strtoul
158 void explain_message_errno_strtoul(char *message, int message_size, int
159 errnum, const char *nptr, char **endptr, int base);
160 The explain_message_errno_strtoul function is used to obtain an expla‐
162 nation of an error returned by the strtoul(3) system call. The least
163 the message will contain is the value of strerror(errno), but usually
164 it will do much better, and indicate the underlying cause in more
165 detail.
166 message The location in which to store the returned message. If a suit‐
168 able message return buffer is supplied, this function is thread
169 safe.
170 message_size
172 The size in bytes of the location in which to store the
173 returned message.
174 errnum The error value to be decoded, usually obtained from the errno
176 global variable just before this function is called. This is
177 necessary if you need to call any code between the system call
178 to be explained and this function, because many libc functions
179 will alter the value of errno.
180 nptr The original nptr, exactly as passed to the strtoul(3) system
182 call.
183 endptr The original endptr, exactly as passed to the strtoul(3) system
185 call.
186 base The original base, exactly as passed to the strtoul(3) system
188 call.
189 Example: This function is intended to be used in a fashion similar to
191 the following example:
192 unsigned long result = strtoul(nptr, endptr, base);
193 if (result < 0)
194 {
195 int err = errno;
196 char message[3000];
197 explain_message_errno_strtoul(message, sizeof(message), err,
198 nptr, endptr, base);
199 fprintf(stderr, "%s\n", message);
200 exit(EXIT_FAILURE);
201 }
202 The above code example is available pre‐packaged as the explain_str‐
204 toul_or_die(3) function.
205
207 strtoul(3)
208 convert a string to an unsigned long integer
209 explain_strtoul_or_die(3)
211 convert a string to an unsigned long integer and report errors
212
214 libexplain version 1.4
215 Copyright (C) 2009 Peter Miller
216 explain_strtoul(3)