pd.if.org Git - pdclib.old/blob - man3/_cbprintf.3

   1 .\" This file is part of the Public Domain C Library (PDCLib).
   2 .\" Permission is granted to use, modify, and / or redistribute at will.
   3 .\"
   4 .Dd
   5 .Dt _CBPRINTF 3
   6 .Os
   7 .\"
   8 .Sh NAME
   9 .Nm _cbprintf ,
  10 .Nm _vcbprintf ,
  11 .Nm _cbwprintf ,
  12 .Nm _vcbwprintf
  13 .Nd formatted output conversion by callback
  14 .\"
  15 .Sh SYNOPSIS
  16 .In stdio.h
  17 .Fn "int _cbprintf"   "void *p" "size_t (*cb)(void *p, const char    *buf, size_t size)" "const char *fmt" "..."
  18 .Fn "int _vcbprintf"  "void *p" "size_t (*cb)(void *p, const char    *buf, size_t size)" "const char *fmt" "va_list ap"
  19 .Pp
  20 .In wchar.h
  21 .Fn "int _cbwprintf"  "void *p" "size_t (*cb)(void *p, const wchar_t *buf, size_t size)" "const wchar_t *fmt" "..."
  22 .Fn "int _vcbwprintf" "void *p" "size_t (*cb)(void *p, const wchar_t *buf, size_t size)" "const wchar_t *fmt" "va_list ap"
  23 .\"
  24 .Sh DESCRIPTION
  25 These functions permit the
  26 .Fn printf
  27 string formatting functionality to be reused outside the C standard library,
  28 without the limitation of using the
  29 .Fn sprintf
  30 function for this process, that the whole formatted string must exist in memory
  31 at once.
  32 .Pp
  33 .\"
  34 These functions shall exhibit the same behaviour and conversion specifiers as
  35 the
  36 .Xr printf 3
  37 function, except they shall perform their output by calling the
  38 .Fa cb
  39 callback, passing the characters to be output as the
  40 .Fa buf
  41 parameter, and the count of such characters as
  42 .Fa size .
  43 .Pp
  44 .\"
  45 The implementation is permitted to invoke
  46 .Fa cb
  47 with a non-zero number of characters as many times as it deems necessary
  48 necessary. That is, the implementation may decide to call it only once it has
  49 finished conversion of the entire string, or it may call it multiple times as it
  50 incrementally performs a conversion (it would be legal for an implementation to
  51 invoke the callback for every character produced).
  52 .Pp
  53 .\"
  54 During all invocations, the callback will be passed as
  55 .Fa p
  56 the same value as was passed to the function.
  57 .Pp
  58 .\"
  59 The callback shall return
  60 .Fa size
  61 on success, or any other value on failure
  62 .\"
  63 .Sh RETURN VALUES
  64 The functions shall return the number of characters produced by the conversion
  65 on success, or a negative number on failure. If the number of characters
  66 converted exceeds
  67 .Dv INT_MAX ,
  68 then
  69 .Dv INT_MAX
  70 shall be returned.
  71 .\"
  72 .Sh EXAMPLES
  73 Using
  74 .Fn _vcbprintf
  75 to reimplement printf
  76 .Bd -literal -offset indent
  77 static size_t do_output(void *p, const char *buf, size_t size)
  78 {
  79     return fwrite(buf, 1, size, (FILE *) p);
  80 }
  81
  82 int myprintf(const char *fmt, ...)
  83 {
  84     va_list ap;
  85     va_start(ap, fmt);
  86     return _vcbprintf(stdout, do_output, ap);
  87     va_end(ap);
  88 }
  89 .Ed
  90 .\"
  91 .Sh ERRORS
  92 This function shall not affect errno, however the callbacks it invokes may
  93 .\"
  94 .Sh SEE ALSO
  95 .Xr printf 3
  96 .\"
  97 .Sh RATIONALE
  98 Sensible implementations of the ISO C standard library implement an analogous
  99 system internally, permitting them to share their implementation of formatting
 100 between
 101 .Xr printf 3
 102 and
 103 .Xr sprintf 3 .
 104 Therefore, implementing a callback based variant is not of substantial
 105 complexity.
 106 .Pp
 107 These functions permit the reuse of this functionality by applications and
 108 libraries (for example, a logging library) without the need to reimplement it,
 109 and without the aforementioned memory limitation imposed by
 110 .Xr sprintf 3 .
 111 .\"
 112 .Sh HISTORY
 113 This nonstandard extension was first defined by PDCLib.