From 8e810a2fd753f8a84bbe5898a98d95a0d38f7905 Mon Sep 17 00:00:00 2001 From: Curtis McEnroe Date: Thu, 10 Jan 2019 22:48:01 -0500 Subject: Create cash-printf.1 --- bin/cash/cash-printf.1 | 382 +++++++++++++++++++++++++++++++++++++++++++++++++ bin/cash/printf.1 | 382 ------------------------------------------------- 2 files changed, 382 insertions(+), 382 deletions(-) create mode 100644 bin/cash/cash-printf.1 delete mode 100644 bin/cash/printf.1 diff --git a/bin/cash/cash-printf.1 b/bin/cash/cash-printf.1 new file mode 100644 index 00000000..ed758757 --- /dev/null +++ b/bin/cash/cash-printf.1 @@ -0,0 +1,382 @@ +.\" Copyright (c) 1989, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the Institute of Electrical and Electronics Engineers, Inc. +.\" +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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. +.\" +.\" @(#)printf.1 8.1 (Berkeley) 6/6/93 +.\" $FreeBSD: releng/12.0/usr.bin/printf/printf.1 314436 2017-02-28 23:42:47Z imp $ +.\" +.Dd January 10, 2019 +.Dt CASH-PRINTF 1 +.Os +.Sh NAME +.Nm printf +.Nd formatted output +.Sh SYNOPSIS +.Nm +.Ar format Op Ar arguments ... +.Sh DESCRIPTION +The +.Nm +utility formats and prints its arguments, after the first, under control +of the +.Ar format . +The +.Ar format +is a character string which contains three types of objects: plain characters, +which are simply copied to standard output, character escape sequences which +are converted and copied to the standard output, and format specifications, +each of which causes printing of the next successive +.Ar argument . +.Pp +The +.Ar arguments +after the first are treated as strings if the corresponding format is +either +.Cm c , b +or +.Cm s ; +otherwise it is evaluated as a C constant, with the following extensions: +.Pp +.Bl -bullet -offset indent -compact +.It +A leading plus or minus sign is allowed. +.It +If the leading character is a single or double quote, the value is the +character code of the next character. +.El +.Pp +The format string is reused as often as necessary to satisfy the +.Ar arguments . +Any extra format specifications are evaluated with zero or the null +string. +.Pp +Character escape sequences are in backslash notation as defined in the +.St -ansiC , +with extensions. +The characters and their meanings +are as follows: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It Cm \ea +Write a character. +.It Cm \eb +Write a character. +.It Cm \ec +Ignore remaining characters in this string. +.It Cm \ef +Write a character. +.It Cm \en +Write a character. +.It Cm \er +Write a character. +.It Cm \et +Write a character. +.It Cm \ev +Write a character. +.It Cm \e\' +Write a character. +.It Cm \e\e +Write a backslash character. +.It Cm \e Ns Ar num +Write a byte whose +value is the 1-, 2-, or 3-digit +octal number +.Ar num . +Multibyte characters can be constructed using multiple +.Cm \e Ns Ar num +sequences. +.El +.Pp +Each format specification is introduced by the percent character +(``%''). +The remainder of the format specification includes, +in the following order: +.Bl -tag -width Ds +.It "Zero or more of the following flags:" +.Bl -tag -width Ds +.It Cm # +A `#' character +specifying that the value should be printed in an ``alternate form''. +For +.Cm b , c , d , s +and +.Cm u +formats, this option has no effect. +For the +.Cm o +formats the precision of the number is increased to force the first +character of the output string to a zero. +For the +.Cm x +.Pq Cm X +format, a non-zero result has the string +.Li 0x +.Pq Li 0X +prepended to it. +For +.Cm a , A , e , E , f , F , g +and +.Cm G +formats, the result will always contain a decimal point, even if no +digits follow the point (normally, a decimal point only appears in the +results of those formats if a digit follows the decimal point). +For +.Cm g +and +.Cm G +formats, trailing zeros are not removed from the result as they +would otherwise be; +.It Cm \&\- +A minus sign `\-' which specifies +.Em left adjustment +of the output in the indicated field; +.It Cm \&+ +A `+' character specifying that there should always be +a sign placed before the number when using signed formats. +.It Sq \&\ \& +A space specifying that a blank should be left before a positive number +for a signed format. +A `+' overrides a space if both are used; +.It Cm \&0 +A zero `0' character indicating that zero-padding should be used +rather than blank-padding. +A `\-' overrides a `0' if both are used; +.El +.It "Field Width:" +An optional digit string specifying a +.Em field width ; +if the output string has fewer bytes than the field width it will +be blank-padded on the left (or right, if the left-adjustment indicator +has been given) to make up the field width (note that a leading zero +is a flag, but an embedded zero is part of a field width); +.It Precision: +An optional period, +.Sq Cm \&.\& , +followed by an optional digit string giving a +.Em precision +which specifies the number of digits to appear after the decimal point, +for +.Cm e +and +.Cm f +formats, or the maximum number of bytes to be printed +from a string; if the digit string is missing, the precision is treated +as zero; +.It Format: +A character which indicates the type of format to use (one of +.Cm diouxXfFeEgGaAcsb ) . +The uppercase formats differ from their lowercase counterparts only in +that the output of the former is entirely in uppercase. +The floating-point format specifiers +.Pq Cm fFeEgGaA +may be prefixed by an +.Cm L +to request that additional precision be used, if available. +.El +.Pp +A field width or precision may be +.Sq Cm \&* +instead of a digit string. +In this case an +.Ar argument +supplies the field width or precision. +.Pp +The format characters and their meanings are: +.Bl -tag -width Fl +.It Cm diouXx +The +.Ar argument +is printed as a signed decimal (d or i), unsigned octal, unsigned decimal, +or unsigned hexadecimal (X or x), respectively. +.It Cm fF +The +.Ar argument +is printed in the style `[\-]ddd.ddd' where the number of d's +after the decimal point is equal to the precision specification for +the argument. +If the precision is missing, 6 digits are given; if the precision +is explicitly 0, no digits and no decimal point are printed. +The values \*[If] and \*[Na] are printed as +.Ql inf +and +.Ql nan , +respectively. +.It Cm eE +The +.Ar argument +is printed in the style +.Cm e +.Sm off +.Sq Op - Ar d.ddd No \(+- Ar dd +.Sm on +where there +is one digit before the decimal point and the number after is equal to +the precision specification for the argument; when the precision is +missing, 6 digits are produced. +The values \*[If] and \*[Na] are printed as +.Ql inf +and +.Ql nan , +respectively. +.It Cm gG +The +.Ar argument +is printed in style +.Cm f +.Pq Cm F +or in style +.Cm e +.Pq Cm E +whichever gives full precision in minimum space. +.It Cm aA +The +.Ar argument +is printed in style +.Sm off +.Sq Op - Ar h.hhh No \(+- Li p Ar d +.Sm on +where there is one digit before the hexadecimal point and the number +after is equal to the precision specification for the argument; +when the precision is missing, enough digits are produced to convey +the argument's exact double-precision floating-point representation. +The values \*[If] and \*[Na] are printed as +.Ql inf +and +.Ql nan , +respectively. +.It Cm c +The first byte of +.Ar argument +is printed. +.It Cm s +Bytes from the string +.Ar argument +are printed until the end is reached or until the number of bytes +indicated by the precision specification is reached; however if the +precision is 0 or missing, the string is printed entirely. +.It Cm b +As for +.Cm s , +but interpret character escapes in backslash notation in the string +.Ar argument . +The permitted escape sequences are slightly different in that +octal escapes are +.Cm \e0 Ns Ar num +instead of +.Cm \e Ns Ar num . +.It Cm n$ +Allows reordering of the output according to +.Ar argument . +.It Cm \&% +Print a `%'; no argument is used. +.El +.Pp +The decimal point +character is defined in the program's locale (category +.Dv LC_NUMERIC ) . +.Pp +In no case does a non-existent or small field width cause truncation of +a field; padding takes place only if the specified field width exceeds +the actual width. +.Pp +Some shells may provide a builtin +.Nm +command which is similar or identical to this utility. +Consult the +.Xr builtin 1 +manual page. +.Sh EXIT STATUS +.Ex -std +.Sh COMPATIBILITY +The traditional +.Bx +behavior of converting arguments of numeric formats not beginning +with a digit to the +.Tn ASCII +code of the first character is not supported. +.Sh SEE ALSO +.Xr builtin 1 , +.Xr echo 1 , +.Xr sh 1 , +.Xr printf 3 +.Sh STANDARDS +The +.Nm +command is expected to be compatible with the +.St -p1003.2 +specification. +.Sh HISTORY +The +.Nm +command appeared in +.Bx 4.3 Reno . +It is modeled +after the standard library function, +.Xr printf 3 . +.Sh CAVEATS +.Tn ANSI +hexadecimal character constants were deliberately not provided. +.Pp +Trying to print a dash ("-") as the first character causes +.Nm +to interpret the dash as a program argument. +.Nm -- +must be used before +.Ar format . +.Pp +If the locale contains multibyte characters +(such as UTF-8), +the +.Cm c +format and +.Cm b +and +.Cm s +formats with a precision +may not operate as expected. +.Sh BUGS +Since the floating point numbers are translated from +.Tn ASCII +to floating-point and +then back again, floating-point precision may be lost. +(By default, the number is translated to an IEEE-754 double-precision +value before being printed. +The +.Cm L +modifier may produce additional precision, depending on the hardware platform.) +.Pp +The escape sequence \e000 is the string terminator. +When present in the argument for the +.Cm b +format, the argument will be truncated at the \e000 character. +.Pp +Multibyte characters are not recognized in format strings (this is only +a problem if +.Ql % +can appear inside a multibyte character). diff --git a/bin/cash/printf.1 b/bin/cash/printf.1 deleted file mode 100644 index 093c1f2c..00000000 --- a/bin/cash/printf.1 +++ /dev/null @@ -1,382 +0,0 @@ -.\" Copyright (c) 1989, 1990, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" This code is derived from software contributed to Berkeley by -.\" the Institute of Electrical and Electronics Engineers, Inc. -.\" -.\" 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. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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. -.\" -.\" @(#)printf.1 8.1 (Berkeley) 6/6/93 -.\" $FreeBSD: releng/12.0/usr.bin/printf/printf.1 314436 2017-02-28 23:42:47Z imp $ -.\" -.Dd April 21, 2014 -.Dt PRINTF 1 -.Os -.Sh NAME -.Nm printf -.Nd formatted output -.Sh SYNOPSIS -.Nm -.Ar format Op Ar arguments ... -.Sh DESCRIPTION -The -.Nm -utility formats and prints its arguments, after the first, under control -of the -.Ar format . -The -.Ar format -is a character string which contains three types of objects: plain characters, -which are simply copied to standard output, character escape sequences which -are converted and copied to the standard output, and format specifications, -each of which causes printing of the next successive -.Ar argument . -.Pp -The -.Ar arguments -after the first are treated as strings if the corresponding format is -either -.Cm c , b -or -.Cm s ; -otherwise it is evaluated as a C constant, with the following extensions: -.Pp -.Bl -bullet -offset indent -compact -.It -A leading plus or minus sign is allowed. -.It -If the leading character is a single or double quote, the value is the -character code of the next character. -.El -.Pp -The format string is reused as often as necessary to satisfy the -.Ar arguments . -Any extra format specifications are evaluated with zero or the null -string. -.Pp -Character escape sequences are in backslash notation as defined in the -.St -ansiC , -with extensions. -The characters and their meanings -are as follows: -.Pp -.Bl -tag -width Ds -offset indent -compact -.It Cm \ea -Write a character. -.It Cm \eb -Write a character. -.It Cm \ec -Ignore remaining characters in this string. -.It Cm \ef -Write a character. -.It Cm \en -Write a character. -.It Cm \er -Write a character. -.It Cm \et -Write a character. -.It Cm \ev -Write a character. -.It Cm \e\' -Write a character. -.It Cm \e\e -Write a backslash character. -.It Cm \e Ns Ar num -Write a byte whose -value is the 1-, 2-, or 3-digit -octal number -.Ar num . -Multibyte characters can be constructed using multiple -.Cm \e Ns Ar num -sequences. -.El -.Pp -Each format specification is introduced by the percent character -(``%''). -The remainder of the format specification includes, -in the following order: -.Bl -tag -width Ds -.It "Zero or more of the following flags:" -.Bl -tag -width Ds -.It Cm # -A `#' character -specifying that the value should be printed in an ``alternate form''. -For -.Cm b , c , d , s -and -.Cm u -formats, this option has no effect. -For the -.Cm o -formats the precision of the number is increased to force the first -character of the output string to a zero. -For the -.Cm x -.Pq Cm X -format, a non-zero result has the string -.Li 0x -.Pq Li 0X -prepended to it. -For -.Cm a , A , e , E , f , F , g -and -.Cm G -formats, the result will always contain a decimal point, even if no -digits follow the point (normally, a decimal point only appears in the -results of those formats if a digit follows the decimal point). -For -.Cm g -and -.Cm G -formats, trailing zeros are not removed from the result as they -would otherwise be; -.It Cm \&\- -A minus sign `\-' which specifies -.Em left adjustment -of the output in the indicated field; -.It Cm \&+ -A `+' character specifying that there should always be -a sign placed before the number when using signed formats. -.It Sq \&\ \& -A space specifying that a blank should be left before a positive number -for a signed format. -A `+' overrides a space if both are used; -.It Cm \&0 -A zero `0' character indicating that zero-padding should be used -rather than blank-padding. -A `\-' overrides a `0' if both are used; -.El -.It "Field Width:" -An optional digit string specifying a -.Em field width ; -if the output string has fewer bytes than the field width it will -be blank-padded on the left (or right, if the left-adjustment indicator -has been given) to make up the field width (note that a leading zero -is a flag, but an embedded zero is part of a field width); -.It Precision: -An optional period, -.Sq Cm \&.\& , -followed by an optional digit string giving a -.Em precision -which specifies the number of digits to appear after the decimal point, -for -.Cm e -and -.Cm f -formats, or the maximum number of bytes to be printed -from a string; if the digit string is missing, the precision is treated -as zero; -.It Format: -A character which indicates the type of format to use (one of -.Cm diouxXfFeEgGaAcsb ) . -The uppercase formats differ from their lowercase counterparts only in -that the output of the former is entirely in uppercase. -The floating-point format specifiers -.Pq Cm fFeEgGaA -may be prefixed by an -.Cm L -to request that additional precision be used, if available. -.El -.Pp -A field width or precision may be -.Sq Cm \&* -instead of a digit string. -In this case an -.Ar argument -supplies the field width or precision. -.Pp -The format characters and their meanings are: -.Bl -tag -width Fl -.It Cm diouXx -The -.Ar argument -is printed as a signed decimal (d or i), unsigned octal, unsigned decimal, -or unsigned hexadecimal (X or x), respectively. -.It Cm fF -The -.Ar argument -is printed in the style `[\-]ddd.ddd' where the number of d's -after the decimal point is equal to the precision specification for -the argument. -If the precision is missing, 6 digits are given; if the precision -is explicitly 0, no digits and no decimal point are printed. -The values \*[If] and \*[Na] are printed as -.Ql inf -and -.Ql nan , -respectively. -.It Cm eE -The -.Ar argument -is printed in the style -.Cm e -.Sm off -.Sq Op - Ar d.ddd No \(+- Ar dd -.Sm on -where there -is one digit before the decimal point and the number after is equal to -the precision specification for the argument; when the precision is -missing, 6 digits are produced. -The values \*[If] and \*[Na] are printed as -.Ql inf -and -.Ql nan , -respectively. -.It Cm gG -The -.Ar argument -is printed in style -.Cm f -.Pq Cm F -or in style -.Cm e -.Pq Cm E -whichever gives full precision in minimum space. -.It Cm aA -The -.Ar argument -is printed in style -.Sm off -.Sq Op - Ar h.hhh No \(+- Li p Ar d -.Sm on -where there is one digit before the hexadecimal point and the number -after is equal to the precision specification for the argument; -when the precision is missing, enough digits are produced to convey -the argument's exact double-precision floating-point representation. -The values \*[If] and \*[Na] are printed as -.Ql inf -and -.Ql nan , -respectively. -.It Cm c -The first byte of -.Ar argument -is printed. -.It Cm s -Bytes from the string -.Ar argument -are printed until the end is reached or until the number of bytes -indicated by the precision specification is reached; however if the -precision is 0 or missing, the string is printed entirely. -.It Cm b -As for -.Cm s , -but interpret character escapes in backslash notation in the string -.Ar argument . -The permitted escape sequences are slightly different in that -octal escapes are -.Cm \e0 Ns Ar num -instead of -.Cm \e Ns Ar num . -.It Cm n$ -Allows reordering of the output according to -.Ar argument . -.It Cm \&% -Print a `%'; no argument is used. -.El -.Pp -The decimal point -character is defined in the program's locale (category -.Dv LC_NUMERIC ) . -.Pp -In no case does a non-existent or small field width cause truncation of -a field; padding takes place only if the specified field width exceeds -the actual width. -.Pp -Some shells may provide a builtin -.Nm -command which is similar or identical to this utility. -Consult the -.Xr builtin 1 -manual page. -.Sh EXIT STATUS -.Ex -std -.Sh COMPATIBILITY -The traditional -.Bx -behavior of converting arguments of numeric formats not beginning -with a digit to the -.Tn ASCII -code of the first character is not supported. -.Sh SEE ALSO -.Xr builtin 1 , -.Xr echo 1 , -.Xr sh 1 , -.Xr printf 3 -.Sh STANDARDS -The -.Nm -command is expected to be compatible with the -.St -p1003.2 -specification. -.Sh HISTORY -The -.Nm -command appeared in -.Bx 4.3 Reno . -It is modeled -after the standard library function, -.Xr printf 3 . -.Sh CAVEATS -.Tn ANSI -hexadecimal character constants were deliberately not provided. -.Pp -Trying to print a dash ("-") as the first character causes -.Nm -to interpret the dash as a program argument. -.Nm -- -must be used before -.Ar format . -.Pp -If the locale contains multibyte characters -(such as UTF-8), -the -.Cm c -format and -.Cm b -and -.Cm s -formats with a precision -may not operate as expected. -.Sh BUGS -Since the floating point numbers are translated from -.Tn ASCII -to floating-point and -then back again, floating-point precision may be lost. -(By default, the number is translated to an IEEE-754 double-precision -value before being printed. -The -.Cm L -modifier may produce additional precision, depending on the hardware platform.) -.Pp -The escape sequence \e000 is the string terminator. -When present in the argument for the -.Cm b -format, the argument will be truncated at the \e000 character. -.Pp -Multibyte characters are not recognized in format strings (this is only -a problem if -.Ql % -can appear inside a multibyte character). -- cgit 1.4.1