contrib/libxo/libxo/xo_create.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_create , xo_create_to_file , xo_destroy
  15 .Nd create and destroy libxo output handles
  16 .Sh LIBRARY
  17 .Lb libxo
  18 .Sh SYNOPSIS
  19 .In libxo/xo.h
  20 .Ft xo_handle_t *
  21 .Fn xo_create "unsigned style" "unsigned flags"
  22 .Ft xo_handle_t *
  23 .Fn xo_create_to_file "FILE *fp" "unsigned style" "unsigned flags"
  24 .Ft void
  25 .Fn xo_destroy "xo_handle_t *handle"
  26 .Sh DESCRIPTION
  27 A
  28 .Nm libxo
  29 handle can be allocated using the
  30 .Fn xo_create
  31 function.
  32 .Bd -literal -offset indent
  33   Example:
  34     xo_handle_t *xop = xo_create(XO_STYLE_JSON, XOF_WARN);
  35     ....
  36     xo_emit_h(xop, "testing\n");
  37 .Ed
  38 .Pp
  39 By default,
  40 .Nm libxo
  41 writes output to standard output.
  42 A convenience
  43 function is provided for situations when output should be written to a
  44 different file.
  45 .Pp
  46 Use the
  47 .Dv XOF_CLOSE_FP
  48 flag to trigger a call to
  49 .Xr fclose 3
  50 for the
  51 .Dv FILE
  52 pointer when the handle is destroyed.
  53 .Pp
  54 The
  55 .Fn xo_destroy
  56 function releases a handle and any resources it is
  57 using.
  58 Calling
  59 .Fn xo_destroy
  60 with a
  61 .Dv NULL
  62 handle will release any
  63 resources associated with the default handle.
  64 .Sh SEE ALSO
  65 .Xr xo_emit 3 ,
  66 .Xr xo_set_options 3 ,
  67 .Xr libxo 3
  68 .Sh HISTORY
  69 The
  70 .Nm libxo
  71 library first appeared in
  72 .Fx 11.0 .
  73 .Sh AUTHORS
  74 .Nm libxo
  75 was written by
  76 .An Phil Shafer Aq Mt phil@freebsd.org .
  77