contrib/libxo/libxo/xo_attr.3

   1 .\" #
   2 .\" # Copyright (c) 2014, 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 July, 2014
  11 .Dt LIBXO 3
  12 .Os
  13 .Sh NAME
  14 .Nm xo_attr , xo_attr_h , xo_attr_hv
  15 .Nd Add attribute name/value pairs to formatted output
  16 .Sh LIBRARY
  17 .Lb libxo
  18 .Sh SYNOPSIS
  19 .In libxo/xo.h
  20 .Ft int
  21 .Fn xo_attr "const char *name" "const char *fmt" "..."
  22 .Ft int
  23 .Fn xo_attr_h "xo_handle_t *handle" "const char *name, const char *fmt" "..."
  24 .Ft int
  25 .Fn xo_attr_hv "xo_handle_t *handle" "const char *name" "const char *fmt" "va_list vap"
  26 .Sh DESCRIPTION
  27 The
  28 .Fn xo_attr
  29 function emits attributes for the XML output style.  The attribute
  30 value is recorded in the
  31 .Fa handle
  32 and is attached to the next field that is emitted via a
  33 .Xr xo_emit 3
  34 call.
  35 .Pp
  36 The
  37 .Fa name
  38 parameter give the name of the attribute to be encoded.  The
  39 .Fa fmt
  40 parameter gives a printf-style format string used to format the
  41 value of the attribute using any remaining arguments, or the
  42 .Fa vap
  43 parameter as passed to
  44 .Fn xo_attr_hv .
  45 .Bd -literal -offset indent
  46     EXAMPLE:
  47       xo_attr("seconds", "%ld", (unsigned long) login_time);
  48       struct tm *tmp = localtime(login_time);
  49       strftime(buf, sizeof(buf), "%R", tmp);
  50       xo_emit("Logged in at {:login-time}\\n", buf);
  51     XML:
  52         <login-time seconds="1408336270">00:14</login-time>
  53 .Ed
  54 .Pp
  55 Since attributes are only emitted in XML, their use should be limited
  56 to meta-data and additional or redundant representations of data
  57 already emitted in other form.
  58 .Sh SEE ALSO
  59 .Xr xo_emit 3 ,
  60 .Xr libxo 3
  61 .Sh HISTORY
  62 The
  63 .Nm libxo
  64 library first appeared in
  65 .Fx 11.0 .
  66 .Sh AUTHORS
  67 .Nm libxo
  68 was written by
  69 .An Phil Shafer Aq Mt phil@freebsd.org .
  70