lib/libc/stdlib/strtonum.3

   1 .\" Copyright (c) 2004 Ted Unangst
   2 .\"
   3 .\" Permission to use, copy, modify, and distribute this software for any
   4 .\" purpose with or without fee is hereby granted, provided that the above
   5 .\" copyright notice and this permission notice appear in all copies.
   6 .\"
   7 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   8 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
   9 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  10 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  11 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  12 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  13 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  14 .\"
  15 .\" $OpenBSD: strtonum.3,v 1.12 2005/10/26 11:37:58 jmc Exp $
  16 .\" $FreeBSD$
  17 .\"
  18 .Dd April 29, 2004
  19 .Dt STRTONUM 3
  20 .Os
  21 .Sh NAME
  22 .Nm strtonum
  23 .Nd "reliably convert string value to an integer"
  24 .Sh SYNOPSIS
  25 .In stdlib.h
  26 .In limits.h
  27 .Ft long long
  28 .Fo strtonum
  29 .Fa "const char *nptr"
  30 .Fa "long long minval"
  31 .Fa "long long maxval"
  32 .Fa "const char **errstr"
  33 .Fc
  34 .Sh DESCRIPTION
  35 The
  36 .Fn strtonum
  37 function converts the string in
  38 .Fa nptr
  39 to a
  40 .Vt "long long"
  41 value.
  42 The
  43 .Fn strtonum
  44 function was designed to facilitate safe, robust programming
  45 and overcome the shortcomings of the
  46 .Xr atoi 3
  47 and
  48 .Xr strtol 3
  49 family of interfaces.
  50 .Pp
  51 The string may begin with an arbitrary amount of whitespace
  52 (as determined by
  53 .Xr isspace 3 )
  54 followed by a single optional
  55 .Ql +
  56 or
  57 .Ql -
  58 sign.
  59 .Pp
  60 The remainder of the string is converted to a
  61 .Vt "long long"
  62 value according to base 10.
  63 .Pp
  64 The value obtained is then checked against the provided
  65 .Fa minval
  66 and
  67 .Fa maxval
  68 bounds.
  69 If
  70 .Fa errstr
  71 is non-null,
  72 .Fn strtonum
  73 stores an error string in
  74 .Fa *errstr
  75 indicating the failure.
  76 .Sh RETURN VALUES
  77 The
  78 .Fn strtonum
  79 function returns the result of the conversion,
  80 unless the value would exceed the provided bounds or is invalid.
  81 On error, 0 is returned,
  82 .Va errno
  83 is set, and
  84 .Fa errstr
  85 will point to an error message.
  86 On success,
  87 .Fa *errstr
  88 will be set to
  89 .Dv NULL ;
  90 this fact can be used to differentiate
  91 a successful return of 0 from an error.
  92 .Sh EXAMPLES
  93 Using
  94 .Fn strtonum
  95 correctly is meant to be simpler than the alternative functions.
  96 .Bd -literal -offset indent
  97 int iterations;
  98 const char *errstr;
  99
 100 iterations = strtonum(optarg, 1, 64, &errstr);
 101 if (errstr)
 102         errx(1, "number of iterations is %s: %s", errstr, optarg);
 103 .Ed
 104 .Pp
 105 The above example will guarantee that the value of iterations is between
 106 1 and 64 (inclusive).
 107 .Sh ERRORS
 108 .Bl -tag -width Er
 109 .It Bq Er ERANGE
 110 The given string was out of range.
 111 .It Bq Er EINVAL
 112 The given string did not consist solely of digit characters.
 113 .It Bq Er EINVAL
 114 The supplied
 115 .Fa minval
 116 was larger than
 117 .Fa maxval .
 118 .El
 119 .Pp
 120 If an error occurs,
 121 .Fa errstr
 122 will be set to one of the following strings:
 123 .Pp
 124 .Bl -tag -width ".Li too large" -compact
 125 .It Li "too large"
 126 The result was larger than the provided maximum value.
 127 .It Li "too small"
 128 The result was smaller than the provided minimum value.
 129 .It Li invalid
 130 The string did not consist solely of digit characters.
 131 .El
 132 .Sh SEE ALSO
 133 .Xr atof 3 ,
 134 .Xr atoi 3 ,
 135 .Xr atol 3 ,
 136 .Xr atoll 3 ,
 137 .Xr sscanf 3 ,
 138 .Xr strtod 3 ,
 139 .Xr strtol 3 ,
 140 .Xr strtoul 3
 141 .Sh STANDARDS
 142 The
 143 .Fn strtonum
 144 function is a
 145 .Bx
 146 extension.
 147 The existing alternatives, such as
 148 .Xr atoi 3
 149 and
 150 .Xr strtol 3 ,
 151 are either impossible or difficult to use safely.
 152 .Sh HISTORY
 153 The
 154 .Fn strtonum
 155 function first appeared in
 156 .Ox 3.6 .