*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> strtoul (3)              
Title
Content
Arch
Section
 

STRTOUL(3)

Contents


NAME    [Toc]    [Back]

     strtoul, strtoull, strtouq - convert a string to an unsigned
long or unsigned
 long long integer

SYNOPSIS    [Toc]    [Back]

     #include <stdlib.h>
     #include <limits.h>

     unsigned long
     strtoul(const char *nptr, char **endptr, int base);

     #include <stdlib.h>
     #include <limits.h>

     unsigned long long
     strtoull(const char *nptr, char **endptr, int base);

     #include <sys/types.h>
     #include <stdlib.h>
     #include <limits.h>

     u_quad_t
     strtouq(const char *nptr, char **endptr, int base);

DESCRIPTION    [Toc]    [Back]

     The strtoul() function converts the string in nptr to an unsigned long
     value.  The strtoull() function converts the string in  nptr
to an
     unsigned  long long value.  The strtouq() function is a deprecated equivalent
 of strtoull() and is provided for backwards compatibility with legacy
  programs.  The conversion is done according to the given
base, which
     must be a number between 2 and 36 inclusive or  the  special
value 0.  If
     the  string in nptr represents a negative number, it will be
converted to
     its unsigned equivalent.  This behavior is  consistent  with
what happens
     when  a signed integer type is cast to its unsigned counterpart.

     The string may begin with an arbitrary amount of  whitespace
(as determined
  by  isspace(3))  followed by a single optional `+' or
`-' sign.  If
     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 base is
taken as 10
     (decimal) unless the next character is `0', in which case it
is taken as
     8 (octal).

     The remainder of the string is converted to an unsigned long
value in the
     obvious manner, stopping at the end of the string or at  the
first character
  that  does not produce 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.)

     If  endptr  is non-null, strtoul() stores the address of the
first invalid
     character in *endptr.  If there were no digits at all,  however, strtoul()
     stores  the  original  value  of nptr in *endptr.  (Thus, if
*nptr is not
     ` ' but **endptr is ` ' on return,  the  entire  string  was
valid.)

RETURN VALUES    [Toc]    [Back]

     The strtoul() function returns the result of the conversion,
unless the
     value would overflow, in which case  ULONG_MAX  is  returned
and errno is
     set to ERANGE.  If there was a leading minus sign, strtoul()
returns the
     (unsigned) negation of the absolute value of the number, unless the absolute
  value would overflow.  In this case, strtoul() returns
ULONG_MAX and
     sets the global variable errno to ERANGE.

     The strtoull() function has identical return  values  except
that
     ULLONG_MAX is used to indicate overflow.

     There  is  no  way to determine if strtoul() has processed a
negative number
     (and returned an unsigned  value)  short  of  examining  the
string in nptr
     directly.

EXAMPLES    [Toc]    [Back]

     Ensuring that a string is a valid number (i.e., in range and
containing
     no trailing characters) requires clearing  errno  beforehand
explicitly
     since   errno  is  not  changed  on  a  successful  call  to
strtoul(), and the return
 value of strtoul() cannot be used unambiguously to signal an error:

           char *ep;
           unsigned long ulval;

           ...

           errno = 0;
           ulval = strtoul(buf, &ep, 10);
           if (buf[0] == ' ' || *ep != ' ')
                   goto not_a_number;
           if (errno == ERANGE && ulval == ULONG_MAX)
                   goto out_of_range;

     This example will accept ``12'' but not ``12foo'' or ``120'.
If trailing
 whitespace is acceptable, further checks must be done on
*ep; alternately,
 use sscanf(3).

ERRORS    [Toc]    [Back]

     [ERANGE]       The  given string was out of range; the value
converted has
                   been clamped.

SEE ALSO    [Toc]    [Back]

      
      
     sscanf(3), strtol(3)

STANDARDS    [Toc]    [Back]

     The  strtoul()  and  strtoull()  functions  conform  to  ANSI/ISO/IEC 9899-1999
     (``ANSI  C99'').   The strtouq() function is a BSD extension
and is provided
 for backwards compatibility with legacy programs.

BUGS    [Toc]    [Back]

     Ignores the current locale.

OpenBSD     3.6                           June      25,      1992
[ Back ]
 Similar pages
Name OS Title
wcstol IRIX convert wide character string to long integer, unsigned long integer, long long integer, unsigned long long in
wcstoumax FreeBSD convert a wide character string value to a long, unsigned long, long long, unsigned long long, intma...
wcstoimax FreeBSD convert a wide character string value to a long, unsigned long, long long, unsigned long long, intma...
wcstoull FreeBSD convert a wide character string value to a long, unsigned long, long long, unsigned long long, intma...
wcstol FreeBSD convert a wide character string value to a long, unsigned long, long long, unsigned long long, intma...
wcstoll FreeBSD convert a wide character string value to a long, unsigned long, long long, unsigned long long, intma...
wcstoul FreeBSD convert a wide character string value to a long, unsigned long, long long, unsigned long long, intma...
strtoull FreeBSD convert a string to an unsigned long, unsigned long long, uintmax_t, or u_quad_t integer
strtoul FreeBSD convert a string to an unsigned long, unsigned long long, uintmax_t, or u_quad_t integer
strtouq FreeBSD convert a string to an unsigned long, unsigned long long, uintmax_t, or u_quad_t integer
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service