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

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

STRTOL(3)

Contents


NAME    [Toc]    [Back]

     strtol, strtoll, strtoq - convert string value to a long  or
long long integer

SYNOPSIS    [Toc]    [Back]

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

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

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

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

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

     quad_t
     strtoq(const char *nptr, char **endptr, int base);

DESCRIPTION    [Toc]    [Back]

     The  strtol() function converts the string in nptr to a long
value.  The
     strtoll() function converts the string in  nptr  to  a  long
long value.  The
     strtoq()  function  is  a deprecated equivalent of strtoll()
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.

     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 a 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 `A' in either
upper or lower
     case represents 10, `B' represents 11, and  so  forth,  with
`Z' representing
 35.)

     If  endptr  is  non-null, strtol() stores the address of the
first invalid
     character in *endptr.  If there were no digits at all,  however, strtol()
     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  strtol() function returns the result of the conversion,
unless the
     value would underflow or overflow.  If an underflow  occurs,
strtol() returns
  LONG_MIN.   If  an  overflow occurs, strtol() returns
LONG_MAX.  In
     both cases, errno is set to ERANGE.

     The strtoll() function has identical  return  values  except
that LLONG_MIN
     and  LLONG_MAX  are  used to indicate underflow and overflow
respectively.

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 strtol(),
and the return
  value of strtol() cannot be used unambiguously to signal an error:

           char *ep;
           long lval;

           ...

           errno = 0;
           lval = strtol(buf, &ep, 10);
           if (buf[0] == ' ' || *ep != ' ')
                   goto not_a_number;
           if (errno == ERANGE && (lval == LONG_MAX  ||  lval  ==
LONG_MIN))
                   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).

     If strtol() is being used instead of atoi(3), error checking
is further
     complicated because the  desired  return  value  is  an  int
rather than a
     long; however, on some architectures integers and long integers are the
     same size.  Thus the following is necessary:

           char *ep;
           int ival;
           long lval;

           ...

           errno = 0;
           lval = strtol(buf, &ep, 10);
           if (buf[0] == ' ' || *ep != ' ')
                goto not_a_number;
           if ((errno == ERANGE && (lval == LONG_MAX ||  lval  ==
LONG_MIN)) ||
               (lval > INT_MAX || lval < INT_MIN))
                goto out_of_range;
           ival = lval;

ERRORS    [Toc]    [Back]

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

SEE ALSO    [Toc]    [Back]

      
      
     atof(3), atoi(3), atol(3), atoll(3),  sscanf(3),  strtod(3),
strtoul(3)

STANDARDS    [Toc]    [Back]

     The strtol() and strtoll() functions conform to ANSI/ISO/IEC
9899-1999
     (``ANSI C99'').  The strtoq() 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
strtoimax FreeBSD convert a string value to a long, long long, intmax_t or quad_t integer
strtol NetBSD convert string value to a long, long long, intmax_t or quad_t integer
strtoq FreeBSD convert a string value to a long, long long, intmax_t or quad_t integer
strtol FreeBSD convert a string value to a long, long long, intmax_t or quad_t integer
strtoll NetBSD convert string value to a long, long long, intmax_t or quad_t integer
strtoimax NetBSD convert string value to a long, long long, intmax_t or quad_t integer
strtoq NetBSD convert string value to a long, long long, intmax_t or quad_t integer
strtoll FreeBSD convert a string value to a long, long long, intmax_t or quad_t integer
wcstol FreeBSD convert a wide character string value to a long, unsigned long, long long, unsigned long long, intma...
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service