Manual Pages for UNIX Operating System command usage for man strtol

Standard C Library Functions                           strtol(3C)



NAME
     strtol, strtoll, atol,  atoll,  atoi,  lltostr,  ulltostr  -
     string conversion routines

SYNOPSIS
     #include 

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


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


     long atol(const char *str);


     long long atoll(const char *str);


     int atoi(const char *str);


     char *lltostr(long long value, char *endptr);


     char *ulltostr(unsigned long long value, char *endptr);


DESCRIPTION
  strtol() and strtoll()
     The strtol() function converts the initial  portion  of  the
     string pointed to by str to a type long int representation.


     The strtoll() function converts the initial portion  of  the
     string pointed to by str to a type long long representation.


     Both functions first decompose the input string  into  three
     parts:  an  initial, possibly empty, sequence of white-space
     characters (as specified by isspace(3C)); a subject sequence
     interpreted  as  an integer represented in some radix deter-
     mined by the value of base; and a final  string  of  one  or
     more unrecognized characters, including the terminating null
     byte of the input string. They then attempt to  convert  the
     subject sequence to an integer and return the result.


     If the value of base is 0, the expected form of the  subject
     sequence  is  that  of a decimal constant, octal constant or
     hexadecimal constant, any of which may be preceded by a + or



SunOS 5.11           Last change: 6 May 2003                    1






Standard C Library Functions                           strtol(3C)



     - sign. A decimal constant begins with a non-zero digit, and
     consists of a sequence of decimal digits. An octal  constant
     consists  of  the prefix 0 optionally followed by a sequence
     of the digits 0 to 7 only. A hexadecimal  constant  consists
     of the prefix 0x or 0X followed by a sequence of the decimal
     digits and letters a (or A) to f (or F) with values 10 to 15
     respectively.


     If the value of base is between 2 and 36, the expected  form
     of  the subject sequence is a sequence of letters and digits
     representing an integer with the radix  specified  by  base,
     optionally preceded by a + or - sign. The letters from a (or
     A) to z (or Z) inclusive are ascribed the values 10  to  35;
     only  letters  whose  ascribed  values are less than that of
     base are permitted. If the value of base is 16, the  charac-
     ters 0x or 0X may optionally precede the sequence of letters
     and digits, following the sign if present.


     The subject sequence  is  defined  as  the  longest  initial
     subsequence  of  the  input  string, starting with the first
     non-white-space character, that is of the expected form. The
     subject  sequence contains no characters if the input string
     is empty or consists entirely of white-space characters,  or
     if  the first non-white-space character is other than a sign
     or a permissible letter or digit.


     If the subject sequence has the expected form and the  value
     of  base  is 0, the sequence of characters starting with the
     first digit is interpreted as an integer  constant.  If  the
     subject sequence has the expected form and the value of base
     is between 2 and 36, it is used as the base for  conversion,
     ascribing  to  each  letter its value as given above. If the
     subject sequence begins with a minus sign, the value result-
     ing  from  the conversion is negated. A pointer to the final
     string is stored in the object pointed to  by  endptr,  pro-
     vided that endptr is not a null pointer.


     In other than the POSIX locale,  additional  implementation-
     dependent subject sequence forms may be accepted.


     If the subject sequence  is  empty  or  does  not  have  the
     expected  form, no conversion is performed; the value of str
     is stored in the object pointed to by endptr, provided  that
     endptr is not a null pointer.

  atol(), atoll() and atoi()




SunOS 5.11           Last change: 6 May 2003                    2






Standard C Library Functions                           strtol(3C)



     Except for behavior  on  error,  atol()  is  equivalent  to:
     strtol(str, (char **)NULL, 10).


     Except for behavior on  error,  atoll()  is  equivalent  to:
     strtoll(str, (char **)NULL, 10).


     Except for behavior on error, atoi() is equivalent to: (int)
     strtol(str, (char **)NULL, 10).


     If the value cannot be represented, the  behavior  is  unde-
     fined.

  lltostr() and ulltostr()
     The lltostr() function  returns  a  pointer  to  the  string
     represented  by  the long long value. The endptr argument is
     assumed to point to the byte following a storage  area  into
     which the decimal representation of value is to be placed as
     a string.  The lltostr() function converts value to  decimal
     and  produces  the  string,   and  returns  a pointer to the
     beginning of the string. No leading zeros are produced,  and
     no  terminating null is produced. The low-order digit of the
     result  always  occupies  memory  position   endptr-1.   The
     behavior of lltostr() is undefined if  value is negative.  A
     single zero digit is produced if  value is 0.


     The ulltostr() function is similar to lltostr() except  that
     value is an unsigned long long.

RETURN VALUES
     Upon successful  completion,  strtol(),  strtoll(),  atol(),
     atoll(),  and  atoi() return the converted value, if any. If
     no conversion could be  performed,  strtol()  and  strtoll()
     return 0 and errno may be set to EINVAL.


     If the correct value is outside the range  of  representable
     values,  strtol() returns LONG_MAX or LONG_MIN and strtoll()
     returns LLONG_MAX or LLONG_MIN (according to the sign of the
     value), and errno is set to ERANGE.


     Upon successful completion, lltostr() and ulltostr()  return
     a pointer to the converted string.

ERRORS
     The strtol() and strtoll() functions will fail if:





SunOS 5.11           Last change: 6 May 2003                    3






Standard C Library Functions                           strtol(3C)



     ERANGE    The value to be returned is not representable.



     The strtol() and strtoll() functions may fail if:

     EINVAL    The value of base is not supported.


USAGE
     Because 0, LONG_MIN, LONG_MAX, LLONG_MIN, and LLONG_MAX  are
     returned  on error and are also valid returns on success, an
     application wishing to check for error situations should set
     errno to 0, call the function, then check errno and if it is
     non-zero, assume an error has occurred.


     The strtol() function no longer accepts values greater  than
     LONG_MAX  or  LLONG_MAX  as  valid  input.  Use  strtoul(3C)
     instead.


     Calls to atoi() and atol() might be faster than  correspond-
     ing  calls to strtol(), and calls to atoll() might be faster
     than corresponding calls to strtoll(). However, applications
     should  not  use  the  atoi(),  atol(), or atoll() functions
     unless they know the value represented by the argument  will
     be in range for the corresponding result type.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|
    | Standard                    | See below.                  |
    |_____________________________|_____________________________|



     For strtol(), strtoll(), atol(), atoll(),  and  atoi(),  see
     standards(5).

SEE ALSO




SunOS 5.11           Last change: 6 May 2003                    4






Standard C Library Functions                           strtol(3C)



     isalpha(3C),     isspace(3C),     scanf(3C),     strtod(3C),
     strtoul(3C), attributes(5), standards(5)





















































SunOS 5.11           Last change: 6 May 2003                    5