1.\" $NetBSD: strsuftoll.3,v 1.11 2010/12/14 13:00:34 jruoho Exp $ 2.\" 3.\" Copyright (c) 2002,2007 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Luke Mewburn. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd May 5, 2018 31.Dt STRSUFTOLL 3 32.Os 33.Sh NAME 34.Nm strsuftoll , 35.Nm strsuftollx 36.Nd "convert a string to a long long, with suffix parsing" 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In stdlib.h 41.Ft long long 42.Fn strsuftoll "const char *desc" "const char *val" "long long min" "long long max" 43.Ft long long 44.Fn strsuftollx "const char *desc" "const char *val" "long long min" "long long max" "char *errbuf" "size_t errbuflen" 45.Sh DESCRIPTION 46The functions 47.Fn strsuftoll 48and 49.Fn strsuftollx 50convert 51.Fa val 52into a number of type 53.Vt long long , 54checking that the result is not smaller than 55.Fa min 56or larger than 57.Fa max . 58Two or more decimal numbers may be separated by an 59.Dq x 60to indicate a product. 61.Pp 62Each decimal number may have one of the following optional suffixes: 63.Pp 64.Bl -tag -width 3n -offset indent -compact 65.It Em b 66Block; multiply by 512 67.It Em k 68Kibi; multiply by 1024 (1 KiB) 69.It Em m 70Mebi; multiply by 1048576 (1 MiB) 71.It Em g 72Gibi; multiply by 1073741824 (1 GiB) 73.It Em t 74Tebi; multiply by 1099511627776 (1 TiB) 75.It Em w 76Word; multiply by the number of bytes in an integer 77.El 78.Pp 79In the case of an error (range overflow or an invalid number), 80.Fn strsuftollx 81places an error message into 82.Fa errbuf 83(which is 84.Fa errbuflen 85bytes long) and returns 0, 86and 87.Fn strsuftoll 88displays that error and terminates the process. 89The parameter 90.Fa desc 91is used to construct 92.Fa errbuf . 93.Pp 94Neither 95.Fa desc 96nor 97.Fa val 98may be 99.Dv NULL . 100.Sh RETURN VALUES 101The functions 102.Fn strsuftoll 103and 104.Fn strsuftollx 105return either the result of the conversion, 106unless the value overflows or is not a number; 107in the latter case, 108.Fn strsuftoll 109displays an error message and terminates the process with exit code 110.Dv EXIT_FAILURE , 111and 112.Fn strsuftollx 113returns with 0 and 114.Fa errbuf 115contains a non-empty error message. 116.Sh ERRORS 117.Bl -tag -width Er 118.It Bq Er ERANGE 119The given string was out of range; the value converted has been clamped. 120.El 121.Sh SEE ALSO 122.Xr errx 3 , 123.Xr strtoll 3 , 124.Xr orders 7 125.Sh BUGS 126At least few limitations should be mentioned: 127.Bl -bullet 128.It 129Both functions ignore the current locale. 130.It 131Neither 132.Fn strsuftoll 133nor 134.Fn strsuftollx 135fail gracefully in case of invalid, 136.Dv NULL , 137pointers. 138.It 139Arguably the return type should be 140.Vt intmax_t 141instead of 142.Vt long long . 143.It 144The 145.Fn strsuftollx 146function is prone to buffer overflows if used incorrectly. 147Arguably only 148.Fn strsuftoll 149should be exposed to a caller. 150.El 151