contrib/libxo/libxo/xo_err.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_err , xo_errc , xo_errx
  15 .Nm xo_warn , xo_warnx , xo_warn_c , xo_warn_hc
  16 .Nd emit errors and warnings in multiple output styles
  17 .Sh LIBRARY
  18 .Lb libxo
  19 .Sh SYNOPSIS
  20 .In libxo/xo.h
  21 .Ft void
  22 .Fn xo_warn "const char *fmt"  "..."
  23 .Ft void
  24 .Fn xo_warnx "const char *fmt" "..."
  25 .Ft void
  26 .Fn xo_warn_c "int code" "const char *fmt" "..."
  27 .Ft void
  28 .Fn xo_warn_hc "xo_handle_t *xop" "int code, const char *fmt" "..."
  29 .Ft void
  30 .Fn xo_err "int eval" "const char *fmt" "..."
  31 .Ft void
  32 .Fn xo_errc "int eval" "int code" "const char *fmt" "..."
  33 .Ft void
  34 .Fn xo_errx "int eval" "const char *fmt" "..."
  35 .Sh DESCRIPTION
  36 Many programs make use of the standard library functions
  37 .Xr err 3
  38 and
  39 .Xr warn 3
  40 to generate errors and warnings for the user.
  41 .Nm libxo
  42 wants to
  43 pass that information via the current output style, and provides
  44 compatible functions to allow this.
  45 .Pp
  46 The
  47 .Fa fmt
  48 argument is one compatible with
  49 .Xr printf 3
  50 rather than
  51 .Xr xo_emit 3
  52 to aid in simple conversion.  This means
  53 these functions make unstructured data.
  54 To generate structured data,
  55 use the
  56 .Xr xo_emit_err 3
  57 functions.
  58 .Pp
  59 These functions display the program name, a colon, a formatted message
  60 based on the arguments, and then optionally a colon and an error
  61 message associated with either
  62 .Fa errno
  63 or the
  64 .Fa code
  65 parameter.
  66 .Bd -literal -offset indent
  67     EXAMPLE:
  68         if (open(filename, O_RDONLY) < 0)
  69             xo_err(1, "cannot open file '%s'", filename);
  70 .Ed
  71 .Sh SEE ALSO
  72 .Xr xo_emit 3 ,
  73 .Xr xo_emit_err 3 ,
  74 .Xr libxo 3
  75 .Sh HISTORY
  76 The
  77 .Nm libxo
  78 library first appeared in
  79 .Fx 11.0 .
  80 .Sh AUTHORS
  81 .Nm libxo
  82 was written by
  83 .An Phil Shafer Aq Mt phil@freebsd.org .
  84