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

FreeBSD Manual Pages


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

       strtoul,	strtoull - convert string to unsigned long

       #include	<stdlib.h>

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

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

       The  strtoul()  function	 converts  the	initial	 portion of the	string
       pointed to by str to a type unsigned long int representation. First  it
       decomposes  the	input  string  into  three parts: an initial, possibly
       empty,  sequence	 of  white-space  characters  (as  specified  by  iss-
       pace(3C));  a subject sequence interpreted as an	integer	represented in
       some radix determined by	the value of base; and a final string  of  one
       or more unrecognised characters,	including the terminating null byte of
       the input string. Then it attempts to convert the subject  sequence  to
       an unsigned integer, and	returns	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

       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.

       The  strtoull()	function  is  identical	 to  strtoul()	except that it
       returns the value represented by	str as an unsigned long	long.

       Upon successful completion strtoul() returns the	 converted  value,  if
       any.  If	 no conversion could be	performed, 0 is	returned and errno may
       be set to EINVAL. If the	correct	value is outside the range  of	repre-
       sentable	values,	ULONG_MAX is returned and errno	is set to ERANGE.

       The strtoul() function will fail	if:

       EINVAL	       The value of base is not	supported.

       ERANGE	       The value to be returned	is not representable.

       The strtoul() function may fail if:

       EINVAL	       No conversion could be performed.

       Because	0  and	ULONG_MAX  are	returned  on  error and	are also valid
       returns on success, an application wishing to check  for	 error	situa-
       tions  should set errno to 0, then call strtoul(), then check errno and
       if it is	non-zero, assume an error has occurred.

       Unlike strtod(3C) and strtol(3C), strtoul() must	always return  a  non-
       negative	 number;  so,  using the return	value of strtoul() for out-of-
       range numbers with strtoul() could cause	more severe problems than just
       loss of precision if those numbers can ever be negative.

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Standard			   |
       |MT-Level		     |MT-Safe			   |

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

SunOS 5.10			  1 Nov	2003			   strtoul(3C)


Want to link to this manual page? Use this URL:

home | help