.\" #
.\" # Copyright (c) 2014, Juniper Networks, Inc.
.\" # All rights reserved.
.\" # This SOFTWARE is licensed under the LICENSE provided in the
.\" # ../Copyright file. By downloading, installing, copying, or
.\" # using the SOFTWARE, you agree to be bound by the terms of that
.\" # LICENSE.
.\" # Phil Shafer, July 2014
.\"
.Dd December 4, 2014
.Dt LIBXO 3
.Os
.Sh NAME
.Nm xo_open_container , xo_open_container_h , xo_open_container_hd , xo_open_container_d
.Nm xo_close_container , xo_close_container_h , xo_close_container_hd , xo_close_container_d
.Nd open (and close) container constructs
.Sh LIBRARY
.Lb libxo
.Sh SYNOPSIS
.In libxo/xo.h
.Ft int
.Fn xo_open_container "const char *name"
.Ft int
.Fn xo_open_container_h "xo_handle_t *handle" "const char *name"
.Ft int
.Fn xo_open_container_hd "xo_handle_t *handle" "const char *name"
.Ft int
.Fn xo_open_container_d "const char *name"
.Ft int
.Fn xo_close_container "const char *name"
.Ft int
.Fn xo_close_container_h "xo_handle_t *handle" "const char *name"
.Ft int
.Fn xo_close_container_hd "xo_handle_t *handle"
.Ft int
.Fn xo_close_container_d "void"
.Sh DESCRIPTION
.Nm libxo
represents two types of hierarchy:
.Dq containers
and
.Dq lists .
A container appears once under a given parent where a list contains
instances that can appear multiple times.
A container is used to hold
related fields and to give the data organization and scope.
The container has no value, but serves to
contain other nodes.
.Pp
To open a container, call
.Fn xo_open_container
or
.Fn xo_open_container_h .
The former uses the default handle and
the latter accepts a specific handle.
.Pp
To close a level, use the
.Fn xo_close_container
or
.Fn xo_close_container_h
functions.
.Pp
Each open call should have a matching close call.
If the
.Dv XOF_WARN
flag is set and the name given does not match the name of
the currently open
container, a warning will be generated.
.Bd -literal -offset indent -compact
Example:
xo_open_container("top");
xo_open_container("system");
xo_emit("{:host-name/%s%s%s", hostname,
domainname ? "." : "", domainname ?: "");
xo_close_container("system");
xo_close_container("top");
Sample Output:
Text:
my-host.example.org
XML: