1explain_strtol(3) Library Functions Manual explain_strtol(3)
2
6 explain_strtol - explain strtol(3) errors
7
9 #include <libexplain/strtol.h>
10 const char *explain_strtol(const char *nptr, char **endptr, int base);
11 const char *explain_errno_strtol(int errnum, const char *nptr, char
12 **endptr, int base);
13 void explain_message_strtol(char *message, int message_size, const char
14 *nptr, char **endptr, int base);
15 void explain_message_errno_strtol(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 strtol(3) system call.
21 explain_strtol
23 const char *explain_strtol(const char *nptr, char **endptr, int base);
24 The explain_strtol function is used to obtain an explanation of an
26 error returned by the strtol(3) system call. The least the message will
27 contain is the value of strerror(errno), but usually it will do much
28 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 strtol(3) system
34 call.
35 endptr The original endptr, exactly as passed to the strtol(3) system
37 call.
38 base The original base, exactly as passed to the strtol(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 long result = strtol(nptr, endptr, base);
55 if (result < 0)
56 {
57 fprintf(stderr, "%s\n", explain_strtol(nptr, endptr, base));
58 exit(EXIT_FAILURE);
59 }
60 The above code example is available pre‐packaged as the explain_str‐
62 tol_or_die(3) function.
63 explain_errno_strtol
65 const char *explain_errno_strtol(int errnum, const char *nptr, char
66 **endptr, int base);
67 The explain_errno_strtol function is used to obtain an explanation of
69 an error returned by the strtol(3) system call. The least the message
70 will contain is the value of strerror(errno), but usually it will do
71 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 nptr The original nptr, exactly as passed to the strtol(3) system
80 call.
81 endptr The original endptr, exactly as passed to the strtol(3) system
83 call.
84 base The original base, exactly as passed to the strtol(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 long result = strtol(nptr, endptr, base);
101 if (result < 0)
102 {
103 int err = errno;
104 fprintf(stderr, "%s\n", explain_errno_strtol(err, nptr,
105 endptr, base));
106 exit(EXIT_FAILURE);
107 }
108 The above code example is available pre‐packaged as the explain_str‐
110 tol_or_die(3) function.
111 explain_message_strtol
113 void explain_message_strtol(char *message, int message_size, const char
114 *nptr, char **endptr, int base);
115 The explain_message_strtol function is used to obtain an explanation of
117 an error returned by the strtol(3) system call. The least the message
118 will contain is the value of strerror(errno), but usually it will do
119 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 nptr The original nptr, exactly as passed to the strtol(3) system
133 call.
134 endptr The original endptr, exactly as passed to the strtol(3) system
136 call.
137 base The original base, exactly as passed to the strtol(3) system
139 call.
140 Example: This function is intended to be used in a fashion similar to
142 the following example:
143 long result = strtol(nptr, endptr, base);
144 if (result < 0)
145 {
146 char message[3000];
147 explain_message_strtol(message, sizeof(message), nptr,
148 endptr, base);
149 fprintf(stderr, "%s\n", message);
150 exit(EXIT_FAILURE);
151 }
152 The above code example is available pre‐packaged as the explain_str‐
154 tol_or_die(3) function.
155 explain_message_errno_strtol
157 void explain_message_errno_strtol(char *message, int message_size, int
158 errnum, const char *nptr, char **endptr, int base);
159 The explain_message_errno_strtol function is used to obtain an explana‐
161 tion of an error returned by the strtol(3) system call. The least the
162 message will contain is the value of strerror(errno), but usually it
163 will do much better, and indicate the underlying cause in more detail.
164 message The location in which to store the returned message. If a suit‐
166 able message return buffer is supplied, this function is thread
167 safe.
168 message_size
170 The size in bytes of the location in which to store the
171 returned message.
172 errnum The error value to be decoded, usually obtained from the errno
174 global variable just before this function is called. This is
175 necessary if you need to call any code between the system call
176 to be explained and this function, because many libc functions
177 will alter the value of errno.
178 nptr The original nptr, exactly as passed to the strtol(3) system
180 call.
181 endptr The original endptr, exactly as passed to the strtol(3) system
183 call.
184 base The original base, exactly as passed to the strtol(3) system
186 call.
187 Example: This function is intended to be used in a fashion similar to
189 the following example:
190 long result = strtol(nptr, endptr, base);
191 if (result < 0)
192 {
193 int err = errno;
194 char message[3000];
195 explain_message_errno_strtol(message, sizeof(message), err,
196 nptr, endptr, base);
197 fprintf(stderr, "%s\n", message);
198 exit(EXIT_FAILURE);
199 }
200 The above code example is available pre‐packaged as the explain_str‐
202 tol_or_die(3) function.
203
205 strtol(3)
206 convert a string to a long integer
207 explain_strtol_or_die(3)
209 convert a string to a long integer and report errors
210
212 libexplain version 1.4
213 Copyright (C) 2009 Peter Miller
214 explain_strtol(3)