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

NAME

6       explain_strtoul - explain strtoul(3) errors
7

SYNOPSIS

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

DESCRIPTION

19       These functions may be used to obtain explanations for errors  returned
20       by the strtoul(3) system call.
21
22   explain_strtoul
23       const char *explain_strtoul(const char *nptr, char **endptr, int base);
24
25       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
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 strtoul(3) system
34               call.
35
36       endptr  The original endptr, exactly as passed to the strtoul(3) system
37               call.
38
39       base    The  original  base, exactly as passed to the strtoul(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              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
62       The  above  code  example is available pre‐packaged as the explain_str‐
63       toul_or_die(3) function.
64
65   explain_errno_strtoul
66       const char *explain_errno_strtoul(int errnum, const char *nptr, char
67       **endptr, int base);
68
69       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
74       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
80       nptr    The original nptr, exactly as passed to the  strtoul(3)  system
81               call.
82
83       endptr  The original endptr, exactly as passed to the strtoul(3) system
84               call.
85
86       base    The original base, exactly as passed to the  strtoul(3)  system
87               call.
88
89       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
96       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
99       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
110       The above code example is available pre‐packaged  as  the  explain_str‐
111       toul_or_die(3) function.
112
113   explain_message_strtoul
114       void explain_message_strtoul(char *message, int message_size, const
115       char *nptr, char **endptr, int base);
116
117       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
122       The  errno global variable will be used to obtain the error value to be
123       decoded.
124
125       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
129       message_size
130               The size in bytes  of  the  location  in  which  to  store  the
131               returned message.
132
133       nptr    The  original  nptr, exactly as passed to the strtoul(3) system
134               call.
135
136       endptr  The original endptr, exactly as passed to the strtoul(3) system
137               call.
138
139       base    The  original  base, exactly as passed to the strtoul(3) system
140               call.
141
142       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
154       The above code example is available pre‐packaged  as  the  explain_str‐
155       toul_or_die(3) function.
156
157   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
161       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
167       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
171       message_size
172               The size in bytes  of  the  location  in  which  to  store  the
173               returned message.
174
175       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
181       nptr    The  original  nptr, exactly as passed to the strtoul(3) system
182               call.
183
184       endptr  The original endptr, exactly as passed to the strtoul(3) system
185               call.
186
187       base    The  original  base, exactly as passed to the strtoul(3) system
188               call.
189
190       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
203       The above code example is available pre‐packaged  as  the  explain_str‐
204       toul_or_die(3) function.
205

SEE ALSO

207       strtoul(3)
208               convert a string to an unsigned long integer
209
210       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
217
218
219                                                            explain_strtoul(3)
Impressum