contrib/libxo/libxo/xo_message.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 December 4, 2014
  11 .Dt LIBXO 3
  12 .Os
  13 .Sh NAME
  14 .Nm xo_message , xo_message_c , xo_message_hc , xo_message_hcv
  15 .Nd emit messages in multiple output styles
  16 .Sh LIBRARY
  17 .Lb libxo
  18 .Sh SYNOPSIS
  19 .In libxo/xo.h
  20 .Ft void
  21 .Fn xo_message "const char *fmt" "..."
  22 .Ft void
  23 .Fn xo_message_e "const char *fmt" "..."
  24 .Ft void
  25 .Fn xo_message_c "int code" "const char *fmt" "..."
  26 .Ft void
  27 .Fn xo_message_hc "xo_handle_t *xop" "int code, const char *fmt" "..."
  28 .Ft void
  29 .Fn xo_message_hcv "xo_handle_t *xop" "int code" "const char *fmt" "va_list vap"
  30 .Sh DESCRIPTION
  31 .Nm xo_message
  32 generates text message which lack any sort of structure.
  33 These functions should not be used under normal conditions, since
  34 they completely defeat the value of using libxo.  They are provided
  35 for scenarios when the output's content is genuinely unknown and
  36 unusable.
  37 It is used in converting programs where err/warn where not used,
  38 and error messages went to
  39 .Nm stdout ,
  40 not
  41 .Nm stderr .
  42 Use of
  43 .Nm xo_message
  44 allows backwards compatibility with that output, but does not put
  45 the error in a useful form.
  46 .Pp
  47 The
  48 .Nm xo_message
  49 function generates output strings using the printf-style format string
  50 and arguments provided.
  51 If the format string does not end in a newline,
  52 .Nm xo_message_e
  53 will appear a colon, a space, and the error associated with the current
  54 .Nm errno
  55 value.
  56 .Nm xo_message_c behaves similarly for the value passed in the
  57 .Fa code
  58 parameter.
  59 .Nm xo_message_hc
  60 accepts a
  61 .Fa handle
  62 as opened by
  63 .Xr xo_create 3
  64 and
  65 .Nm xo_message_hcv accepts a va_list parameter of arguments.
  66 .Sh SEE ALSO
  67 .Xr xo_emit 3 ,
  68 .Xr libxo 3
  69 .Sh HISTORY
  70 The
  71 .Nm libxo
  72 library first appeared in
  73 .Fx 11.0 .
  74 .Sh AUTHORS
  75 .Nm libxo
  76 was written by
  77 .An Phil Shafer Aq Mt phil@freebsd.org .
  78