New: fmt_scaled() and scan_scaled() convert to and from "human readable"

or scaled numbers. fmt_scaled, and the format, based on Ken Stailey's
code for "df -h"; scan_scaled is new. Significantly commented on
and reworked by pjanzen@; other comments from millert@.  OK pjanzen@.

src/lib/libutil/Makefile

@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.25 2001/09/29 17:45:35 jakob Exp $
+#	$OpenBSD: Makefile,v 1.26 2003/05/15 01:26:26 ian Exp $
 #	$NetBSD: Makefile,v 1.8 1996/05/16 07:03:28 thorpej Exp $
 
 LIB=	util
@@ -7,11 +7,13 @@ CFLAGS+=-DLIBC_SCCS
 HDRS=	util.h scsi.h
 SRCS=	check_expire.c getmaxpartitions.c getrawpartition.c login.c \
 	login_tty.c logout.c logwtmp.c opendev.c passwd.c pty.c readlabel.c \
-	scsi.c login_fbtab.c uucplock.c fparseln.c opendisk.c pidfile.c
+	scsi.c login_fbtab.c uucplock.c fparseln.c opendisk.c pidfile.c \
+	fmt_scaled.c
 
 MAN=	check_expire.3 getmaxpartitions.3 getrawpartition.3 login.3 opendev.3 \
 	openpty.3 pw_init.3 pw_lock.3 readlabelfs.3 scsi.3 pw_getconf.3 \
-	uucplock.3 fparseln.3 opendisk.3 login_fbtab.3 pidfile.3
+	uucplock.3 fparseln.3 opendisk.3 login_fbtab.3 pidfile.3 \
+	fmt_scaled.3
 
 MLINKS+=login.3 logout.3
 MLINKS+=login.3 logwtmp.3
@@ -42,6 +44,7 @@ MLINKS+=uucplock.3 uu_lock.3
 MLINKS+=uucplock.3 uu_unlock.3
 MLINKS+=uucplock.3 uu_lockerr.3
 MLINKS+=uucplock.3 uu_lock_txfr.3
+MLINKS+=fmt_scaled.3 scan_scaled.3
 
 includes:
 	@cd ${.CURDIR}; for i in $(HDRS); do \

src/lib/libutil/fmt_scaled.3

@@ -0,0 +1,132 @@
+.\"	$OpenBSD: fmt_scaled.3,v 1.1 2003/05/15 01:26:26 ian Exp $
+.\" Copyright (c) 2001, 2003 Ian Darwin.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd September 19, 2001
+.Dt FMT_SCALED 3
+.Os
+.Sh NAME
+.Nm fmt_scaled ,
+.Nm scan_scaled
+.Nd handle numbers with a human-readable scale
+.Sh SYNOPSIS
+.Fd #include <util.h>
+.Ft int
+.Fn scan_scaled "char *number_w_scale" "long long *result"
+.Ft int
+.Fn fmt_scaled "long long number" "char *result"
+.Sh DESCRIPTION
+The
+.Fn scan_scaled
+function scans the given number and looks for a terminal scale multiplier
+of B, K, M, G, T, P or E
+.Pq in either upper or lower case
+for Byte, Kilobyte, Megabyte, Gigabyte, Terabyte, Petabyte, Exabyte
+.Po computed using powers of two, i.e., Megabyte = 1024*1024
+.Pc .
+The number can have a decimal point, as in 1.5K, which returns 1536
+.Pq 1024+512 .
+If no scale factor is found, B is assumed.
+.Pp
+The
+.Fn fmt_scaled
+function formats a number for display using the same
+"human-readable" format, that is, a number with one of the above scale factors.
+Numbers will be printed with a maximum of four digits (preceded by
+a minus sign if the value is negative); values such
+as 0B, 100B, 1023B, 1K, 1.5K, 5.5M, and so on, will be generated.
+The
+.Qq result
+buffer must be allocated with at least
+.Dv FMT_SCALED_STRSIZE
+bytes.
+The result will be left-justified in the given space, and null-terminated.
+.Sh RETURN VALUES
+The
+.Fn scan_scaled
+and
+.Fn fmt_scaled
+functions
+return 0 on success.
+In case of error, they return \-1, leave
+.Va *result
+as is, and set
+.Va errno
+to one of the following values:
+.Dv EFAULT
+if an input pointer is
+.Dv NULL .
+.Dv ERANGE
+if the input string represents a number that is too large to represent.
+.Dv EINVAL
+if an unknown character was used as scale factor, or
+if the input to
+.Fn scan_scaled
+was malformed, e.g., too many '.' characters.
+.Sh EXAMPLES
+.Bd -literal -offset indent
+char *cinput = "1.5K";
+long long result;
+if (scan_scaled(cinput, &result) != 0)
+	printf("%s -> %ld\en", cinput, result);
+else
+	fprintf(stderr, "%s - invalid\en", cinput);
+
+char buf[FMT_SCALED_STRSIZE];
+long long ninput = 10483892;
+if (fmt_scaled(ninput, buf) == 0)
+	printf("%lld -> %s\en", ninput, buf);
+else
+	fprintf(stderr, "fmt scaled failed (errno %d)", errno);
+.Ed
+.Sh SEE ALSO
+.Xr printf 3 ,
+.Xr scanf 3
+.Sh BUGS
+Some of the scale factors have misleading meanings in lower case
+(p for P is incorrect; p should be pico- and P for Peta-).
+However, we bend the SI rules in favor of common sense here.
+A person creating a disk partition of "100m" is unlikely to require
+100 millibytes (i.e., 0.1 byte) of storage in the partition;
+100 megabytes is the only reasonable interpretation.
+.Pp
+Cannot represent the larger scale factors on all architectures.
+.Pp
+Ignores the current locale.
+.Sh HISTORY
+The functions
+.Fn fmt_scaled
+and
+.Fn scan_scaled
+first appeared in
+.Ox 3.4 .
+.Sh AUTHORS
+Ken Stailey wrote the first version of the code that became
+.Xr fmt_scaled 3 ,
+originally inside
+.Ox
+.Xr df 1 .
+Ian Darwin excerpted this and made it into a library routine
+(with significant help from Paul Janzen), and wrote
+.Xr scan_scaled 3 .

src/lib/libutil/fmt_scaled.c

@@ -0,0 +1,277 @@
+/*	$OpenBSD: fmt_scaled.c,v 1.1 2003/05/15 01:26:26 ian Exp $	*/
+
+/*
+ * Copyright (c) 2001, 2002, 2003 Ian F. Darwin.  All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ * 3. The name of the author may not be used to endorse or promote products
+ *    derived from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * fmt_scaled: Format numbers scaled for human comprehension
+ * scan_scaled: Scan numbers in this format.
+ *
+ * "Human-readable" output uses 4 digits max, and puts a unit suffix at
+ * the end.  Makes output compact and easy-to-read esp. on huge disks.
+ * Formatting code was originally in OpenBSD "df", converted to library routine.
+ * Scanning code written for OpenBSD libutil.
+ */
+
+#if defined(LIBC_SCCS) && !defined(lint)
+static const char ident[] = "$OpenBSD: fmt_scaled.c,v 1.1 2003/05/15 01:26:26 ian Exp $";
+#endif /* LIBC_SCCS and not lint */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <errno.h>
+#include <string.h>
+#include <ctype.h>
+#include <limits.h>
+
+#include "util.h"
+
+typedef enum {
+	NONE = 0, KILO = 1, MEGA = 2, GIGA = 3, TERA = 4, PETA = 5, EXA = 6
+} unit_type;
+
+/* These three arrays MUST be in sync!  XXX make a struct */
+static unit_type units[] = { NONE, KILO, MEGA, GIGA, TERA, PETA, EXA };
+static char scale_chars[] = "BKMGTPE";
+static long long scale_factors[] = {
+	1LL,
+	1024LL,
+	1024LL*1024,
+	1024LL*1024*1024,
+	1024LL*1024*1024*1024,
+	1024LL*1024*1024*1024*1024,
+	1024LL*1024*1024*1024*1024*1024,
+};
+#define	SCALE_LENGTH (sizeof(units)/sizeof(units[0]))
+
+#define MAX_DIGITS (SCALE_LENGTH * 3)	/* XXX strlen(sprintf("%lld", -1)? */
+
+/** Convert the given input string "scaled" into numeric in "result".
+ * Return 0 on success, -1 and errno set on error.
+ */
+int
+scan_scaled(char *scaled, long long *result)
+{
+	char *p = scaled;
+	int sign = 0;
+	unsigned int i, ndigits = 0, fract_digits = 0;
+	long long scale_fact = 1, whole = 0, fpart = 0;
+
+	if (p == NULL || result == NULL) {
+		errno = EFAULT;
+		return -1;
+	}
+
+	/* Skip leading whitespace */
+	while (*p && isascii(*p) && isspace(*p))
+		++p;
+
+	/* Then at most one leading + or - */
+	while (*p == '-' || *p == '+') {
+		if (*p == '-') {
+			if (sign) {
+				errno = EINVAL;
+				return -1;
+			}
+			sign = -1;
+			++p;
+		} else if (*p == '+') {
+			if (sign) {
+				errno = EINVAL;
+				return -1;
+			}
+			sign = +1;
+			++p;
+		}
+	}
+
+	/* Main loop: Scan digits, find decimal point, if present.
+	 * We don't allow exponentials, so no scientific notation
+	 * (but note that E for Exa might look like e to some!).
+	 * Advance 'p' to end, to get scale factor.
+	 */
+	for (; *p && isascii(*p) && (isdigit(*p) || *p=='.'); ++p) {
+		if (*p == '.') {
+			if (fract_digits > 0) {	/* oops, more than one '.' */
+				errno = EINVAL;
+				return -1;
+			}
+			fract_digits = 1;
+			continue;
+		}
+
+		i = (*p) - '0';			/* whew! finally a digit we can use */
+		if (fract_digits > 0) {
+			if (fract_digits >= MAX_DIGITS-1)
+				continue;		/* ignore extra fractional digits */
+			fract_digits++;		/* for later scaling */
+			fpart *= 10;
+			fpart += i;
+		} else {				/* normal digit */
+			if (++ndigits >= MAX_DIGITS) {
+				errno = ERANGE;
+				return -1;
+			}
+			whole *= 10;
+			whole += i;
+		}
+	}
+
+	if (sign) {
+		whole *= sign;
+		fpart *= sign;
+	}
+
+	/* If no scale factor given, we're done. fraction is discarded. */
+	if (!*p) {
+		*result = whole;
+		return 0;
+	}
+
+	/* Validate scale factor, and scale whole and fraction by it. */
+	for (i = 0; i < SCALE_LENGTH; i++) {
+
+		/** Are we there yet? */
+		if (*p == scale_chars[i] ||
+			*p == tolower(scale_chars[i])) {
+
+			/* If it ends with alphanumerics after the scale char, bad. */
+			if (*(p+1) != '\0' && isalnum(*(p+1))) {
+				errno = EINVAL;
+				return -1;
+			}
+			scale_fact = scale_factors[i];
+
+			/* scale whole part */
+			whole *= scale_fact;
+
+			/* truncate fpart so it does't overflow.
+			 * then scale fractional part.
+			 */
+			while (fpart >= LLONG_MAX / scale_fact) {
+				fpart /= 10;
+				fract_digits--;
+			}
+			fpart *= scale_fact;
+			if (fract_digits > 0) {
+				for (i = 0; i < fract_digits -1; i++)
+					fpart /= 10;
+			}
+			whole += fpart;
+			*result = whole;
+			return 0;
+		}
+	}
+	errno = ERANGE;
+	return -1;
+}
+
+/* Format the given "number" into human-readable form in "result".
+ * Result must point to an allocated buffer of length FMT_SCALED_STRSIZE.
+ * Return 0 on success, -1 and errno set if error.
+ */
+int
+fmt_scaled(long long number, char *result)
+{
+	long long abval, fract = 0;
+	unsigned int i;
+	unit_type unit = NONE;
+
+	if (result == NULL) {
+		errno = EFAULT;
+		return -1;
+	}
+
+	abval = (number < 0LL) ? -number : number;	/* no long long_abs yet */
+
+	/* Not every negative long long has a positive representation.
+	 * Also check for numbers that are just too darned big to format
+	 */
+	if (abval < 0 || abval / 1024 >= scale_factors[SCALE_LENGTH-1]) {
+		errno = ERANGE;
+		return -1;
+	}
+
+	/* scale whole part; get unscaled fraction */
+	for (i = 0; i < SCALE_LENGTH; i++) {
+		if (abval/1024 < scale_factors[i]) {
+			unit = units[i];
+			fract = (i == 0) ? 0 : abval % scale_factors[i];
+			number /= scale_factors[i];
+			break;
+		}
+	}
+
+	/* scale fraction to one digit (by rounding) - thnx pjanzen */
+	for (i = SCALE_LENGTH-1; i > 0; i--) {
+		if (fract > scale_factors[i]) {
+			fract /= scale_factors[i];
+			break;
+		}
+	}
+	fract = (10 * fract + 512) / 1024;
+	/* if the result would be >= 10, round main number up */
+	if (fract == 10) {
+		number++;
+		fract = 0;
+	}
+
+	if (number == 0)
+		strlcpy(result, "0B", FMT_SCALED_STRSIZE);
+	else if (number > 100 || number < -100)
+		(void)snprintf(result, FMT_SCALED_STRSIZE, "%lld%c",
+			number, scale_chars[unit]);
+	else
+		(void)snprintf(result, FMT_SCALED_STRSIZE, "%lld.%1lld%c",
+			number, fract, scale_chars[unit]);
+
+	return 0;
+}
+
+#ifdef	MAIN
+/*
+ * This is the original version of the program in the man page.
+ * Copy-and-paste whatever you need from it.
+ */
+int
+main(int argc, char **argv)
+{
+	char *cinput = "1.5K", buf[FMT_SCALED_STRSIZE];
+	long long ninput = 10483892, result;
+
+	if (scan_scaled(cinput, &result) == 0)
+		printf("\"%s\" -> %lld\n", cinput, result);
+	else
+		perror(cinput);
+
+	if (fmt_scaled(ninput, buf) == 0)
+		printf("%lld -> \"%s\"\n", ninput, buf);
+	else
+		fprintf(stderr, "%lld invalid (%s)\n", ninput, strerror(errno));
+
+	return 0;
+}
+#endif

src/lib/libutil/shlib_version

@@ -1,2 +1,2 @@
 major=8
-minor=0
+minor=1

src/lib/libutil/util.h

@@ -1,4 +1,4 @@
-/*	$OpenBSD: util.h,v 1.22 2002/06/21 16:37:11 millert Exp $	*/
+/*	$OpenBSD: util.h,v 1.23 2003/05/15 01:26:26 ian Exp $	*/
 /*	$NetBSD: util.h,v 1.2 1996/05/16 07:00:22 thorpej Exp $	*/
 
 /*-
@@ -70,6 +70,11 @@
 #define UU_LOCK_TRY_ERR (-6)
 #define UU_LOCK_OWNER_ERR (-7)
 
+/*
+ * fmt_scaled(3) specific flags.
+ */
+#define	FMT_SCALED_STRSIZE	7	/* minus sign, 4 digits, suffix, null byte */
+
 /*
  * stub struct definitions.
  */
@@ -113,6 +118,8 @@ const char *uu_lockerr(int _uu_lockresult);
 int     uu_lock(const char *_ttyname);
 int	uu_lock_txfr(const char *_ttyname, pid_t _pid);
 int     uu_unlock(const char *_ttyname);
+int	fmt_scaled(long long number, char *result);
+int	scan_scaled(char *scaled, long long *result);
 __END_DECLS
 
 #endif /* !_UTIL_H_ */