1.\" # 2.\" # Copyright (c) 2016, Juniper Networks, Inc. 3.\" # All rights reserved. 4.\" # This SOFTWARE is licensed under the LICENSE provided in the 5.\" # ../Copyright file. By downloading, installing, copying, or 6.\" # using the SOFTWARE, you agree to be bound by the terms of that 7.\" # LICENSE. 8.\" # Phil Shafer, April 2016 9.\" 10.Dd April 15, 2016 11.Dt LIBXO 3 12.Os 13.Sh NAME 14.Nm xo_emit_f , xo_emit_hf , xo_emit_hvf 15.Nd emit formatted output based on format string and arguments 16.Sh LIBRARY 17.Lb libxo 18.Sh SYNOPSIS 19.In libxo/xo.h 20.Ft int 21.Fn xo_emit_f "xo_emit_flags_t flags" "const char *fmt" "..." 22.Ft int 23.Fn xo_emit_hf "xo_handle_t *xop" "xo_emit_flags_t flags" "const char *fmt" "..." 24.Ft int 25.Fn xo_emit_hvf "xo_handle_t *xop" "xo_emit_flags_t flags" "const char *fmt" "va_list vap" 26.Ft void 27.Fn xo_retain_clear_all "void" 28.Ft void 29.Fn xo_retain_clear "const char *fmt" 30.Sh DESCRIPTION 31These functions allow callers to pass a set of flags to 32.Nm 33emitting functions. These processing of arguments, except for 34.Fa flags , 35is identical to the base functions. 36See 37.Xr xo_emit 3 38for additional information. 39.Pp 40The only currently defined flag is 41.Dv XOEF_RETAIN . 42.Nm 43can retain the parsed internal information related to the given 44format string, allowing subsequent 45.Xr xo_emit 3 46calls, the retained 47information is used, avoiding repetitive parsing of the format string. 48To retain parsed format information, use the 49.Dv XOEF_RETAIN 50flag to the 51.Fn xo_emit_f 52function. 53.Pp 54The format string must be immutable across multiple calls to 55.Xn xo_emit_f , 56since the library retains the string. 57Typically this is done by using 58static constant strings, such as string literals. If the string is not 59immutable, the 60.Dv XOEF_RETAIN 61flag must not be used. 62.Pp 63The functions 64.Fn xo_retain_clear 65and 66.Fn xo_retain_clear_all 67release internal information on either a single format string or all 68format strings, respectively. 69Neither is required, but the library will 70retain this information until it is cleared or the process exits. 71.Pp 72The retained information is kept as thread-specific data. 73.Pp 74Use 75.Fn xo_retain_clear 76and 77.Fn xo_retain_clear_all 78to clear the retained information, clearing the retained information 79for either a specific format string or all format strings, respectively. 80These functions are only needed when the calling application wants to 81clear this information; they are not generally needed. 82.Sh EXAMPLES 83.Pp 84.Bd -literal -offset indent 85 for (i = 0; i < 1000; i++) { 86 xo_open_instance("item"); 87 xo_emit_f(XOEF_RETAIN, "{:name} {:count/%d}\n", 88 name[i], count[i]); 89 } 90.Ed 91.Pp 92In this example, the caller desires to clear the retained information. 93.Bd -literal -offset indent 94 const char *fmt = "{:name} {:count/%d}\n"; 95 for (i = 0; i < 1000; i++) { 96 xo_open_instance("item"); 97 xo_emit_f(XOEF_RETAIN, fmt, name[i], count[i]); 98 } 99 xo_retain_clear(fmt); 100.Ed 101.Sh RETURN CODE 102The return values for these functions is identical to those of their 103traditional counterparts. See 104.Xr xo_emit 3 105for details. 106.Sh SEE ALSO 107.Xr xo_emit 3 , 108.Xr xo_open_container 3 , 109.Xr xo_open_list 3 , 110.Xr xo_format 5 , 111.Xr libxo 3 112