Subversion Repositories planix.SVN

.TH PRINT 2

.SH NAME

print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint \- print formatted output

.SH SYNOPSIS

.B #include <u.h>

.br

.B #include <libc.h>

.PP

.ta \w'\fLchar* 'u

.B

int	print(char *format, ...)

.PP

.B

int	fprint(int fd, char *format, ...)

.PP

.B

int	sprint(char *s, char *format, ...)

.PP

.B

int	snprint(char *s, int len, char *format, ...)

.PP

.B

char*	seprint(char *s, char *e, char *format, ...)

.PP

.B

char*	smprint(char *format, ...)

.PP

.B

int	runesprint(Rune *s, char *format, ...)

.PP

.B

int	runesnprint(Rune *s, int len, char *format, ...)

.PP

.B

Rune*	runeseprint(Rune *s, Rune *e, char *format, ...)

.PP

.B

Rune*	runesmprint(char *format, ...)

.PP

.B

int	vfprint(int fd, char *format, va_list v)

.PP

.B

int	vsnprint(char *s, int len, char *format, va_list v)

.PP

.B

char*	vseprint(char *s, char *e, char *format, va_list v)

.PP

.B

char*	vsmprint(char *format, va_list v)

.PP

.B

int	runevsnprint(Rune *s, int len, char *format, va_list v)

.PP

.B

Rune*	runevseprint(Rune *s, Rune *e, char *format, va_list v)

.PP

.B

Rune*	runevsmprint(Rune *format, va_list v)

.PP

.B

.SH DESCRIPTION

.I Print

writes text to the standard output.

.I Fprint

writes to the named output

file descriptor;

a buffered form

is described in

.IR bio (2).

.I Sprint

places text

followed by the NUL character

.RB ( \e0 )

in consecutive bytes starting at

.IR s ;

it is the user's responsibility to ensure that

enough storage is available.

Each function returns the number of bytes

transmitted (not including the NUL

in the case of

.IR sprint ),

or

a negative value if an output error was encountered.

.PP

.I Snprint

is like

.IR sprint ,

but will not place more than

.I len

bytes in

.IR s .

Its result is always NUL-terminated and holds the maximal

number of complete UTF-8 characters that can fit.

.I Seprint

is like

.IR snprint ,

except that the end is indicated by a pointer

.I e

rather than a count and the return value points to the terminating NUL of the

resulting string.

.I Smprint

is like

.IR sprint ,

except that it prints into and returns a string of the required length, which is

allocated by

.IR malloc (2).

.PP

The routines

.IR runesprint ,

.IR runesnprint ,

.IR runeseprint ,

and

.I runesmprint

are the same as

.IR sprint ,

.IR snprint ,

.IR seprint

and

.I smprint

except that their output is rune strings instead of byte strings.

.PP

Finally, the routines

.IR vfprint ,

.IR vsnprint ,

.IR vseprint ,

.IR vsmprint ,

.IR runevsnprint ,

.IR runevseprint ,

and

.IR runevsmprint

are like their

.BR v-less

relatives except they take as arguments a

.B va_list

parameter, so they can be called within a variadic function.

The Example section shows a representative usage.

.PP

Each of these functions

converts, formats, and prints its

trailing arguments

under control of a

.IR format 

string.

The

format

contains two types of objects:

plain characters, which are simply copied to the

output stream,

and conversion specifications,

each of which results in fetching of

zero or more

arguments.

The results are undefined if there are arguments of the

wrong type or too few

arguments for the format.

If the format is exhausted while

arguments remain, the excess

is ignored.

.PP

Each conversion specification has the following format:

.IP

.B "% [flags] verb

.PP

The verb is a single character and each flag is a single character or a

(decimal) numeric string.

Up to two numeric strings may be used;

the first is called

.IR width ,

the second

.IR precision .

A period can be used to separate them, and if the period is

present then

.I width

and

.I precision

are taken to be zero if missing, otherwise they are `omitted'.

Either or both of the numbers may be replaced with the character

.BR * ,

meaning that the actual number will be obtained from the argument list

as an integer.

The flags and numbers are arguments to

the

.I verb

described below.

.PP

The numeric verbs

.BR d ,

.BR o ,

.BR b ,

.BR x ,

and

.B X

format their arguments in decimal,

octal, binary, hexadecimal, and upper case hexadecimal.

Each interprets the flags

.BR 0 ,

.BR h ,

.BR hh ,

.BR l ,

.BR u ,

.BR + ,

.BR - ,

.BR , ,

and

.B #

to mean pad with zeros,

short, byte, long, unsigned, always print a sign, left justified, commas every three digits,

and alternate format.

Also, a space character in the flag

position is like

.BR + ,

but prints a space instead of a plus sign for non-negative values.

If neither

short nor long is specified,

then the argument is an

.BR int .

If unsigned is specified,

then the argument is interpreted as a

positive number and no sign is output.

If two

.B l

flags are given,

then the argument is interpreted as a

.B vlong

(usually an 8-byte, sometimes a 4-byte integer).

If

.I precision

is not omitted, the number is padded on the left with zeros

until at least

.I precision

digits appear.

Then, if alternate format is specified,

for

.B o

conversion, the number is preceded by a

.B 0

if it doesn't already begin with one;

for

.B x

conversion, the number is preceded by

.BR 0x ;

for

.B X

conversion, the number is preceded by

.BR 0X .

Finally, if

.I width

is not omitted, the number is padded on the left (or right, if

left justification is specified) with enough blanks to

make the field at least

.I width

characters long.

.PP

The floating point verbs

.BR f ,

.BR e ,

.BR E ,

.BR g ,

and

.B G

take a

.B double

argument.

Each interprets the flags

.BR + ,

.BR - ,

and

.B #

to mean

always print a sign,

left justified,

and

alternate format.

.I Width

is the minimum field width and,

if the converted value takes up less than

.I width

characters, it is padded on the left (or right, if `left justified')

with spaces.

.I Precision

is the number of digits that are converted after the decimal place for

.BR e ,

.BR E ,

and

.B f

conversions,

and

.I precision

is the maximum number of significant digits for

.B g

and

.B G

conversions.

The 

.B f

verb produces output of the form

.RB [ - ] digits [ .digits\fR].

.B E

conversion appends an exponent

.BR E [ - ] digits ,

and

.B e

conversion appends an exponent

.BR e [ - ] digits .

The

.B g

verb will output the argument in either

.B e

or

.B f

with the goal of producing the smallest output.

Also, trailing zeros are omitted from the fraction part of

the output, and a trailing decimal point appears only if it is followed

by a digit.

The

.B G

verb is similar, but uses

.B E

format instead of

.BR e .

When alternate format is specified, the result will always contain a decimal point,

and for

.B g

and

.B G

conversions, trailing zeros are not removed.

.PP

The

.B s

verb copies a nul-terminated string

(pointer to

.BR char )

to the output.

The number of characters copied

.RI ( n )

is the minimum

of the size of the string and

.IR precision .

These

.I n

characters are justified within a field of

.I width

characters as described above.

If a

.I precision

is given, it is safe for the string not to be nul-terminated

as long as it is at least

.I precision

characters (not bytes!) long.

The

.B S

verb is similar, but it interprets its pointer as an array

of runes (see

.IR utf (6));

the runes are converted to

.SM UTF

before output.

.PP

The

.B c

verb copies a single

.B char

(promoted to

.BR int )

justified within a field of

.I width

characters as described above.

The

.B C

verb is similar, but works on runes.

.PP

The

.B p

verb formats a single pointer or pointer-sized integer

.RB ( uintptr ,

see

.IR intro (2))

in hexadecimal.

.PP

The

.B r

verb takes no arguments; it copies the error string returned by a call to

.IR errstr (2).

.PP

Custom verbs may be installed using

.IR fmtinstall (2).

.SH EXAMPLE

This function prints an error message with a variable

number of arguments and then quits.

.IP

.EX

.ta 6n +6n +6n

void fatal(char *msg, ...)

{

	char buf[1024], *out;

	va_list arg;

	out = seprint(buf, buf+sizeof(buf), "Fatal error: ");

	va_start(arg, msg);

	out = vseprint(out, buf+sizeof(buf), msg, arg);

	va_end(arg);

	write(2, buf, out-buf);

	exits("fatal error");

}

.EE

.SH SOURCE

.B /sys/src/libc/fmt

.SH SEE ALSO

.IR fmtinstall (2),

.IR fprintf (2),

.IR utf (6),

.IR errstr (2)

.SH DIAGNOSTICS

Routines that write to a file descriptor or call

.IR malloc

set

.IR errstr .

.SH BUGS

The formatting is close to that specified for ANSI

.IR fprintf (2);

the main difference is that

.B b

is not in ANSI and

.B u

is a flag here instead of a verb.

Also, and distinctly not a bug,

.I print

and friends generate

.SM UTF

rather than

.SM ASCII.

.PP

There is no

.BR runeprint ,

.BR runefprint ,

etc. because runes are byte-order dependent and should not be written directly to a file; use the

UTF output of

.I print

or

.I fprint

instead.

Also,

.I sprint

is deprecated for safety reasons; use

.IR snprint ,

.IR seprint ,

or

.I smprint

instead.

Safety also precludes the existence of

.IR runesprint .