git.saurik.com Git - apple/libc.git/blob

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