diff options
Diffstat (limited to 'man3/strtoul.3')
| -rw-r--r-- | man3/strtoul.3 | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/man3/strtoul.3 b/man3/strtoul.3 new file mode 100644 index 0000000..a9a8d60 --- /dev/null +++ b/man3/strtoul.3 @@ -0,0 +1,219 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" Modified Sun Jul 25 10:54:03 1993 by Rik Faith (faith@cs.unc.edu) +.\" Fixed typo, aeb, 950823 +.\" 2002-02-22, joey, mihtjel: Added strtoull() +.\" +.TH strtoul 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +strtoul, strtoull, strtouq \- convert a string to an unsigned long integer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.PP +.BI "unsigned long strtoul(const char *restrict " nptr , +.BI " char **restrict " endptr ", int " base ); +.BI "unsigned long long strtoull(const char *restrict " nptr , +.BI " char **restrict " endptr ", int " base ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR strtoull (): +.nf + _ISOC99_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR strtoul () +function converts the initial part of the string +in +.I nptr +to an +.I "unsigned long" +value according to the +given +.IR base , +which must be between 2 and 36 inclusive, or be +the special value 0. +.PP +The string may begin with an arbitrary amount of white space (as +determined by +.BR isspace (3)) +followed by a single optional \[aq]+\[aq] or \[aq]\-\[aq] +sign. +If +.I base +is zero or 16, the string may then include a +"0x" prefix, and the number will be read in base 16; otherwise, a +zero +.I base +is taken as 10 (decimal) unless the next character +is \[aq]0\[aq], in which case it is taken as 8 (octal). +.PP +The remainder of the string is converted to an +.I "unsigned long" +value in the obvious manner, +stopping at the first character which is not a +valid digit in the given base. +(In bases above 10, the letter \[aq]A\[aq] in +either uppercase or lowercase represents 10, \[aq]B\[aq] represents 11, and so +forth, with \[aq]Z\[aq] representing 35.) +.PP +If +.I endptr +is not NULL, +.BR strtoul () +stores the address of the +first invalid character in +.IR *endptr . +If there were no digits at +all, +.BR strtoul () +stores the original value of +.I nptr +in +.I *endptr +(and returns 0). +In particular, if +.I *nptr +is not \[aq]\e0\[aq] but +.I **endptr +is \[aq]\e0\[aq] on return, the entire string is valid. +.PP +The +.BR strtoull () +function works just like the +.BR strtoul () +function but returns an +.I "unsigned long long" +value. +.SH RETURN VALUE +The +.BR strtoul () +function returns either the result of the conversion +or, if there was a leading minus sign, the negation of the result of the +conversion represented as an unsigned value, +unless the original (nonnegated) value would overflow; in +the latter case, +.BR strtoul () +returns +.B ULONG_MAX +and sets +.I errno +to +.BR ERANGE . +Precisely the same holds for +.BR strtoull () +(with +.B ULLONG_MAX +instead of +.BR ULONG_MAX ). +.SH ERRORS +.TP +.B EINVAL +(not in C99) +The given +.I base +contains an unsupported value. +.TP +.B ERANGE +The resulting value was out of range. +.PP +The implementation may also set +.I errno +to +.B EINVAL +in case +no conversion was performed (no digits seen, and 0 returned). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strtoul (), +.BR strtoull (), +.BR strtouq () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR strtoul () +POSIX.1-2001, C89, SVr4. +.TP +.BR strtoull () +POSIX.1-2001, C99. +.SH NOTES +Since +.BR strtoul () +can legitimately return 0 or +.B ULONG_MAX +.RB ( ULLONG_MAX +for +.BR strtoull ()) +on both success and failure, the calling program should set +.I errno +to 0 before the call, +and then determine if an error occurred by checking whether +.I errno +has a nonzero value after the call. +.PP +In locales other than the "C" locale, other strings may be accepted. +(For example, the thousands separator of the current locale may be +supported.) +.PP +BSD also has +.PP +.in +4n +.EX +.BI "u_quad_t strtouq(const char *" nptr ", char **" endptr ", int " base ); +.EE +.in +.PP +with completely analogous definition. +Depending on the wordsize of the current architecture, this +may be equivalent to +.BR strtoull () +or to +.BR strtoul (). +.PP +Negative values are considered valid input and are +silently converted to the equivalent +.I "unsigned long" +value. +.SH EXAMPLES +See the example on the +.BR strtol (3) +manual page; +the use of the functions described in this manual page is similar. +.SH SEE ALSO +.BR a64l (3), +.BR atof (3), +.BR atoi (3), +.BR atol (3), +.BR strtod (3), +.BR strtol (3), +.BR strtoumax (3) |