lib/libc/stdlib/strtoul.3

   1 .\" Copyright (c) 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Chris Torek and the American National Standards Committee X3,
   6 .\" on Information Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)strtoul.3   8.1 (Berkeley) 6/4/93
  37 .\" $FreeBSD: src/lib/libc/stdlib/strtoul.3,v 1.3.2.7 2002/01/21 12:30:34 ru Exp $
  38 .\"
  39 .Dd June 4, 1993
  40 .Dt STRTOUL 3
  41 .Os
  42 .Sh NAME
  43 .Nm strtoul , strtoull , strtouq
  44 .Nd "convert a string to an"
  45 .Vt "unsigned long" , "unsigned long long" ,
  46 or
  47 .Vt u_quad_t
  48 integer
  49 .Sh LIBRARY
  50 .Lb libc
  51 .Sh SYNOPSIS
  52 .In stdlib.h
  53 .In limits.h
  54 .Ft "unsigned long"
  55 .Fn strtoul "const char *nptr" "char **endptr" "int base"
  56 .Ft "unsigned long long"
  57 .Fn strtoull "const char *nptr" "char **endptr" "int base"
  58 .In sys/types.h
  59 .In stdlib.h
  60 .In limits.h
  61 .Ft u_quad_t
  62 .Fn strtouq "const char *nptr" "char **endptr" "int base"
  63 .Sh DESCRIPTION
  64 The
  65 .Fn strtoul
  66 function
  67 converts the string in
  68 .Fa nptr
  69 to an
  70 .Vt "unsigned long"
  71 value.
  72 The
  73 .Fn strtoull
  74 function
  75 converts the string in
  76 .Fa nptr
  77 to an
  78 .Vt "unsigned long long"
  79 value.
  80 The
  81 .Fn strtouq
  82 function
  83 converts the string in
  84 .Fa nptr
  85 to a
  86 .Vt u_quad_t
  87 value.
  88 The conversion is done according to the given
  89 .Fa base ,
  90 which must be between 2 and 36 inclusive,
  91 or be the special value 0.
  92 .Pp
  93 The string may begin with an arbitrary amount of white space
  94 (as determined by
  95 .Xr isspace 3 )
  96 followed by a single optional
  97 .Ql +
  98 or
  99 .Ql -
 100 sign.
 101 If
 102 .Fa base
 103 is zero or 16,
 104 the string may then include a
 105 .Dq Li 0x
 106 prefix,
 107 and the number will be read in base 16; otherwise, a zero
 108 .Fa base
 109 is taken as 10 (decimal) unless the next character is
 110 .Ql 0 ,
 111 in which case it is taken as 8 (octal).
 112 .Pp
 113 The remainder of the string is converted to an
 114 .Vt "unsigned long"
 115 value in the obvious manner,
 116 stopping at the end of the string
 117 or at the first character that does not produce a valid digit
 118 in the given base.
 119 (In bases above 10, the letter
 120 .Ql A
 121 in either upper or lower case
 122 represents 10,
 123 .Ql B
 124 represents 11, and so forth, with
 125 .Ql Z
 126 representing 35.)
 127 .Pp
 128 If
 129 .Fa endptr
 130 is not
 131 .Dv NULL ,
 132 .Fn strtoul
 133 stores the address of the first invalid character in
 134 .Fa *endptr .
 135 If there were no digits at all, however,
 136 .Fn strtoul
 137 stores the original value of
 138 .Fa nptr
 139 in
 140 .Fa *endptr .
 141 (Thus, if
 142 .Fa *nptr
 143 is not
 144 .Ql \e0
 145 but
 146 .Fa **endptr
 147 is
 148 .Ql \e0
 149 on return, the entire string was valid.)
 150 .Sh RETURN VALUES
 151 The
 152 .Fn strtoul
 153 function
 154 returns either the result of the conversion
 155 or, if there was a leading minus sign,
 156 the negation of the result of the conversion,
 157 unless the original (non-negated) value would overflow;
 158 in the latter case,
 159 .Fn strtoul
 160 returns
 161 .Dv ULONG_MAX .
 162 The
 163 .Fn strtoull
 164 function
 165 returns either the result of the conversion
 166 or, if there was a leading minus sign,
 167 the negation of the result of the conversion,
 168 unless the original (non-negated) value would overflow;
 169 in the latter case,
 170 .Fn strtoull
 171 returns
 172 .Dv ULLONG_MAX .
 173 In all cases,
 174 .Va errno
 175 is set to
 176 .Er ERANGE .
 177 .Sh ERRORS
 178 .Bl -tag -width Er
 179 .It Bq Er ERANGE
 180 The given string was out of range; the value converted has been clamped.
 181 .El
 182 .Sh SEE ALSO
 183 .Xr strtol 3
 184 .Sh STANDARDS
 185 The
 186 .Fn strtoul
 187 function
 188 conforms to
 189 .St -isoC .
 190 The
 191 .Fn strtoull
 192 function
 193 conforms to
 194 .St -isoC-99 .
 195 The
 196 .Bx
 197 .Fn strtouq
 198 function is deprecated.
 199 .Sh BUGS
 200 Ignores the current locale.