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