fmtinstall 7.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373
  1. .TH FMTINSTALL 2
  2. .SH NAME
  3. fmtinstall, dofmt, dorfmt, fmtprint, fmtvprint, fmtrune, fmtstrcpy, fmtrunestrcpy, fmtfdinit, fmtfdflush, fmtstrinit, fmtstrflush, runefmtstrinit, runefmtstrflush, errfmt \- support for user-defined print formats and output routines
  4. .SH SYNOPSIS
  5. .B #include <u.h>
  6. .br
  7. .B #include <libc.h>
  8. .PP
  9. .ft L
  10. .nf
  11. .ta \w' 'u +\w' 'u +\w' 'u +\w' 'u +\w' 'u
  12. typedef struct Fmt Fmt;
  13. struct Fmt{
  14. uchar runes; /* output buffer is runes or chars? */
  15. void *start; /* of buffer */
  16. void *to; /* current place in the buffer */
  17. void *stop; /* end of the buffer; overwritten if flush fails */
  18. int (*flush)(Fmt*); /* called when to == stop */
  19. void *farg; /* to make flush a closure */
  20. int nfmt; /* num chars formatted so far */
  21. va_list args; /* args passed to dofmt */
  22. int r; /* % format Rune */
  23. int width;
  24. int prec;
  25. ulong flags;
  26. };
  27. enum{
  28. FmtWidth = 1,
  29. FmtLeft = FmtWidth << 1,
  30. FmtPrec = FmtLeft << 1,
  31. FmtSharp = FmtPrec << 1,
  32. FmtSpace = FmtSharp << 1,
  33. FmtSign = FmtSpace << 1,
  34. FmtZero = FmtSign << 1,
  35. FmtUnsigned = FmtZero << 1,
  36. FmtShort = FmtUnsigned << 1,
  37. FmtLong = FmtShort << 1,
  38. FmtVLong = FmtLong << 1,
  39. FmtComma = FmtVLong << 1,
  40. FmtFlag = FmtComma << 1
  41. };
  42. .fi
  43. .PP
  44. .B
  45. .ta \w'\fLchar* 'u
  46. .PP
  47. .B
  48. int fmtfdinit(Fmt *f, int fd, char *buf, int nbuf);
  49. .PP
  50. .B
  51. int fmtfdflush(Fmt *f);
  52. .PP
  53. .B
  54. int fmtstrinit(Fmt *f);
  55. .PP
  56. .B
  57. char* fmtstrflush(Fmt *f);
  58. .PP
  59. .B
  60. int runefmtstrinit(Fmt *f);
  61. .PP
  62. .B
  63. Rune* runefmtstrflush(Fmt *f);
  64. .PP
  65. .B
  66. int fmtinstall(int c, int (*fn)(Fmt*));
  67. .PP
  68. .B
  69. int dofmt(Fmt *f, char *fmt);
  70. .PP
  71. .B
  72. int dorfmt(Fmt*, Rune *fmt);
  73. .PP
  74. .B
  75. int fmtprint(Fmt *f, char *fmt, ...);
  76. .PP
  77. .B
  78. int fmtvprint(Fmt *f, char *fmt, va_list v);
  79. .PP
  80. .B
  81. int fmtrune(Fmt *f, int r);
  82. .PP
  83. .B
  84. int fmtstrcpy(Fmt *f, char *s);
  85. .PP
  86. .B
  87. int fmtrunestrcpy(Fmt *f, Rune *s);
  88. .PP
  89. .B
  90. int errfmt(Fmt *f);
  91. .SH DESCRIPTION
  92. The interface described here allows the construction of custom
  93. .IR print (2)
  94. verbs and output routines.
  95. In essence, they provide access to the workings of the formatted print code.
  96. .PP
  97. The
  98. .IR print (2)
  99. suite maintains its state with a data structure called
  100. .BR Fmt .
  101. A typical call to
  102. .IR print (2)
  103. or its relatives initializes a
  104. .B Fmt
  105. structure, passes it to subsidiary routines to process the output,
  106. and finishes by emitting any saved state recorded in the
  107. .BR Fmt .
  108. The details of the
  109. .B Fmt
  110. are unimportant to outside users, except insofar as the general
  111. design influences the interface.
  112. The
  113. .B Fmt
  114. records whether the output is in runes or bytes,
  115. the verb being processed, its precision and width,
  116. and buffering parameters.
  117. Most important, it also records a
  118. .I flush
  119. routine that the library will call if a buffer overflows.
  120. When printing to a file descriptor, the flush routine will
  121. emit saved characters and reset the buffer; when printing
  122. to an allocated string, it will resize the string to receive more output.
  123. The flush routine is nil when printing to fixed-size buffers.
  124. User code need never provide a flush routine; this is done internally
  125. by the library.
  126. .SS Custom output routines
  127. To write a custom output routine, such as an error handler that
  128. formats and prints custom error messages, the output sequence can be run
  129. from outside the library using the routines described here.
  130. There are two main cases: output to an open file descriptor
  131. and output to a string.
  132. .PP
  133. To write to a file descriptor, call
  134. .I fmtfdinit
  135. to initialize the local
  136. .B Fmt
  137. structure
  138. .IR f ,
  139. giving the file descriptor
  140. .IR fd ,
  141. the buffer
  142. .IR buf ,
  143. and its size
  144. .IR nbuf .
  145. Then call
  146. .IR fmtprint
  147. or
  148. .IR fmtvprint
  149. to generate the output.
  150. These behave like
  151. .B fprint
  152. (see
  153. .IR print (2))
  154. or
  155. .B vfprint
  156. except that the characters are buffered until
  157. .I fmtfdflush
  158. is called and the return value is either 0 or \-1.
  159. A typical example of this sequence appears in the Examples section.
  160. .PP
  161. The same basic sequence applies when outputting to an allocated string:
  162. call
  163. .I fmtstrinit
  164. to initialize the
  165. .BR Fmt ,
  166. then call
  167. .I fmtprint
  168. and
  169. .I fmtvprint
  170. to generate the output.
  171. Finally,
  172. .I fmtstrflush
  173. will return the allocated string, which should be freed after use.
  174. To output to a rune string, use
  175. .I runefmtstrinit
  176. and
  177. .IR runefmtstrflush .
  178. Regardless of the output style or type,
  179. .I fmtprint
  180. or
  181. .I fmtvprint
  182. generates the characters.
  183. .SS Custom format verbs
  184. .I Fmtinstall
  185. is used to install custom verbs and flags labeled by character
  186. .IR c ,
  187. which may be any non-zero Unicode character.
  188. .I Fn
  189. should be declared as
  190. .IP
  191. .EX
  192. int fn(Fmt*)
  193. .EE
  194. .PP
  195. .IB Fp ->r
  196. is the flag or verb character to cause
  197. .I fn
  198. to be called.
  199. In
  200. .IR fn ,
  201. .IB fp ->width ,
  202. .IB fp ->prec
  203. are the width and precision, and
  204. .IB fp ->flags
  205. the decoded flags for the verb (see
  206. .IR print (2)
  207. for a description of these items).
  208. The standard flag values are:
  209. .B FmtSign
  210. .RB ( + ),
  211. .B FmtLeft
  212. .RB ( - ),
  213. .B FmtSpace
  214. .RB ( '\ ' ),
  215. .B FmtSharp
  216. .RB ( # ),
  217. .B FmtComma
  218. .RB ( , ),
  219. .B FmtLong
  220. .RB ( l ),
  221. .B FmtShort
  222. .RB ( h ),
  223. .B FmtUnsigned
  224. .RB ( u ),
  225. and
  226. .B FmtVLong
  227. .RB ( ll ).
  228. The flag bits
  229. .B FmtWidth
  230. and
  231. .B FmtPrec
  232. identify whether a width and precision were specified.
  233. .PP
  234. .I Fn
  235. is passed a pointer to the
  236. .B Fmt
  237. structure recording the state of the output.
  238. If
  239. .IB fp ->r
  240. is a verb (rather than a flag),
  241. .I fn
  242. should use
  243. .B Fmt->args
  244. to fetch its argument from the list,
  245. then format it, and return zero.
  246. If
  247. .IB fp ->r
  248. is a flag,
  249. .I fn
  250. should return one.
  251. All interpretation of
  252. .IB fp ->width\f1,
  253. .IB fp ->prec\f1,
  254. and
  255. .IB fp-> flags
  256. is left up to the conversion routine.
  257. .I Fmtinstall
  258. returns 0 if the installation succeeds, \-1 if it fails.
  259. .PP
  260. .IR Fmtprint
  261. and
  262. .IR fmtvprint
  263. may be called to
  264. help prepare output in custom conversion routines.
  265. However, these functions clear the width, precision, and flags.
  266. Both functions return 0 for success and \-1 for failure.
  267. .PP
  268. The functions
  269. .I dofmt
  270. and
  271. .I dorfmt
  272. are the underlying formatters; they
  273. use the existing contents of
  274. .B Fmt
  275. and should be called only by sophisticated conversion routines.
  276. These routines return the number of characters (bytes of UTF or runes)
  277. produced.
  278. .PP
  279. Some internal functions may be useful to format primitive types.
  280. They honor the width, precision and flags as described in
  281. .IR print (2).
  282. .I Fmtrune
  283. formats a single character
  284. .BR r .
  285. .I Fmtstrcpy
  286. formats a string
  287. .BR s ;
  288. .I fmtrunestrcpy
  289. formats a rune string
  290. .BR s .
  291. .I Errfmt
  292. formats the system error string.
  293. All these routines return zero for successful execution.
  294. Conversion routines that call these functions will work properly
  295. regardless of whether the output is bytes or runes.
  296. .PP
  297. .IR 2c (1)
  298. describes the C directive
  299. .B #pragma
  300. .B varargck
  301. that can be used to provide type-checking for custom print verbs and output routines.
  302. .SH EXAMPLES
  303. This function prints an error message with a variable
  304. number of arguments and then quits.
  305. Compared to the corresponding example in
  306. .IR print (2),
  307. this version uses a smaller buffer, will never truncate
  308. the output message, but might generate multiple
  309. .B write
  310. system calls to produce its output.
  311. .IP
  312. .EX
  313. .ta 6n +6n +6n +6n +6n +6n +6n +6n +6n
  314. #pragma varargck argpos error 1
  315. void fatal(char *fmt, ...)
  316. {
  317. Fmt f;
  318. char buf[64];
  319. va_list arg;
  320. fmtfdinit(&f, 1, buf, sizeof buf);
  321. fmtprint(&f, "fatal: ");
  322. va_start(arg, fmt);
  323. fmtvprint(&f, fmt, arg);
  324. va_end(arg);
  325. fmtprint(&f, "\en");
  326. fmtfdflush(&f);
  327. exits("fatal error");
  328. }
  329. .EE
  330. .PP
  331. This example adds a verb to print complex numbers.
  332. .IP
  333. .EX
  334. typedef
  335. struct {
  336. double r, i;
  337. } Complex;
  338. #pragma varargck type "X" Complex
  339. int
  340. Xfmt(Fmt *f)
  341. {
  342. Complex c;
  343. c = va_arg(f->args, Complex);
  344. return fmtprint(f, "(%g,%g)", c.r, c.i);
  345. }
  346. main(...)
  347. {
  348. Complex x = (Complex){ 1.5, -2.3 };
  349. fmtinstall('X', Xfmt);
  350. print("x = %X\en", x);
  351. }
  352. .EE
  353. .SH SOURCE
  354. .B /sys/src/libc/fmt
  355. .SH SEE ALSO
  356. .IR print (2),
  357. .IR utf (6),
  358. .IR errstr (2)
  359. .SH DIAGNOSTICS
  360. These routines return negative numbers or nil for errors and set
  361. .IR errstr .
  362. .SH BUGS