Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
strtol(3C)		 Standard C Library Functions		    strtol(3C)

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

SYNOPSIS
       #include	<stdlib.h>

       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	speci-
       fied by isspace(3C)); a subject sequence	interpreted as an integer rep-
       resented	 in  some  radix  determined by	the value of base; and a final
       string of one or	more unrecognized characters, including	the  terminat-
       ing  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 - 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 sub-
       ject sequence is	a sequence of letters and digits representing an inte-
       ger  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 characters 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  charac-
       ters  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	inter-
       preted 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	resulting from
       the  conversion	is negated. A pointer to the final string is stored in
       the object pointed to by	endptr,	provided 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()
       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)  str-
       tol(str,	(char **)NULL, 10).

       If the value cannot be represented, the behavior	is undefined.

   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	termi-
       nating null is produced.	The low-order digit of the result always occu-
       pies 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 EIN-
       VAL.

       If the correct value is outside the range of representable values, str-
       tol()  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:

       ERANGE	       The value to be returned	is not representable. The str-
		       tol() 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	corresponding 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 attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |See below.		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

       The  strtol(),  strtoll(),  atol(),  atoll(),  and atoi() functions are
       Standard.

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

SunOS 5.10			  6 May	2003			    strtol(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=strtol&sektion=3c&manpath=SunOS+5.10>

home | help