modules/src/print/print.3

   1 .TH PRINT 3 "$Revision: 1.9 $"
   2 .ad
   3 .SH NAME
   4 print, fprint, sprint, doprnt -- very simple formatted-output routines
   5 .SH SYNOPSIS
   6 .nf
   7 .B #include <system.h>
   8 .B #include <print.h>
   9 .PP
  10 .B void print(format [, arg] ... )
  11 .B char *format;
  12 .PP
  13 .B void fprint(filep, format [, arg] ... )
  14 .B File *filep;
  15 .B char *format;
  16 .PP
  17 .B char *sprint(s, format [, arg] ... )
  18 .B char *s, *format;
  19 .PP
  20 .B void doprnt(filep, format, args)
  21 .B File *filep;
  22 .B char *format;
  23 .B va_list args;
  24 .PP
  25 .B int _format(buf, format, args)
  26 .B char *buf;
  27 .B char *format;
  28 .B va_list args;
  29 .fi
  30 .SH DESCRIPTION
  31 .I Print
  32 writes output on standard output.
  33 .I Fprint
  34 and
  35 .I doprnt
  36 place output on the open file known by
  37 .IR filep .
  38 .I filep could for instance be STDOUT or STDERR.
  39 .I Sprint
  40 places `output' in the string
  41 .IR s ,
  42 followed by the character `\\0'.
  43 .PP
  44 Each of these functions converts, formats and prints its arguments, following
  45 the
  46 .I format
  47 argument, under control of
  48 .IR format .
  49 .I Format
  50 is a character string which contains two types of objects: plain characters,
  51 which are simply copied to the output destination, and conversion
  52 specifications, each of which causes conversion and printing of the next
  53 successive argument.
  54 .PP
  55 A conversion specification is introduced by the character %.
  56 Following the %, there may be
  57 .IP \(bu
  58 an optional row of decimal digits specifying the field width;
  59 if the converted integral value has fewer characters than
  60 the field width, it will be blank-padded on the left;
  61 if the field width begins with a zero, zero-padding will be done;
  62 .IP \(bu
  63 the character
  64 .B l
  65 specifying that a following
  66 .BR b ,
  67 .BR d ,
  68 .BR o ,
  69 .B u
  70 or
  71 .B x
  72 corresponds to a long-integer argument;
  73 .IP \(bu
  74 a character which indicates the type of conversion to be applied.
  75 .LP
  76 .PP
  77 The conversion characters and their meanings are
  78 .IP \fBbdox\fP
  79 The next argument is an integer and is converted to binary, decimal, octal
  80 or hexadecimal notation respectively.
  81 .IP \fBc\fP
  82 Next argument is a character and is put directly into the resulting string.
  83 the field width is one character.
  84 .IP \fBs\fP
  85 Next argument is taken to be a character pointer and characters from the
  86 string are taken until a null character is reached; a specified field width
  87 is not taken into account.
  88 .IP \fBu\fP
  89 The unsigned integer argument is converted to decimal.
  90 .LP
  91 .PP
  92 Integral arguments are not truncated, even if their size exceeds the specified
  93 field width.
  94 Padding takes place only if the specified field width exceeds the actual width.
  95 .PP
  96 The printing routines build the string to be printed internally and use
  97 .I sys_write
  98 to print it.
  99 .PP
 100 The
 101 .I _format
 102 routine builds the string, but does not null-terminate it. It returns the
 103 length of the string.
 104 .PP
 105 .I Doprnt
 106 takes
 107 .I args
 108 as the address of the arguments of the format string.
 109 .SH FILES
 110 .nf
 111 ~em/modules/lib/libprint.a
 112 .fi
 113 .SH MODULES
 114 system(3), string(3)
 115 .SH DIAGNOSTICS
 116 .PP
 117 Each illegal conversion specification is replaced by the string "<bad\ format>".
 118 .SH BUGS
 119 The maximum length of the string to be printed is 1024 characters.
 120 .SH SEE ALSO
 121 printf(3)