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.13 2006/04/25 05:15:42 tedu 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 .Ft long long
  27 .Fo strtonum
  28 .Fa "const char *nptr"
  29 .Fa "long long minval"
  30 .Fa "long long maxval"
  31 .Fa "const char **errstr"
  32 .Fc
  33 .Sh DESCRIPTION
  34 The
  35 .Fn strtonum
  36 function converts the string in
  37 .Fa nptr
  38 to a
  39 .Vt "long long"
  40 value.
  41 The
  42 .Fn strtonum
  43 function was designed to facilitate safe, robust programming
  44 and overcome the shortcomings of the
  45 .Xr atoi 3
  46 and
  47 .Xr strtol 3
  48 family of interfaces.
  49 .Pp
  50 The string may begin with an arbitrary amount of whitespace
  51 (as determined by
  52 .Xr isspace 3 )
  53 followed by a single optional
  54 .Ql +
  55 or
  56 .Ql -
  57 sign.
  58 .Pp
  59 The remainder of the string is converted to a
  60 .Vt "long long"
  61 value according to base 10.
  62 .Pp
  63 The value obtained is then checked against the provided
  64 .Fa minval
  65 and
  66 .Fa maxval
  67 bounds.
  68 If
  69 .Fa errstr
  70 is non-null,
  71 .Fn strtonum
  72 stores an error string in
  73 .Fa *errstr
  74 indicating the failure.
  75 .Sh RETURN VALUES
  76 The
  77 .Fn strtonum
  78 function returns the result of the conversion,
  79 unless the value would exceed the provided bounds or is invalid.
  80 On error, 0 is returned,
  81 .Va errno
  82 is set, and
  83 .Fa errstr
  84 will point to an error message.
  85 On success,
  86 .Fa *errstr
  87 will be set to
  88 .Dv NULL ;
  89 this fact can be used to differentiate
  90 a successful return of 0 from an error.
  91 .Sh EXAMPLES
  92 Using
  93 .Fn strtonum
  94 correctly is meant to be simpler than the alternative functions.
  95 .Bd -literal -offset indent
  96 int iterations;
  97 const char *errstr;
  98
  99 iterations = strtonum(optarg, 1, 64, &errstr);
 100 if (errstr != NULL)
 101         errx(1, "number of iterations is %s: %s", errstr, optarg);
 102 .Ed
 103 .Pp
 104 The above example will guarantee that the value of iterations is between
 105 1 and 64 (inclusive).
 106 .Sh ERRORS
 107 .Bl -tag -width Er
 108 .It Bq Er ERANGE
 109 The given string was out of range.
 110 .It Bq Er EINVAL
 111 The given string did not consist solely of digit characters.
 112 .It Bq Er EINVAL
 113 The supplied
 114 .Fa minval
 115 was larger than
 116 .Fa maxval .
 117 .El
 118 .Pp
 119 If an error occurs,
 120 .Fa errstr
 121 will be set to one of the following strings:
 122 .Pp
 123 .Bl -tag -width ".Li too large" -compact
 124 .It Li "too large"
 125 The result was larger than the provided maximum value.
 126 .It Li "too small"
 127 The result was smaller than the provided minimum value.
 128 .It Li invalid
 129 The string did not consist solely of digit characters.
 130 .El
 131 .Sh SEE ALSO
 132 .Xr atof 3 ,
 133 .Xr atoi 3 ,
 134 .Xr atol 3 ,
 135 .Xr atoll 3 ,
 136 .Xr sscanf 3 ,
 137 .Xr strtod 3 ,
 138 .Xr strtol 3 ,
 139 .Xr strtoul 3
 140 .Sh STANDARDS
 141 The
 142 .Fn strtonum
 143 function is a
 144 .Bx
 145 extension.
 146 The existing alternatives, such as
 147 .Xr atoi 3
 148 and
 149 .Xr strtol 3 ,
 150 are either impossible or difficult to use safely.
 151 .Sh HISTORY
 152 The
 153 .Fn strtonum
 154 function first appeared in
 155 .Ox 3.6 .