diff options
Diffstat (limited to 'man3/strtoul.3')
-rw-r--r-- | man3/strtoul.3 | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/man3/strtoul.3 b/man3/strtoul.3 new file mode 100644 index 000000000..a2cd1e33f --- /dev/null +++ b/man3/strtoul.3 @@ -0,0 +1,129 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" 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 2002-05-30 "GNU" "Linux Programmer's Manual" +.SH NAME +strtoul, strtoull, strtouq \- convert a string to an unsigned long integer +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.sp +.BI "unsigned long int" +.BI "strtoul(const char *" nptr ", char **" endptr ", int " base ); +.sp +.BI "unsigned long long int" +.BI "strtoull(const char *" nptr ", char **" endptr ", int " base ); +.fi +.SH DESCRIPTION +The \fBstrtoul()\fP function converts the initial part of the string +in \fInptr\fP to an unsigned long integer value according to the +given \fIbase\fP, which must be between 2 and 36 inclusive, or be +the special value 0. +.PP +The string must begin with an arbitrary amount of white space (as +determined by +.BR isspace (3)) +followed by a single optional `+' or `-' +sign. If \fIbase\fP is zero or 16, the string may then include a +`0x' prefix, and the number will be read in base 16; otherwise, a +zero \fIbase\fP is taken as 10 (decimal) unless the next character +is `0', in which case it is taken as 8 (octal). +.PP +The remainder of the string is converted to an unsigned long int 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 `A' in +either upper or lower case represents 10, `B' represents 11, and so +forth, with `Z' representing 35.) +.PP +If \fIendptr\fP is not NULL, \fBstrtoul()\fP stores the address of the +first invalid character in \fI*endptr\fP. If there were no digits at +all, \fBstrtoul()\fP stores the original value of \fInptr\fP in +\fI*endptr\fP (and returns 0). +In particular, if \fI*nptr\fP is not `\\0' but \fI**endptr\fP +is `\\0' on return, the entire string is valid. +.PP +The +.B strtoull() +function works just like the +.B strtoul() +function but returns an unsigned long long integer value. +.SH "RETURN VALUE" +The \fBstrtoul()\fP function returns either the result of the conversion +or, if there was a leading minus sign, the negation of the result of the +conversion, unless the original (non-negated) value would overflow; in +the latter case, \fBstrtoul()\fP returns ULONG_MAX and sets the global +variable \fIerrno\fP to ERANGE. +Precisely the same holds for +.B strtoull() +(with ULLONG_MAX instead of 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. +.LP +The implementation may also set \fIerrno\fP to \fBEINVAL\fP in case +no conversion was performed (no digits seen, and 0 returned). +.SH NOTES +In locales other than the "C" locale, also other strings may be accepted. +(For example, the thousands separator of the current locale may be +supported.) +.LP +BSD also has +.sp +.in +4n +.nf +.BI "u_quad_t" +.BI "strtouq(const char *" nptr ", char **" endptr ", int base" ); +.sp +.in -4n +.fi +with completely analogous definition. +Depending on the wordsize of the current architecture, this +may be equivalent to +.B strtoull() +or to +.BR strtoul() . +.SH "CONFORMING TO" +.B strtoul() +conforms to SVID 3, BSD 4.3, ISO 9899 (C99) and POSIX, and +.BR strtoull() +to ISO 9899 (C99) and POSIX 1003.1-2001. +.SH "SEE ALSO" +.BR atof (3), +.BR atoi (3), +.BR atol (3), +.BR strtod (3), +.BR strtol (3) |