stdio/xprintf_comp.3

   1 .Dd Aug 19, 2012
   2 .Dt XPRINTF_COMP 3
   3 .Os Darwin
   4 .Sh NAME
   5 .Nm free_printf_comp , new_printf_comp
   6 .Nd extensible printf compilation
   7 .Sh SYNOPSIS
   8 .In printf.h
   9 .Ft void
  10 .Fn free_printf_comp "printf_comp_t pc"
  11 .Ft printf_comp_t
  12 .Fn new_printf_comp "printf_domain_t restrict domain" "locale_t restrict loc" "const char * restrict fmt"
  13 .Sh DESCRIPTION
  14 To ameliorate some of the slowness caused by the extra overhead in
  15 extensible printf (see
  16 .Xr xprintf 5 ) ,
  17 a compile/execute mechanism has been created.
  18 The
  19 .Fn new_printf_comp
  20 function compiles the given format string, along with a printf domain
  21 (see
  22 .Xr xprintf_domain 3 )
  23 and an extended locale
  24 (see
  25 .Xr xlocale 3 ) ,
  26 and returns a
  27 .Ft printf_comp_t
  28 structure.
  29 The domain may not be
  30 .Dv NULL ,
  31 but the locale can be
  32 .Dv NULL ,
  33 which means to use the current locale, either the per-thread locale if it
  34 was set, or else the global locale.
  35 Because the
  36 .Ft printf_comp_t
  37 structure records the domain and locale, care should be taken if either
  38 of these are changed.
  39 .Pp
  40 Once a
  41 .Ft printf_comp_t
  42 structure is created, it can be passed to one of the extensible printf
  43 execution variants, described in
  44 .Xr xprintf_exec 3 ,
  45 along with the necessary arguments.
  46 Creating the
  47 .Ft printf_comp_t
  48 structure needs to be done only once, but it can be passed
  49 to extensible printf execution variants any number of times.
  50 .Pp
  51 When the
  52 .Ft printf_comp_t
  53 structure is no longer needed, it should be passed to
  54 .Fn free_printf_comp
  55 to release internal memory.
  56 .Sh RETURN VALUES
  57 The
  58 .Fn new_printf_comp
  59 function returns the new structure, or
  60 .Dv NULL
  61 on error (usually NULL domain or out of memory condition).
  62 .Sh SEE ALSO
  63 .Xr xlocale 3 ,
  64 .Xr xprintf_domain 3 ,
  65 .Xr xprintf_exec 3 ,
  66 .Xr xprintf 5