print.3 3.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144
  1. .TH PRINT 3 "$Revision$"
  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 <varargs.h>
  9. .PP
  10. .B print(format [, arg] ... )
  11. .B char *format;
  12. .PP
  13. .B 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 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. This allows routines, e.g.
  110. .IR print ,
  111. to be defined as follows:
  112. .br
  113. .RS
  114. .nf
  115. #include <varargs.h>
  116. #include <system.h>
  117. /*VARARGS*/
  118. print(va_alist)
  119. va_dcl
  120. {
  121. char *fmt;
  122. va_list args;
  123. va_start(args);
  124. fmt = va_arg(args, char *);
  125. doprnt(STDOUT, fmt, args);
  126. va_end(args);
  127. }
  128. .fi
  129. .RE
  130. .SH FILES
  131. .nf
  132. ~em/modules/lib/libprint.a
  133. .fi
  134. .SH MODULES
  135. system(3), string(3)
  136. .SH DIAGNOSTICS
  137. .PP
  138. Each illegal conversion specification is replaced by the string "<bad\ format>".
  139. .SH BUGS
  140. The maximum length of the string to be printed is 1024 characters.
  141. .SH SEE ALSO
  142. printf(3)