[unix-history] / usr.bin / printf / printf.1

.\" Copyright (c) 1989, 1990 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. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. 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.
.\"
.\"	from: @(#)printf.1	5.11 (Berkeley) 7/24/91
.\"	$Id: printf.1,v 1.3 1993/11/05 20:12:38 jtc Exp $
.\"
.Dd November 5, 1993
.Dt PRINTF 1
.Os
.Sh NAME
.Nm printf
.Nd formatted output
.Sh SYNOPSIS
.Nm printf 
.Ar format
.Op Ar arguments  ...
.Sh DESCRIPTION
.Nm Printf
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 b ,
.Cm c
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 
.Tn ASCII
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 
.St -ansiC .
The characters and their meanings
are as follows:
.Bl -tag -width Ds -offset indent
.It Cm \ea
Write a <bell> character.
.It Cm \eb
Write a <backspace> character.
.It Cm \ef
Write a <form-feed> character.
.It Cm \en
Write a <new-line> character.
.It Cm \er
Write a <carriage return> character.
.It Cm \et
Write a <tab> character.
.It Cm \ev
Write a <vertical tab> character.
.It Cm \e\'
Write a <single quote> character.
.It Cm \e\e
Write a backslash character.
.It Cm \e Ns Ar num 
Write an 8-bit character whose
.Tn ASCII
value is the 1-, 2-, or 3-digit
octal number
.Ar num .
.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 c  ,
.Cm d ,
and
.Cm s  ,
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 e  ,
.Cm E ,
.Cm f  ,
.Cm 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 characters 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 characters 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 diouxXfwEgGbcs ) .
.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 decimal, unsigned octal,
or unsigned hexadecimal (X or x), respectively.
.It Cm f
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.
.It Cm eE
The
.Ar argument
is printed in the style
.Cm e
.`[-]d.ddd Ns \(+-dd\' 
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.
An upper-case E is used for an `E' format.
.It Cm gG
The
.Ar argument
is printed in style
.Cm f
or in style
.Cm e
.Pq Cm E
whichever gives full precision in minimum space.
.It Cm b
Characters from the string
.Ar argument
are printed with backslash-escape sequences expanded.
.It Cm c
The first character of
.Ar argument
is printed.
.It Cm s
Characters from the string
.Ar argument
are printed until the end is reached or until the number of characters
indicated by the precision specification is reached; however if the
precision is 0 or missing, all characters in the string are printed.
.It Cm \&%
Print a `%'; no argument is used.
.El
.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.
.Sh RETURN VALUES
.Nm Printf
exits 0 on success, 1 on failure.
.Sh SEE ALSO
.Xr echo 1 ,
.Xr printf 3
.Sh STANDARDS
The
.Nm printf
utility conforms to 
.St -p1003.2-92 .
.Sh BUGS
Since arguments are translated from
.Tn ASCII
to floating-point, and
then back again, floating-point precision may be lost.
Commit	Line	Data
15637ed4 RG	1	.\" Copyright (c) 1989, 1990 The Regents of the University of California.
	2	.\" All rights reserved.
	3	.\"
	4	.\" This code is derived from software contributed to Berkeley by
	5	.\" the Institute of Electrical and Electronics Engineers, Inc.
	6	.\"
	7	.\" Redistribution and use in source and binary forms, with or without
	8	.\" modification, are permitted provided that the following conditions
	9	.\" are met:
	10	.\" 1. Redistributions of source code must retain the above copyright
	11	.\" notice, this list of conditions and the following disclaimer.
	12	.\" 2. Redistributions in binary form must reproduce the above copyright
	13	.\" notice, this list of conditions and the following disclaimer in the
	14	.\" documentation and/or other materials provided with the distribution.
	15	.\" 3. All advertising materials mentioning features or use of this software
	16	.\" must display the following acknowledgement:
	17	.\" This product includes software developed by the University of
	18	.\" California, Berkeley and its contributors.
	19	.\" 4. Neither the name of the University nor the names of its contributors
	20	.\" may be used to endorse or promote products derived from this software
	21	.\" without specific prior written permission.
	22	.\"
	23	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	24	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	25	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	26	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	27	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	28	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	29	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	30	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	31	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	32	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	33	.\" SUCH DAMAGE.
	34	.\"
49b60b62 C	35	.\" from: @(#)printf.1 5.11 (Berkeley) 7/24/91
49b60b62 C	36	.\" $Id: printf.1,v 1.3 1993/11/05 20:12:38 jtc Exp $
15637ed4	37	.\"
49b60b62	38	.Dd November 5, 1993
15637ed4 RG	39	.Dt PRINTF 1
	40	.Os
	41	.Sh NAME
	42	.Nm printf
	43	.Nd formatted output
	44	.Sh SYNOPSIS
49b60b62 C	45	.Nm printf
	46	.Ar format
	47	.Op Ar arguments ...
15637ed4 RG	48	.Sh DESCRIPTION
	49	.Nm Printf
	50	formats and prints its arguments, after the first, under control
	51	of the
	52	.Ar format .
	53	The
	54	.Ar format
	55	is a character string which contains three types of objects: plain characters,
	56	which are simply copied to standard output, character escape sequences which
	57	are converted and copied to the standard output, and format specifications,
	58	each of which causes printing of the next successive
	59	.Ar argument .
	60	.Pp
	61	The
	62	.Ar arguments
	63	after the first are treated as strings if the corresponding format is
	64	either
49b60b62	65	.Cm b ,
15637ed4 RG	66	.Cm c
	67	or
	68	.Cm s ;
	69	otherwise it is evaluated as a C constant, with the following extensions:
	70	.Pp
	71	.Bl -bullet -offset indent -compact
	72	.It
	73	A leading plus or minus sign is allowed.
	74	.It
49b60b62 C	75	If the leading character is a single or double quote, the value is the
	76	.Tn ASCII
	77	code of the next character.
15637ed4 RG	78	.El
	79	.Pp
	80	The format string is reused as often as necessary to satisfy the
	81	.Ar arguments .
	82	Any extra format specifications are evaluated with zero or the null
	83	string.
	84	.Pp
49b60b62 C	85	Character escape sequences are in backslash notation as defined in
49b60b62 C	86	.St -ansiC .
15637ed4 RG	87	The characters and their meanings
	88	are as follows:
	89	.Bl -tag -width Ds -offset indent
	90	.It Cm \ea
	91	Write a <bell> character.
	92	.It Cm \eb
	93	Write a <backspace> character.
	94	.It Cm \ef
	95	Write a <form-feed> character.
	96	.It Cm \en
	97	Write a <new-line> character.
	98	.It Cm \er
	99	Write a <carriage return> character.
	100	.It Cm \et
	101	Write a <tab> character.
	102	.It Cm \ev
	103	Write a <vertical tab> character.
	104	.It Cm \e\'
	105	Write a <single quote> character.
	106	.It Cm \e\e
	107	Write a backslash character.
	108	.It Cm \e Ns Ar num
	109	Write an 8-bit character whose
	110	.Tn ASCII
	111	value is the 1-, 2-, or 3-digit
	112	octal number
	113	.Ar num .
	114	.El
	115	.Pp
	116	Each format specification is introduced by the percent character
	117	(``%'').
	118	The remainder of the format specification includes,
	119	in the following order:
	120	.Bl -tag -width Ds
	121	.It "Zero or more of the following flags:"
	122	.Bl -tag -width Ds
	123	.It Cm #
	124	A `#' character
	125	specifying that the value should be printed in an ``alternate form''.
	126	For
	127	.Cm c ,
	128	.Cm d ,
	129	and
	130	.Cm s ,
	131	formats, this option has no effect. For the
	132	.Cm o
	133	formats the precision of the number is increased to force the first
	134	character of the output string to a zero. For the
	135	.Cm x
	136	.Pq Cm X
	137	format, a non-zero result has the string
	138	.Li 0x
	139	.Pq Li 0X
	140	prepended to it. For
	141	.Cm e ,
	142	.Cm E ,
	143	.Cm f ,
	144	.Cm g ,
	145	and
	146	.Cm G ,
	147	formats, the result will always contain a decimal point, even if no
	148	digits follow the point (normally, a decimal point only appears in the
	149	results of those formats if a digit follows the decimal point). For
	150	.Cm g
151	and
152	.Cm G
153	formats, trailing zeros are not removed from the result as they
154	would otherwise be;
155	.It Cm \&\-
156	A minus sign `\-' which specifies
157	.Em left adjustment
158	of the output in the indicated field;
159	.It Cm \&+
160	A `+' character specifying that there should always be
161	a sign placed before the number when using signed formats.
162	.It Sq \&\ \&
163	A space specifying that a blank should be left before a positive number
164	for a signed format. A `+' overrides a space if both are used;
165	.It Cm \&0
166	A zero `0' character indicating that zero-padding should be used
167	rather than blank-padding. A `\-' overrides a `0' if both are used;
168	.El
169	.It "Field Width:"
170	An optional digit string specifying a
171	.Em field width ;
172	if the output string has fewer characters than the field width it will
173	be blank-padded on the left (or right, if the left-adjustment indicator
174	has been given) to make up the field width (note that a leading zero
175	is a flag, but an embedded zero is part of a field width);
176	.It Precision:
177	An optional period,
178	.Sq Cm \&.\& ,
179	followed by an optional digit string giving a
180	.Em precision
181	which specifies the number of digits to appear after the decimal point,
182	for
183	.Cm e
184	and
185	.Cm f
186	formats, or the maximum number of characters to be printed
187	from a string; if the digit string is missing, the precision is treated
188	as zero;
189	.It Format:
190	A character which indicates the type of format to use (one of
49b60b62	191	.Cm diouxXfwEgGbcs ) .
15637ed4 RG	192	.El
	193	.Pp
	194	A field width or precision may be
	195	.Sq Cm \&*
	196	instead of a digit string.
	197	In this case an
	198	.Ar argument
	199	supplies the field width or precision.
	200	.Pp
	201	The format characters and their meanings are:
	202	.Bl -tag -width Fl
	203	.It Cm diouXx
	204	The
	205	.Ar argument
	206	is printed as a signed decimal (d or i), unsigned decimal, unsigned octal,
	207	or unsigned hexadecimal (X or x), respectively.
	208	.It Cm f
	209	The
	210	.Ar argument
	211	is printed in the style `[\-]ddd.ddd' where the number of d's
	212	after the decimal point is equal to the precision specification for
	213	the argument.
	214	If the precision is missing, 6 digits are given; if the precision
	215	is explicitly 0, no digits and no decimal point are printed.
	216	.It Cm eE
	217	The
	218	.Ar argument
	219	is printed in the style
	220	.Cm e
	221	.`[-]d.ddd Ns \(+-dd\'
	222	where there
	223	is one digit before the decimal point and the number after is equal to
	224	the precision specification for the argument; when the precision is
	225	missing, 6 digits are produced.
	226	An upper-case E is used for an `E' format.
	227	.It Cm gG
	228	The
	229	.Ar argument
	230	is printed in style
	231	.Cm f
	232	or in style
	233	.Cm e
	234	.Pq Cm E
	235	whichever gives full precision in minimum space.
49b60b62 C	236	.It Cm b
	237	Characters from the string
	238	.Ar argument
	239	are printed with backslash-escape sequences expanded.
15637ed4 RG	240	.It Cm c
	241	The first character of
	242	.Ar argument
	243	is printed.
	244	.It Cm s
	245	Characters from the string
	246	.Ar argument
	247	are printed until the end is reached or until the number of characters
	248	indicated by the precision specification is reached; however if the
	249	precision is 0 or missing, all characters in the string are printed.
	250	.It Cm \&%
	251	Print a `%'; no argument is used.
	252	.El
	253	.Pp
	254	In no case does a non-existent or small field width cause truncation of
	255	a field; padding takes place only if the specified field width exceeds
	256	the actual width.
	257	.Sh RETURN VALUES
	258	.Nm Printf
	259	exits 0 on success, 1 on failure.
	260	.Sh SEE ALSO
49b60b62	261	.Xr echo 1 ,
15637ed4	262	.Xr printf 3
49b60b62	263	.Sh STANDARDS
15637ed4 RG	264	The
15637ed4 RG	265	.Nm printf
49b60b62 C	266	utility conforms to
49b60b62 C	267	.St -p1003.2-92 .
15637ed4	268	.Sh BUGS
49b60b62	269	Since arguments are translated from
15637ed4 RG	270	.Tn ASCII
	271	to floating-point, and
	272	then back again, floating-point precision may be lost.