1explain_strtol(3)          Library Functions Manual          explain_strtol(3)
2
3
4

NAME

6       explain_strtol - explain strtol(3) errors
7

SYNOPSIS

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

DESCRIPTION

19       These functions may be used to obtain explanations for errors  returned
20       by the strtol(3) system call.
21
22   explain_strtol
23       const char *explain_strtol(const char *nptr, char **endptr, int base);
24
25       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
30       The errno global variable will be used to obtain the error value to  be
31       decoded.
32
33       nptr    The  original  nptr,  exactly as passed to the strtol(3) system
34               call.
35
36       endptr  The original endptr, exactly as passed to the strtol(3)  system
37               call.
38
39       base    The  original  base,  exactly as passed to the strtol(3) system
40               call.
41
42       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
49       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
52       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
61       The above code example is available pre‐packaged  as  the  explain_str‐
62       tol_or_die(3) function.
63
64   explain_errno_strtol
65       const char *explain_errno_strtol(int errnum, const char *nptr, char
66       **endptr, int base);
67
68       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
73       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
79       nptr    The  original  nptr,  exactly as passed to the strtol(3) system
80               call.
81
82       endptr  The original endptr, exactly as passed to the strtol(3)  system
83               call.
84
85       base    The  original  base,  exactly as passed to the strtol(3) system
86               call.
87
88       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
95       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
98       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
109       The  above  code  example is available pre‐packaged as the explain_str‐
110       tol_or_die(3) function.
111
112   explain_message_strtol
113       void explain_message_strtol(char *message, int message_size, const char
114       *nptr, char **endptr, int base);
115
116       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
121       The errno global variable will be used to obtain the error value to  be
122       decoded.
123
124       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
128       message_size
129               The  size  in  bytes  of  the  location  in  which to store the
130               returned message.
131
132       nptr    The original nptr, exactly as passed to  the  strtol(3)  system
133               call.
134
135       endptr  The  original endptr, exactly as passed to the strtol(3) system
136               call.
137
138       base    The original base, exactly as passed to  the  strtol(3)  system
139               call.
140
141       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
153       The  above  code  example is available pre‐packaged as the explain_str‐
154       tol_or_die(3) function.
155
156   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
160       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
165       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
169       message_size
170               The size in bytes  of  the  location  in  which  to  store  the
171               returned message.
172
173       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
179       nptr    The  original  nptr,  exactly as passed to the strtol(3) system
180               call.
181
182       endptr  The original endptr, exactly as passed to the strtol(3)  system
183               call.
184
185       base    The  original  base,  exactly as passed to the strtol(3) system
186               call.
187
188       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
201       The above code example is available pre‐packaged  as  the  explain_str‐
202       tol_or_die(3) function.
203

SEE ALSO

205       strtol(3)
206               convert a string to a long integer
207
208       explain_strtol_or_die(3)
209               convert a string to a long integer and report errors
210
212       libexplain version 0.40
213       Copyright (C) 2009 Peter Miller
214
215
216
217                                                             explain_strtol(3)
Impressum