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
14To ameliorate some of the slowness caused by the extra overhead in
15extensible printf (see
16.Xr xprintf 5 ) ,
17a compile/execute mechanism has been created.
18The
19.Fn new_printf_comp
20function compiles the given format string, along with a printf domain
21(see
22.Xr xprintf_domain 3 )
23and an extended locale
24(see
25.Xr xlocale 3 ) ,
26and returns a
27.Ft printf_comp_t
28structure.
29The domain may not be
30.Dv NULL ,
31but the locale can be
32.Dv NULL ,
33which means to use the current locale, either the per-thread locale if it
34was set, or else the global locale.
35Because the
36.Ft printf_comp_t
37structure records the domain and locale, care should be taken if either
38of these are changed.
39.Pp
40Once a
41.Ft printf_comp_t
42structure is created, it can be passed to one of the extensible printf
43execution variants, described in
44.Xr xprintf_exec 3 ,
45along with the necessary arguments.
46Creating the
47.Ft printf_comp_t
48structure needs to be done only once, but it can be passed
49to extensible printf execution variants any number of times.
50.Pp
51When the
52.Ft printf_comp_t
53structure is no longer needed, it should be passed to
54.Fn free_printf_comp
55to release internal memory.
56.Sh RETURN VALUES
57The
58.Fn new_printf_comp
59function returns the new structure, or
60.Dv NULL
61on 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
67