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 se-
       quence 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 re-
       turns 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 re-
       turns on	success, an application	wishing	to check for error  situations
       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),  at-
       tributes(5), standards(5)

SunOS 5.10			  1 Nov	2003			   strtoul(3C)


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

home | help