summaryrefslogtreecommitdiffstats
path: root/upstream/mageia-cauldron/man1p/printf.1p
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--upstream/mageia-cauldron/man1p/printf.1p587
1 files changed, 587 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1p/printf.1p b/upstream/mageia-cauldron/man1p/printf.1p
new file mode 100644
index 00000000..410aaaee
--- /dev/null
+++ b/upstream/mageia-cauldron/man1p/printf.1p
@@ -0,0 +1,587 @@
+'\" et
+.TH PRINTF "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\"
+.SH PROLOG
+This manual page is part of the POSIX Programmer's Manual.
+The Linux implementation of this interface may differ (consult
+the corresponding Linux manual page for details of Linux behavior),
+or the interface may not be implemented on Linux.
+.\"
+.SH NAME
+printf
+\(em write formatted output
+.SH SYNOPSIS
+.LP
+.nf
+printf \fIformat\fB [\fIargument\fR...\fB]\fR
+.fi
+.SH DESCRIPTION
+The
+.IR printf
+utility shall write formatted operands to the standard output. The
+.IR argument
+operands shall be formatted under control of the
+.IR format
+operand.
+.SH OPTIONS
+None.
+.SH OPERANDS
+The following operands shall be supported:
+.IP "\fIformat\fR" 10
+A string describing the format to use to write the remaining operands.
+See the EXTENDED DESCRIPTION section.
+.IP "\fIargument\fR" 10
+The strings to be written to standard output, under the control of
+.IR format .
+See the EXTENDED DESCRIPTION section.
+.SH STDIN
+Not used.
+.SH "INPUT FILES"
+None.
+.SH "ENVIRONMENT VARIABLES"
+The following environment variables shall affect the execution of
+.IR printf :
+.IP "\fILANG\fP" 10
+Provide a default value for the internationalization variables that are
+unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
+.IR "Section 8.2" ", " "Internationalization Variables"
+the precedence of internationalization variables used to determine the
+values of locale categories.)
+.IP "\fILC_ALL\fP" 10
+If set to a non-empty string value, override the values of all the
+other internationalization variables.
+.IP "\fILC_CTYPE\fP" 10
+Determine the locale for the interpretation of sequences of bytes of
+text data as characters (for example, single-byte as opposed to
+multi-byte characters in arguments).
+.IP "\fILC_MESSAGES\fP" 10
+.br
+Determine the locale that should be used to affect the format and
+contents of diagnostic messages written to standard error.
+.IP "\fILC_NUMERIC\fP" 10
+.br
+Determine the locale for numeric formatting. It shall affect the
+format of numbers written using the
+.BR e ,
+.BR E ,
+.BR f ,
+.BR g ,
+and
+.BR G
+conversion specifier characters (if supported).
+.IP "\fINLSPATH\fP" 10
+Determine the location of message catalogs for the processing of
+.IR LC_MESSAGES .
+.SH "ASYNCHRONOUS EVENTS"
+Default.
+.SH STDOUT
+See the EXTENDED DESCRIPTION section.
+.SH STDERR
+The standard error shall be used only for diagnostic messages.
+.SH "OUTPUT FILES"
+None.
+.SH "EXTENDED DESCRIPTION"
+The
+.IR format
+operand shall be used as the
+.IR format
+string described in the Base Definitions volume of POSIX.1\(hy2017,
+.IR "Chapter 5" ", " "File Format Notation"
+with the following exceptions:
+.IP " 1." 4
+A
+<space>
+in the format string, in any context other than a flag of a conversion
+specification, shall be treated as an ordinary character that is copied
+to the output.
+.IP " 2." 4
+A
+.BR ' '
+character in the format string shall be treated as a
+.BR ' '
+character, not as a
+<space>.
+.IP " 3." 4
+In addition to the escape sequences shown in the Base Definitions volume of POSIX.1\(hy2017,
+.IR "Chapter 5" ", " "File Format Notation"
+(\c
+.BR '\e\e' ,
+.BR '\ea' ,
+.BR '\eb' ,
+.BR '\ef' ,
+.BR '\en' ,
+.BR '\er' ,
+.BR '\et' ,
+.BR '\ev' ),
+.BR \(dq\eddd\(dq ,
+where
+.IR ddd
+is a one, two, or three-digit octal number, shall be written as a byte
+with the numeric value specified by the octal number.
+.IP " 4." 4
+The implementation shall not precede or follow output from the
+.BR d
+or
+.BR u
+conversion specifiers with
+<blank>
+characters not specified by the
+.IR format
+operand.
+.IP " 5." 4
+The implementation shall not precede output from the
+.BR o
+conversion specifier with zeros not specified by the
+.IR format
+operand.
+.IP " 6." 4
+The
+.BR a ,
+.BR A ,
+.BR e ,
+.BR E ,
+.BR f ,
+.BR F ,
+.BR g ,
+and
+.BR G
+conversion specifiers need not be supported.
+.IP " 7." 4
+An additional conversion specifier character,
+.BR b ,
+shall be supported as follows. The argument shall be taken to be a
+string that can contain
+<backslash>-escape
+sequences. The following
+<backslash>-escape
+sequences shall be supported:
+.RS 4
+.IP -- 4
+The escape sequences listed in the Base Definitions volume of POSIX.1\(hy2017,
+.IR "Chapter 5" ", " "File Format Notation"
+(\c
+.BR '\e\e' ,
+.BR '\ea' ,
+.BR '\eb' ,
+.BR '\ef' ,
+.BR '\en' ,
+.BR '\er' ,
+.BR '\et' ,
+.BR '\ev' ),
+which shall be converted to the characters they represent
+.IP -- 4
+.BR \(dq\e0ddd\(dq ,
+where
+.IR ddd
+is a zero, one, two, or three-digit octal number that shall be
+converted to a byte with the numeric value specified by the octal
+number
+.IP -- 4
+.BR '\ec' ,
+which shall not be written and shall cause
+.IR printf
+to ignore any remaining characters in the string operand containing it,
+any remaining string operands, and any additional characters in the
+.IR format
+operand
+.P
+The interpretation of a
+<backslash>
+followed by any other sequence of characters is unspecified.
+.P
+Bytes from the converted string shall be written until the end of the
+string or the number of bytes indicated by the precision specification
+is reached. If the precision is omitted, it shall be taken to be
+infinite, so all bytes up to the end of the converted string shall be
+written.
+.RE
+.IP " 8." 4
+For each conversion specification that consumes an argument, the next
+.IR argument
+operand shall be evaluated and converted to the appropriate
+type for the conversion as specified below.
+.IP " 9." 4
+The
+.IR format
+operand shall be reused as often as necessary to satisfy the
+.IR argument
+operands. Any extra
+.BR b ,
+.BR c ,
+or
+.BR s
+conversion specifiers shall be evaluated as if a null string
+argument were supplied; other extra conversion specifications shall be
+evaluated as if a zero argument were supplied. If the
+.IR format
+operand contains no conversion specifications and
+.IR argument
+operands are present, the results are unspecified.
+.IP 10. 4
+If a character sequence in the
+.IR format
+operand begins with a
+.BR '%'
+character, but does not form a valid conversion specification, the
+behavior is unspecified.
+.IP 11. 4
+The argument to the
+.BR c
+conversion specifier can be a string containing zero or more bytes. If
+it contains one or more bytes, the first byte shall be written and any
+additional bytes shall be ignored. If the argument is an empty string,
+it is unspecified whether nothing is written or a null byte is written.
+.P
+The
+.IR argument
+operands shall be treated as strings if the corresponding conversion
+specifier is
+.BR b ,
+.BR c ,
+or
+.BR s ,
+and shall be evaluated as if by the
+\fIstrtod\fR()
+function if the corresponding conversion specifier is
+.BR a ,
+.BR A ,
+.BR e ,
+.BR E ,
+.BR f ,
+.BR F ,
+.BR g ,
+or
+.BR G .
+Otherwise, they shall be evaluated as unsuffixed C integer constants,
+as described by the ISO\ C standard, with the following extensions:
+.IP " *" 4
+A leading
+<plus-sign>
+or
+<hyphen-minus>
+shall be allowed.
+.IP " *" 4
+If the leading character is a single-quote or double-quote, the value
+shall be the numeric value in the underlying codeset of the character
+following the single-quote or double-quote.
+.IP " *" 4
+Suffixed integer constants may be allowed.
+.P
+If an
+.IR argument
+operand cannot be completely converted into an internal
+value appropriate to the corresponding conversion specification, a
+diagnostic message shall be written to standard error and the utility
+shall not exit with a zero exit status, but shall continue processing
+any remaining operands and shall write the value accumulated at the
+time the error was detected to standard output.
+.P
+It shall not be considered an error if an
+.IR argument
+operand is not completely used for a
+.BR b ,
+.BR c ,
+or
+.BR s
+conversion.
+.SH "EXIT STATUS"
+The following exit values shall be returned:
+.IP "\00" 6
+Successful completion.
+.IP >0 6
+An error occurred.
+.SH "CONSEQUENCES OF ERRORS"
+Default.
+.LP
+.IR "The following sections are informative."
+.SH "APPLICATION USAGE"
+The floating-point formatting conversion specifications of
+\fIprintf\fR()
+are not required because all arithmetic in the shell is integer
+arithmetic. The
+.IR awk
+utility performs floating-point calculations and provides its own
+.BR printf
+function. The
+.IR bc
+utility can perform arbitrary-precision floating-point arithmetic, but
+does not provide extensive formatting capabilities. (This
+.IR printf
+utility cannot really be used to format
+.IR bc
+output; it does not support arbitrary precision.) Implementations are
+encouraged to support the floating-point conversions as an extension.
+.P
+Note that this
+.IR printf
+utility, like the
+\fIprintf\fR()
+function defined in the System Interfaces volume of POSIX.1\(hy2017 on which it is based, makes no special
+provision for dealing with multi-byte characters when using the
+.BR %c
+conversion specification or when a precision is specified in a
+.BR %b
+or
+.BR %s
+conversion specification. Applications should be extremely cautious
+using either of these features when there are multi-byte characters in
+the character set.
+.P
+No provision is made in this volume of POSIX.1\(hy2017 which allows field widths and precisions
+to be specified as
+.BR '*'
+since the
+.BR '*'
+can be replaced directly in the
+.IR format
+operand using shell variable substitution. Implementations can also
+provide this feature as an extension if they so choose.
+.P
+Hexadecimal character constants as defined in the ISO\ C standard are not
+recognized in the
+.IR format
+operand because there is no consistent way to detect the end of the
+constant. Octal character constants are limited to, at most, three
+octal digits, but hexadecimal character constants are only terminated
+by a non-hex-digit character. In the ISO\ C standard, the
+.BR \(dq##\(dq
+concatenation operator can be used to terminate a constant and follow
+it with a hexadecimal character to be written. In the shell,
+concatenation occurs before the
+.IR printf
+utility has a chance to parse the end of the hexadecimal constant.
+.P
+The
+.BR %b
+conversion specification is not part of the ISO\ C standard; it has been added
+here as a portable way to process
+<backslash>-escapes
+expanded in string operands as provided by the
+.IR echo
+utility. See also the APPLICATION USAGE section of
+.IR "\fIecho\fR\^"
+for ways to use
+.IR printf
+as a replacement for all of the traditional versions of the
+.IR echo
+utility.
+.P
+If an argument cannot be parsed correctly for the corresponding
+conversion specification, the
+.IR printf
+utility is required to report an error. Thus, overflow and extraneous
+characters at the end of an argument being used for a numeric
+conversion shall be reported as errors.
+.SH EXAMPLES
+To alert the user and then print and read a series of prompts:
+.sp
+.RS 4
+.nf
+
+printf "\eaPlease fill in the following: \enName: "
+read name
+printf "Phone number: "
+read phone
+.fi
+.P
+.RE
+.P
+To read out a list of right and wrong answers from a file, calculate
+the percentage correctly, and print them out. The numbers are
+right-justified and separated by a single
+<tab>.
+The percentage is written to one decimal place of accuracy:
+.sp
+.RS 4
+.nf
+
+while read right wrong ; do
+ percent=$(echo "scale=1;($right*100)/($right+$wrong)" | bc)
+ printf "%2d right\et%2d wrong\et(%s%%)\en" \e
+ $right $wrong $percent
+done < database_file
+.fi
+.P
+.RE
+The command:
+.sp
+.RS 4
+.nf
+
+printf "%5d%4d\en" 1 21 321 4321 54321
+.fi
+.P
+.RE
+.P
+produces:
+.sp
+.RS 4
+.nf
+
+ 1 21
+ 3214321
+54321 0
+.fi
+.P
+.RE
+.P
+Note that the
+.IR format
+operand is used three times to print all of the given strings and that
+a
+.BR '0'
+was supplied by
+.IR printf
+to satisfy the last
+.BR %4d
+conversion specification.
+.P
+The
+.IR printf
+utility is required to notify the user when conversion errors are
+detected while producing numeric output; thus, the following results
+would be expected on an implementation with 32-bit twos-complement
+integers when
+.BR %d
+is specified as the
+.IR format
+operand:
+.br
+.TS
+center tab(@) box;
+cB | cB | cB
+cB | cB | cB
+lf5 | lf5 | lf7.
+@Standard
+Argument@Output@Diagnostic Output
+_
+5a@5@printf: "5a" not completely converted
+9999999999@2147483647@printf: "9999999999" arithmetic overflow
+\-9999999999@\-2147483648@printf: "\-9999999999" arithmetic overflow
+ABC@0@printf: "ABC" expected numeric value
+.TE
+.P
+The diagnostic message format is not specified, but these examples
+convey the type of information that should be reported. Note that the
+value shown on standard output is what would be expected as the return
+value from the
+\fIstrtol\fR()
+function as defined in the System Interfaces volume of POSIX.1\(hy2017. A similar correspondence exists
+between
+.BR %u
+and
+\fIstrtoul\fR()
+and
+.BR %e ,
+.BR %f ,
+and
+.BR %g
+(if the implementation supports floating-point conversions) and
+\fIstrtod\fR().
+.P
+In a locale using the ISO/IEC\ 646:\|1991 standard as the underlying codeset, the command:
+.sp
+.RS 4
+.nf
+
+printf "%d\en" 3 +3 -3 \e\(aq3 \e"+3 "\(aq-3"
+.fi
+.P
+.RE
+.P
+produces:
+.IP 3 6
+Numeric value of constant 3
+.IP 3 6
+Numeric value of constant 3
+.IP "\-3" 6
+Numeric value of constant \-3
+.IP 51 6
+Numeric value of the character
+.BR '3'
+in the ISO/IEC\ 646:\|1991 standard codeset
+.IP 43 6
+Numeric value of the character
+.BR '\(pl'
+in the ISO/IEC\ 646:\|1991 standard codeset
+.IP 45 6
+Numeric value of the character
+.BR '\-'
+in the ISO/IEC\ 646:\|1991 standard codeset
+.P
+Note that in a locale with multi-byte characters, the value of a
+character is intended to be the value of the equivalent of the
+.BR wchar_t
+representation of the character as described in the System Interfaces volume of POSIX.1\(hy2017.
+.SH RATIONALE
+The
+.IR printf
+utility was added to provide functionality that has historically been
+provided by
+.IR echo .
+However, due to irreconcilable differences in the various versions of
+.IR echo
+extant, the version has few special features, leaving those to this new
+.IR printf
+utility, which is based on one in the Ninth Edition system.
+.P
+The EXTENDED DESCRIPTION section almost exactly matches the
+\fIprintf\fR()
+function in the ISO\ C standard, although it is described in terms of the file
+format notation in the Base Definitions volume of POSIX.1\(hy2017,
+.IR "Chapter 5" ", " "File Format Notation".
+.P
+Earlier versions of this standard specified that arguments for all
+conversions other than
+.BR b ,
+.BR c ,
+and
+.BR s
+were evaluated in the same way (as C constants, but with stated
+exceptions). For implementations supporting the floating-point conversions
+it was not clear whether integer conversions need only accept integer
+constants and floating-point conversions need only accept floating-point
+constants, or whether both types of conversions should accept both
+types of constants. Also by not distinguishing between them, the
+requirement relating to a leading single-quote or double-quote applied
+to floating-point conversions even though this provided no useful
+functionality to applications that was not already available through
+the integer conversions. The current standard clarifies the situation
+by specifying that the arguments for floating-point conversions are
+evaluated as if by
+\fIstrtod\fR(),
+and the arguments for integer conversions are evaluated as C integer
+constants, with the special treatment of leading single-quote and
+double-quote applying only to integer conversions.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "\fIawk\fR\^",
+.IR "\fIbc\fR\^",
+.IR "\fIecho\fR\^"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "Chapter 5" ", " "File Format Notation",
+.IR "Chapter 8" ", " "Environment Variables"
+.P
+The System Interfaces volume of POSIX.1\(hy2017,
+.IR "\fIfprintf\fR\^(\|)",
+.IR "\fIstrtod\fR\^(\|)"
+.\"
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1-2017, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 7, 2018 Edition,
+Copyright (C) 2018 by the Institute of
+Electrical and Electronics Engineers, Inc and The Open Group.
+In the event of any discrepancy between this version and the original IEEE and
+The Open Group Standard, the original IEEE and The Open Group Standard
+is the referee document. The original Standard can be obtained online at
+http://www.opengroup.org/unix/online.html .
+.PP
+Any typographical or formatting errors that appear
+in this page are most likely
+to have been introduced during the conversion of the source files to
+man page format. To report such errors, see
+https://www.kernel.org/doc/man-pages/reporting_bugs.html .
generated by cgit v1.2.3 (git 2.39.1) at 2025-02-11 09:43:21 +0000