1.\" # 2.\" # Copyright (c) 2021, 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, July 2014 9.\" 10.Dd December 4, 2014 11.Dt LIBXO 3 12.Os 13.Sh NAME 14.Nm xo_emit_field 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 xo_ssize_t 21.Fn xo_emit_field "const char *rolmod" "const char *content" "const char *fmt" "const char *efmt" "..." 22.Ft xo_ssize_t 23.Fn xo_emit_field_h "xo_handle_t *xop" "const char *rolmod" "const char *content" "const char *fmt" const char *efmt" "..." 24.Ft xo_ssize_t 25.Fn xo_emit_field_hv "xo_handle_t *xop" "const char *rolmod" "const char *content" "const char *fmt" "const char *efmt" "va_list vap" 26.Sh DESCRIPTION 27The 28.Fn xo_emit_field 29function emits formatted output similar to 30.Xr xo_emit 3 31but where 32.Fn xo_emit 33uses a single string argument containing the description 34for multiple fields, 35.Fn xo_emit_field 36emits a single field using multiple arguments to contain the 37field description. 38.Fn xo_emit_field_h 39adds an explicit handle to use instead of the default 40handle, while 41.Fn xo_emit_field_hv 42accepts a 43.Fa va_list 44for additional flexibility. 45.Pp 46The arguments 47.Fa rolmod , 48.Fa content , 49.Fa fmt , 50and 51.Fa efmt 52are detailed in 53.Xr xo_format 5 . 54Using distinct arguments allows callers to pass the field description 55in pieces, rather than having to use something like 56.Xr snprintf 3 57to build the format string required by 58.Fn xo_emit . 59The arguments are each NUL-terminated strings. The 60.Fa rolmod 61argument contains the "role" and "modifier" portions of 62the field description, the 63.Fa content 64argument contains the "content" portion, and the 65.Fa fmt 66and 67.Fa efmt 68contain the "field-format" and "encoding-format" portions, respectively. 69.Pp 70As with xo_emit, the 71.Fa fmt 72and 73.Fa efmt 74values are both optional, since the field-format string 75defaults to "%s", and the encoding-format's default value is 76derived from the field-format 77per 78.Xr xo_format 5 . 79However, care must be taken to avoid using a value directly as the 80format, since characters like '{', '%', and '}' will be interpreted 81as formatting directives, and may cause 82.Nm 83to dereference arbitrary values off the stack, leading to bugs, 84core files, and gnashing of teeth. 85.Sh EXAMPLES 86In this example, a set of four values is emitted using the following 87source code: 88.Bd -literal -offset indent 89 xo_emit_field("T", title, NULL, NULL, NULL); 90 xo_emit_field("Vt", "max-chaos", NULL, NULL, " very "); 91 xo_emit_field("V", "min-chaos", "%02d", "%d", 42); 92 xo_emit_field_h(NULL, ",leaf-list,quotes", "sku", "%s-%u", "%s-000-%u", 93 "gum", 1412); 94.Ed 95.Sh RETURN CODE 96.Nm 97returns a negative value on error. If the 98.Nm XOF_COLUMNS 99flag has been turned on for the specific handle using 100.Xr xo_set_flags 3 , 101then the number of display columns consumed by the output will be returned. 102.Sh SEE ALSO 103.Xr xo_format 5 , 104.Xr libxo 3 105.Sh HISTORY 106The 107.Nm libxo 108library first appeared in 109.Fx 11.0 . 110.Sh AUTHORS 111.Nm libxo 112was written by 113.An Phil Shafer Aq Mt phil@freebsd.org . 114