lib/libc/stdlib/strtonum.3

   1 .\" $NetBSD: strtonum.3,v 1.2 2015/01/19 11:47:41 wiz Exp $
   2 .\" $OpenBSD: strtonum.3,v 1.17 2013/08/14 06:32:28 jmc Exp $
   3 .\"
   4 .\" Copyright (c) 2004 Ted Unangst
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd January 18, 2015
  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 .Vt #define _OPENBSD_SOURCE
  26 .In stdlib.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 .Li long long
  41 value.
  42 .Pp
  43 The string may begin with an arbitrary amount of whitespace
  44 (as determined by
  45 .Xr isspace 3 )
  46 followed by a single optional
  47 .Ql +
  48 or
  49 .Ql -
  50 sign.
  51 .Pp
  52 The remainder of the string is converted to a
  53 .Li long long
  54 value according to base 10.
  55 .Pp
  56 The value obtained is then checked against the provided
  57 .Fa minval
  58 and
  59 .Fa maxval
  60 bounds.
  61 If
  62 .Fa errstr
  63 is non-null,
  64 .Fn strtonum
  65 stores an error string in
  66 .Fa *errstr
  67 indicating the failure.
  68 .Sh RETURN VALUES
  69 The
  70 .Fn strtonum
  71 function returns the result of the conversion,
  72 unless the value would exceed the provided bounds or is invalid.
  73 On error, 0 is returned,
  74 .Va errno
  75 is set, and
  76 .Fa errstr
  77 will point to an error message.
  78 .Fa *errstr
  79 will be set to
  80 .Dv NULL
  81 on success;
  82 this fact can be used to differentiate
  83 a successful return of 0 from an error.
  84 .Sh EXAMPLES
  85 Using
  86 .Fn strtonum
  87 correctly is meant to be simpler than the alternative functions.
  88 .Bd -literal -offset indent
  89 int iterations;
  90 const char *errstr;
  91
  92 iterations = strtonum(optarg, 1, 64, &errstr);
  93 if (errstr)
  94         errx(1, "number of iterations is %s: %s", errstr, optarg);
  95 .Ed
  96 .Pp
  97 The above example will guarantee that the value of iterations is between
  98 1 and 64 (inclusive).
  99 .Sh ERRORS
 100 .Bl -tag -width Er
 101 .It Bq Er EINVAL
 102 The given string did not consist solely of digit characters; or
 103 .Ar minval
 104 was larger than
 105 .Ar maxval .
 106 .It Bq Er ERANGE
 107 The given string was out of range.
 108 .El
 109 .Pp
 110 If an error occurs,
 111 .Fa errstr
 112 will be set to one of the following strings:
 113 .Pp
 114 .Bl -tag -width "too largeXX" -compact
 115 .It Qq too large
 116 The result was larger than the provided maximum value.
 117 .It Qq too small
 118 The result was smaller than the provided minimum value.
 119 .It Qq invalid
 120 The string did not consist solely of digit characters.
 121 .El
 122 .Sh SEE ALSO
 123 .Xr atof 3 ,
 124 .Xr atoi 3 ,
 125 .Xr atol 3 ,
 126 .Xr atoll 3 ,
 127 .Xr sscanf 3 ,
 128 .Xr strtod 3 ,
 129 .Xr strtoi 3 ,
 130 .Xr strtol 3 ,
 131 .Xr strtoll 3 ,
 132 .Xr strtou 3 ,
 133 .Xr strtoul 3 ,
 134 .Xr strtoull 3
 135 .Sh STANDARDS
 136 .Fn strtonum
 137 is an
 138 .Ox
 139 extension.
 140 .Sh HISTORY
 141 The
 142 .Fn strtonum
 143 function first appeared in
 144 .Ox 3.6 .
 145 .Fn strtonum
 146 was redesigned in
 147 .Nx 8
 148 as
 149 .Fn strtoi 3
 150 and
 151 .Fn strtou 3 .
 152 For compatibility reasons it's available since
 153 .Nx 8
 154 in the
 155 .Vt _OPENBSD_SOURCE
 156 namespace.
 157 .Sh CAVEATS
 158 The
 159 .Fn strtonum
 160 function was designed to facilitate safe,
 161 robust programming and overcome the shortcomings of the
 162 .Xr atoi 3
 163 and
 164 .Xr strtol 3
 165 family of interfaces, however there are problems with the
 166 .Fn strtonum
 167 API:
 168 .Bl -dash
 169 .It
 170 will return 0 on failure; 0 might not be in range, so that necessitates
 171 an error check even if you want to avoid it
 172 .It
 173 does not differentiate 'illegal' returns, so we can't tell the
 174 difference between partial and no conversions
 175 .It
 176 returns english strings
 177 .It
 178 can't set the base, or find where the conversion ended
 179 .It
 180 hardcodes long long integer type
 181 .El
 182 To overcome the shortcomings of
 183 .Fn strtonum
 184 .Nx
 185 provides
 186 .Fn strtou 3
 187 and
 188 .Fn strtoi 3 .