libs/src/sio/Sprint.3

   1 .\"(c) Copyright 1992, 1993 by Panagiotis Tsirigotis
   2 .\"All rights reserved.  The file named COPYRIGHT specifies the terms
   3 .\"and conditions for redistribution.
   4 .\"
   5 .\" $Id: Sprint.3,v 1.1.1.1 2003/02/19 17:29:27 bbraun Exp $
   6 .TH Sprint 3X "29 May 1992"
   7 .SH NAME
   8 Sprint -- formatted stream output
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 .ft B
  13 int Sprint( fd, format [ , ... ] )
  14 int fd ;
  15 char *format ;
  16 .SH DESCRIPTION
  17 \fBSprint()\fR provides formatted output conversion. The formatting is
  18 controlled by the \fIformat\fR argument. All characters in
  19 \fIformat\fR that do not specify a conversion are printed. A conversion
  20 is specified by a '%' followed by a string that ends with a
  21 conversion type character. The string may contain flags, a field width,
  22 a precision, and a modifier.
  23 .LP
  24 Possible flags (more that one can be specified and they can be in any order)
  25 include:
  26 .TP 10
  27 .B \'-'
  28 specifies left adjustment of the converted argument. The default
  29 is right adjustment. This flag is meaningful only if a field width
  30 is specified.
  31 .TP
  32 .B \'+'
  33 specifies that a number will always have a sign as a prefix (this
  34 forces a '+' sign to appear if the number is positive).
  35 .TP
  36 .B \' '
  37 prefixes a \fIspace\fR to the number if the number has not a sign
  38 (therefore the '+' flag overrides this flag).
  39 .TP
  40 .B \'#'
  41 The meaning of '#' depends on the conversion type character: for \fBo\fR
  42 conversions the first digit will be 0; for \fBx\fR or \fBX\fR conversions
  43 \fB0x\fR or \fB0X\fR respectively will be prefixed to the number (if it
  44 is not zero); for \fBe\fR, \fBE\fR, \fBf\fR, \fBg\fR, and \fBG\fR conversions
  45 the number will always have a decimal point.
  46 .TP
  47 .B \'0'
  48 specifies padding with zeros instead of spaces.
  49 .LP
  50 The field width is specified by a number. This number indicates the
  51 \fIminimum\fR width for the field. A '*' may be used instead of the number.
  52 In that case the width is the value of the next argument which should
  53 be an \fBint\fR.
  54 A negative width value specifies left adjustment with a width equal
  55 to the absolute width value.
  56 .LP
  57 A precision is specified by a '.' followed by a number. The meaning of
  58 the precision depends on the type conversion character. For a string
  59 conversion, precision determines how many characters are printed from
  60 the string. For integer conversions, precision determines the
  61 number of digits used to print the number (zero padding is done if
  62 the precision exceeds the length of the number). For floating point
  63 conversions, precision determines the number of digits after the
  64 decimal point (\fBe\fR, \fBE\fR, \fBf\fR) or the number of
  65 significant digits (\fBg\fR, \fBG\fR).
  66 A '*' may be used instead of a number to specify the precision. In that
  67 case the precision is the value of the next argument which should
  68 be an \fBint\fR.
  69 The behavior of \fBSprint()\fR is undefined if the precision is negative.
  70 .LP
  71 The length modifier is \fBl\fR and indicates that the argument is
  72 a \fBlong\fR integer.
  73 .LP
  74 The type conversion characters are:
  75 \fBd, i, o, x, X, u, c, s, f, e, E, g, G, p, n, %\fR.
  76 For floating point conversions the argument should be of type \fIdouble\fR.
  77 .TP 10
  78 .B d,i
  79 specify signed decimal conversion.
  80 .TP
  81 .B u
  82 specifies unsigned decimal conversion.
  83 .TP
  84 .B o
  85 specifies octal conversion.
  86 .TP
  87 .B x,X
  88 specify hexadecimal conversion. For
  89 .B x
  90 the hex digits used are 0123456789abcdef. For
  91 .B X
  92 the hex digits used are 0123456789ABCDEF.
  93 There is no leading
  94 .B 0x
  95 or
  96 .B 0X
  97 (use the '#' flag for that).
  98 .TP
  99 .B c
 100 specifies character conversion; the argument should be of type
 101 \fIchar\fR.
 102 .TP
 103 .B s
 104 specifies string conversion; the argument should be of type
 105 \fIchar *\fR.
 106 .TP
 107 .B f
 108 specifies conversion to the form [-]ddd.dddd. The number
 109 of digits after the decimal point depends on precision; the default is 6.
 110 If the precision is 0, the decimal point is not printed (this can
 111 be overriden with the '#' flag).
 112 .B e,E
 113 specify conversion to the form [-]ddd.dddd[eE][+-]ddd.
 114 The number of digits after the decimal point depends on precision;
 115 the default is 6. If the precision is 0, the decimal point is not printed
 116 (this can be overriden with the '#' flag).
 117 The exponent is at least 2 digit wide.
 118 .TP
 119 .B g,G
 120 specify a conversion using the
 121 .B e,E
 122 format respectively if the
 123 exponent is less than -4 or greater than or equal to the precision;
 124 otherwise the
 125 .B f
 126 format is used.
 127 .TP
 128 .B p
 129 is used to print pointers (type \fIvoid *\fR,
 130 or \fIchar *\fR if the compiler does not support the former).
 131 .TP
 132 .B n
 133 expects a \fIint *\fR argument and puts in that integer
 134 the number of characters already printed by this call.
 135 .TP
 136 .B %
 137 is used to print a \fI%\fR.
 138 .LP
 139 If an unknown conversion character is specified, the percent sign
 140 followed by that character will be printed.
 141 .SH RETURN VALUE
 142 .LP
 143 If no error occured, \fBSprint()\fR returns the number of characters
 144 printed. In case of error, it returns \fBSIO_ERR\fR.
 145 .SH BUGS
 146 .LP
 147 This is a list of differences between \fBSprint()\fR and the ANSI C Standard
 148 \fBprintf()\fR:
 149 .LP
 150 \fBSprint()\fR does not support non-removal of trailing zeroes for
 151 \fBg\fR and \fBG\fR conversions when the '#' flag is used.
 152 .LP
 153 \fBSprint()\fR does not support the h and L modifiers.
 154 .LP
 155 The current implementation assumes that \fIsizeof(int)==sizeof(long)\fR.
 156 .LP
 157 \fBSprint()\fR supports "%p" only if \fIsizeof(pointer)<=sizeof(int)\fR.