kc3-lang/libbsd/man/strtonum.3bsd

• Show log

  Commit

• Hash : 21f4052c
  Author :
  Date : 2019-06-13T23:36:09
  

  man: Add doc-str-Lb-libbsd aliases for str-Lb-libbsd groff(1) has changed the internal layout for the .Lb doc strings, but to preserve backwards compatibility we cannot simply rename them, we need to create new aliases so that these will work with old and new macros. Signed-off-by: Guillem Jover <guillem@hadrons.org>

Download

• man/strtonum.3bsd

• .\" $NetBSD: strtonum.3,v 1.2 2015/01/19 11:47:41 wiz Exp $
  .\" $OpenBSD: strtonum.3,v 1.17 2013/08/14 06:32:28 jmc Exp $
  .\"
  .\" Copyright (c) 2004 Ted Unangst
  .\"
  .\" Permission to use, copy, modify, and distribute this software for any
  .\" purpose with or without fee is hereby granted, provided that the above
  .\" copyright notice and this permission notice appear in all copies.
  .\"
  .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  .\"
  .Dd January 18, 2015
  .Dt STRTONUM 3bsd
  .Os
  .Sh NAME
  .Nm strtonum
  .Nd reliably convert string value to an integer
  .Sh LIBRARY
  .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
  .ds doc-str-Lb-libbsd \*[str-Lb-libbsd]
  .Lb libbsd
  .Sh SYNOPSIS
  .In limits.h
  .In stdlib.h
  (See
  .Xr libbsd 7
  for include usage.)
  .Ft long long
  .Fo strtonum
  .Fa "const char *nptr"
  .Fa "long long minval"
  .Fa "long long maxval"
  .Fa "const char **errstr"
  .Fc
  .Sh DESCRIPTION
  The
  .Fn strtonum
  function converts the string in
  .Fa nptr
  to a
  .Vt "long long"
  value.
  .Pp
  The string may begin with an arbitrary amount of whitespace
  (as determined by
  .Xr isspace 3 )
  followed by a single optional
  .Ql +
  or
  .Ql -
  sign.
  .Pp
  The remainder of the string is converted to a
  .Vt "long long"
  value according to base 10.
  .Pp
  The value obtained is then checked against the provided
  .Fa minval
  and
  .Fa maxval
  bounds.
  If
  .Fa errstr
  is non-null,
  .Fn strtonum
  stores an error string in
  .Fa *errstr
  indicating the failure.
  .Sh RETURN VALUES
  The
  .Fn strtonum
  function returns the result of the conversion,
  unless the value would exceed the provided bounds or is invalid.
  On error, 0 is returned,
  .Va errno
  is set, and
  .Fa errstr
  will point to an error message.
  On success,
  .Fa *errstr
  will be set to
  .Dv NULL ;
  this fact can be used to differentiate
  a successful return of 0 from an error.
  .Sh EXAMPLES
  Using
  .Fn strtonum
  correctly is meant to be simpler than the alternative functions.
  .Bd -literal -offset indent
  int iterations;
  const char *errstr;
  
  iterations = strtonum(optarg, 1, 64, &errstr);
  if (errstr)
  	errx(1, "number of iterations is %s: %s", errstr, optarg);
  .Ed
  .Pp
  The above example will guarantee that the value of iterations is between
  1 and 64 (inclusive).
  .Sh ERRORS
  .Bl -tag -width Er
  .It Bq Er EINVAL
  The given string did not consist solely of digit characters; or
  .Ar minval
  was larger than
  .Ar maxval .
  .It Bq Er ERANGE
  The given string was out of range.
  .El
  .Pp
  If an error occurs,
  .Fa errstr
  will be set to one of the following strings:
  .Pp
  .Bl -tag -width ".Li too large" -compact
  .It Li "too large"
  The result was larger than the provided maximum value.
  .It Li "too small"
  The result was smaller than the provided minimum value.
  .It Li invalid
  The string did not consist solely of digit characters.
  .El
  .Sh SEE ALSO
  .Xr atof 3 ,
  .Xr atoi 3 ,
  .Xr atol 3 ,
  .Xr atoll 3 ,
  .Xr sscanf 3 ,
  .Xr strtod 3 ,
  .Xr strtoi 3bsd ,
  .Xr strtol 3 ,
  .Xr strtoll 3 ,
  .Xr strtou 3bsd ,
  .Xr strtoul 3 ,
  .Xr strtoull 3
  .Sh STANDARDS
  .Fn strtonum
  is an
  .Ox
  extension.
  .Sh HISTORY
  .ds doc-operating-system-NetBSD-8.0 8.0
  The
  .Fn strtonum
  function first appeared in
  .Ox 3.6 .
  .Fn strtonum
  was redesigned in
  .Nx 8.0
  as
  .Fn strtoi 3bsd
  and
  .Fn strtou 3bsd .
  .Sh CAVEATS
  The
  .Fn strtonum
  function was designed to facilitate safe,
  robust programming and overcome the shortcomings of the
  .Xr atoi 3
  and
  .Xr strtol 3
  family of interfaces, however there are problems with the
  .Fn strtonum
  API:
  .Bl -dash
  .It
  will return 0 on failure; 0 might not be in range, so that necessitates
  an error check even if you want to avoid it
  .It
  does not differentiate 'illegal' returns, so we can't tell the
  difference between partial and no conversions
  .It
  returns english strings
  .It
  can't set the base, or find where the conversion ended
  .It
  hardcodes long long integer type
  .El
  To overcome the shortcomings of
  .Fn strtonum
  .Nx
  provides
  .Fn strtou 3bsd
  and
  .Fn strtoi 3bsd .
  

Download