diff options
Diffstat (limited to 'contrib/libxo/doc/api.rst')
| -rw-r--r-- | contrib/libxo/doc/api.rst | 59 |
1 files changed, 41 insertions, 18 deletions
diff --git a/contrib/libxo/doc/api.rst b/contrib/libxo/doc/api.rst index 94358489f075..8a9b7bb5cefe 100644 --- a/contrib/libxo/doc/api.rst +++ b/contrib/libxo/doc/api.rst @@ -386,19 +386,18 @@ xo_destroy Emitting Content (xo_emit) -------------------------- -The functions in this section are used to emit output. - -The "fmt" argument is a string containing field descriptors as -specified in :ref:`format-strings`. The use of a handle is optional and -`NULL` can be passed to access the internal "default" handle. See +The functions in this section are used to emit output. They use a +`format` string containing field descriptors as specified in +:ref:`format-strings`. The use of a handle is optional and `NULL` can +be passed to access the internal "default" handle. See :ref:`handles`. The remaining arguments to `xo_emit` and `xo_emit_h` are a set of arguments corresponding to the fields in the format string. Care must be taken to ensure the argument types match the fields in the format -string, since an inappropriate cast can ruin your day. The vap -argument to `xo_emit_hv` points to a variable argument list that can -be used to retrieve arguments via `va_arg`. +string, since an inappropriate or missing argument can ruin your day. +The `vap` argument to `xo_emit_hv` points to a variable argument list +that can be used to retrieve arguments via `va_arg`. .. c:function:: xo_ssize_t xo_emit (const char *fmt, ...) @@ -428,19 +427,40 @@ be used to retrieve arguments via `va_arg`. Single Field Emitting Functions (xo_emit_field) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The functions in this section can also make output, but only make a -single field at a time. These functions are intended to avoid the -scenario where one would otherwise need to compose a format -descriptors using `snprintf`. The individual parts of the format -descriptor are passed in distinctly. - -.. c:function:: xo_ssize_t xo_emit_field (const char *rolmod, const char *contents, const char *fmt, const char *efmt, ...) +The functions in this section emit formatted output similar to +`xo_emit` but where `xo_emit` uses a single string argument containing +the description for multiple fields, `xo_emit_field` emits a single +field using multiple ar- guments to contain the field description. +`xo_emit_field_h` adds an ex- plicit handle to use instead of the +default handle, while `xo_emit_field_hv` accepts a va_list for +additional flexibility. + +The arguments `rolmod`, `content`, `fmt`, and `efmt` are detailed in +:ref:`field-formatting`. Using distinct arguments allows callers to +pass the field description in pieces, rather than having to use +something like `snprintf` to build the format string required by +`xo_emit`. The arguments are each NUL-terminated strings. The `rolmod` +argument contains the `role` and `modifier` portions of the field +description, the `content` argument contains the `content` portion, and +the `fmt` and `efmt` contain the `field-format` and `encoding-format` por- +tions, respectively. + +As with `xo_emit`, the `fmt` and `efmt` values are both optional, +since the `field-format` string defaults to "%s", and the +`encoding-format`'s default value is derived from the `field-format` +per :ref:`field-formatting`. However, care must be taken to avoid +using a value directly as the format, since characters like '{', '%', +and '}' will be interpreted as formatting directives, and may cause +xo_emit_field to dereference arbitrary values off the stack, leading +to bugs, core files, and gnashing of teeth. + +.. c:function:: xo_ssize_t xo_emit_field (const char *rolmod, const char *content, const char *fmt, const char *efmt, ...) :param rolmod: A comma-separated list of field roles and field modifiers :type rolmod: const char * - :param contents: The "contents" portion of the field description string - :type contents: const char * - :param fmt: Content format string + :param content: The "content" portion of the field description string + :type content: const char * + :param fmt: Contents format string :type fmt: const char * :param efmt: Encoding format string, followed by additional arguments :type efmt: const char * @@ -450,8 +470,11 @@ descriptor are passed in distinctly. :: EXAMPLE:: + xo_emit_field("T", title, NULL, NULL, NULL); xo_emit_field("T", "Host name is ", NULL, NULL); xo_emit_field("V", "host-name", NULL, NULL, host-name); + xo_emit_field(",leaf-list,quotes", "sku", "%s-%u", "%s-000-%u", + "gum", 1412); .. c:function:: xo_ssize_t xo_emit_field_h (xo_handle_t *xop, const char *rolmod, const char *contents, const char *fmt, const char *efmt, ...) |