[apple/libc.git] / stdio / xprintf_comp.3

.Dd Aug 19, 2012
.Dt XPRINTF_COMP 3
.Os Darwin
.Sh NAME
.Nm free_printf_comp , new_printf_comp
.Nd extensible printf compilation
.Sh SYNOPSIS
.In printf.h
.Ft void
.Fn free_printf_comp "printf_comp_t pc"
.Ft printf_comp_t
.Fn new_printf_comp "printf_domain_t restrict domain" "locale_t restrict loc" "const char * restrict fmt"
.Sh DESCRIPTION
To ameliorate some of the slowness caused by the extra overhead in
extensible printf (see
.Xr xprintf 5 ) ,
a compile/execute mechanism has been created.
The
.Fn new_printf_comp
function compiles the given format string, along with a printf domain
(see
.Xr xprintf_domain 3 )
and an extended locale
(see
.Xr xlocale 3 ) ,
and returns a
.Ft printf_comp_t
structure.
The domain may not be
.Dv NULL ,
but the locale can be
.Dv NULL ,
which means to use the current locale, either the per-thread locale if it
was set, or else the global locale.
Because the
.Ft printf_comp_t
structure records the domain and locale, care should be taken if either
of these are changed.
.Pp
Once a
.Ft printf_comp_t
structure is created, it can be passed to one of the extensible printf
execution variants, described in
.Xr xprintf_exec 3 ,
along with the necessary arguments.
Creating the
.Ft printf_comp_t
structure needs to be done only once, but it can be passed
to extensible printf execution variants any number of times.
.Pp
When the
.Ft printf_comp_t
structure is no longer needed, it should be passed to
.Fn free_printf_comp
to release internal memory.
.Sh RETURN VALUES
The
.Fn new_printf_comp
function returns the new structure, or
.Dv NULL
on error (usually NULL domain or out of memory condition).
.Sh SEE ALSO
.Xr xlocale 3 ,
.Xr xprintf_domain 3 ,
.Xr xprintf_exec 3 ,
.Xr xprintf 5
Commit	Line	Data
6465356a A	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