Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PRINT(3)		   Library Functions Manual		      PRINT(3)

NAME
       print,  fprint,	sprint,	 snprint, seprint, smprint, runesprint,	runes-
       nprint, runeseprint, runesmprint,  vfprint,  vsnprint,  vseprint,  vsm-
       print,  runevsnprint, runevseprint, runevsmprint	- print	formatted out-
       put

SYNOPSIS
       #include	<u.h>

       #include	<libc.h>

       int   print(char	*format, ...)

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

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

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

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

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

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

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

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

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

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

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

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

       char* vsmprint(char *format, va_list v)

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

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

       Rune* runevsmprint(Rune *format,	va_list	v)

DESCRIPTION
       Print writes text to the	standard output.  Fprint writes	to  the	 named
       output file descriptor: a buffered form is described in bio(3).	Sprint
       places text followed by the NUL character  (\0)	in  consecutive	 bytes
       starting	 at  s;	 it is the user's responsibility to ensure that	enough
       storage is available.  Each function returns the	number of bytes	trans-
       mitted  (not  including	the  NUL in the	case of	sprint), or a negative
       value if	an output error	was encountered.

       Snprint is like sprint, but will	not place more than len	 bytes	in  s.
       Its  result  is	always	NUL-terminated and holds the maximal number of
       complete	UTF-8 characters that can fit.	Seprint	is like	 snprint,  ex-
       cept  that  the end is indicated	by a pointer e rather than a count and
       the return value	points to the terminating NUL of the resulting string.
       Smprint is like sprint, except that it prints into and returns a	string
       of the required length, which is	allocated by malloc(3).

       The routines runesprint,	runesnprint, runeseprint, and runesmprint  are
       the same	as sprint, snprint, seprint and	smprint	except that their out-
       put is rune strings instead of byte strings.  They return a rune	 count
       rather than a byte count.

       Finally,	 the  routines	vfprint, vsnprint, vseprint, vsmprint, runevs-
       nprint, runevseprint, and runevsmprint are like their v-less  relatives
       except  they  take  as  arguments  a  va_list parameter,	so they	can be
       called within a variadic	function.  The Example section shows a	repre-
       sentative usage.

       Each  of	these functions	converts, formats, and prints its trailing ar-
       guments under control of	a format  string.   The	 format	 contains  two
       types of	objects: plain characters, which are simply copied to the out-
       put 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 ig-
       nored.

       Each conversion specification has the following format:

	      %	[flags]	verb

       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 width, the second precision.  A period can be  used  to
       separate	 them,	and  if	the period is present then width and precision
       are taken to be zero if missing,	otherwise they are `omitted'.	Either
       or  both	 of  the numbers may be	replaced with the character *, meaning
       that the	actual number will be obtained from the	argument  list	as  an
       integer.	 The flags and numbers are arguments to	the verb described be-
       low.

       The numeric verbs d, o, b, x, and X format their	arguments in  decimal,
       octal,  binary,	hexadecimal,  and upper	case hexadecimal.  Each	inter-
       prets the flags 0, h, hh, l, u, +, -, ,,	and # to mean pad with	zeros,
       short,  byte, long, unsigned, always print a sign, left justified, com-
       mas every three digits, and alternate format.  Also, a space  character
       in  the	flag  position is like +, 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	int.  If unsigned is specified,	then the argu-
       ment is interpreted as a	positive number	and no sign is output.	If two
       l flags are given, then the argument is interpreted as a	vlong (usually
       an 8-byte, sometimes a 4-byte integer).	If precision is	 not  omitted,
       the  number  is	padded on the left with	zeros until at least precision
       digits appear.  If precision is explicitly 0, and the number is	0,  no
       digits  are  generated, and alternate formatting	does not apply.	 Then,
       if alternate format is specified, for o conversion, the number is  pre-
       ceded  by  a  0 if it doesn't already begin with	one; for x conversion,
       the number is preceded by 0x; for X conversion, the number is  preceded
       by  0X.	 Finally, if 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 width	characters long.

       The  floating  point  verbs  f,	e, E, g, and G take a double argument.
       Each interprets the flags 0, L +, -, and	# to mean pad with zeros, long
       double  argument,  always  print	 a sign, left justified, and alternate
       format.	Width is the minimum field width and, if the  converted	 value
       takes  up  less	than  width  characters,  it is	padded on the left (or
       right, if `left justified') with	spaces.	 Precision is  the  number  of
       digits  that are	converted after	the decimal place for e, E, and	f con-
       versions, and precision is the maximum number of	significant digits for
       g  and  G  conversions.	The f verb produces output of the form [-]dig-
       its[.digits].  E	conversion appends an exponent E[-]digits, and e  con-
       version appends an exponent e[-]digits.	The g verb will	output the ar-
       gument in either	e or 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  G verb is similar, but uses	E format instead of e.	When alternate
       format is specified, the	result will always contain  a  decimal	point,
       and for g and G conversions, trailing zeros are not removed.

       The s verb copies a NUL-terminated string (pointer to char) to the out-
       put.  The number	of characters copied (n) is the	minimum	of the size of
       the  string  and	 precision.  These n characters	are justified within a
       field of	width characters as described above.  If a precision is	given,
       it  is safe for the string not to be nul-terminated as long as it is at
       least precision characters (not bytes!) long.  The S verb  is  similar,
       but  it	interprets  its	pointer	as an array of runes (see utf(7)); the
       runes are converted to UTF before output.

       The c verb copies a single char (promoted to int)  justified  within  a
       field  of  width	characters as described	above.	The C verb is similar,
       but works on runes.

       The p verb formats a pointer value.  At the moment, it is a synonym for
       x, but that will	change if pointers and integers	are different sizes.

       The r verb takes	no arguments; it copies	the error string returned by a
       call to errstr(3).

       Custom verbs may	be installed using fmtinstall(3).

EXAMPLE
       This function prints an error message with a variable number  of	 argu-
       ments and then quits.

	      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");
	      }

SOURCE
       /usr/local/plan9/src/lib9/fmt

SEE ALSO
       fmtinstall(3), fprintf(3), utf(7)

DIAGNOSTICS
       Routines	that write to a	file descriptor	or call	malloc set errstr.

BUGS
       The formatting is close to that specified for ANSI fprintf(3); the main
       difference is that b and	r are not in ANSI and u	is a flag here instead
       of  a verb.  Also, and distinctly not a bug, print and friends generate
       UTF rather than ASCII.

       There is	no runeprint, runefprint, etc. because	runes  are  byte-order
       dependent  and  should  not  be written directly	to a file; use the UTF
       output of print or fprint instead.   Also,  sprint  is  deprecated  for
       safety  reasons;	use snprint, seprint, or smprint instead.  Safety also
       precludes the existence of runesprint.

								      PRINT(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | SOURCE | SEE ALSO | DIAGNOSTICS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=print&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help