---
name: "xo_open_container"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/xo_close_container"
---

# xo\_open\_container(3)

open (and close) container constructs

Part of [xo\_close\_container(3)](/xo_close_container/3.md).

## NAME

**xo\_open\_container**, **xo\_open\_container\_h**, **xo\_open\_container\_hd**, **xo\_open\_container\_d** **xo\_close\_container**, **xo\_close\_container\_h**, **xo\_close\_container\_hd**, **xo\_close\_container\_d** – open (and close) container constructs

## LIBRARY

library “libxo”

## SYNOPSIS

**#include \<libxo/xo.h\>**

*xo\_ssize\_t*\

**xo\_open\_container**(*const char \*name*);

*xo\_ssize\_t*\

**xo\_open\_container\_h**(*xo\_handle\_t \*handle*, *const char \*name*);

*xo\_ssize\_t*\

**xo\_open\_container\_hd**(*xo\_handle\_t \*handle*, *const char \*name*);

*xo\_ssize\_t*\

**xo\_open\_container\_d**(*const char \*name*);

*xo\_ssize\_t*\

**xo\_close\_container**(*const char \*name*);

*xo\_ssize\_t*\

**xo\_close\_container\_h**(*xo\_handle\_t \*handle*, *const char \*name*);

*xo\_ssize\_t*\

**xo\_close\_container\_hd**(*xo\_handle\_t \*handle*);

*xo\_ssize\_t*\

**xo\_close\_container\_d**(*void*);

## DESCRIPTION

**libxo** represents two types of hierarchy: “containers” and “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.

To open a container, call **xo\_open\_container**() or **xo\_open\_container\_h**(). The former uses the default handle and the latter accepts a specific handle.

To close a level, use the **xo\_close\_container**() or **xo\_close\_container\_h**() functions.

Each open call should have a matching close call. If the XOF\_WARN flag is set and the name given does not match the name of  the currently open container, a warning will be generated.

```
    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:
        <top>
          <system>
              <host-name>my-host.example.org</host-name>
          </system>
        </top>
      JSON:
        "top" : {
          "system" : {
              "host-name": "my-host.example.org"
          }
        }
      HTML:
        <div class="data"
             data-tag="host-name">my-host.example.org</div>
```

## EMITTING HIERARCHY

To create a container, use the **xo\_open\_container**() and **xo\_close\_container**() set of functions. The *handle* parameter contains a handle such as returned by [xo\_create(3)](/xo_create/3.md) or NULL to use the default handle. The *name* parameter gives the name of the container, encoded in *UTF-8*. Since *ASCII* is a proper subset of *UTF-8*, traditional C strings can be used directly.

The close functions with the “\_d” suffix are used in “Do The Right Thing” mode, where the name of the open containers, lists, and instances are maintained internally by **libxo** to allow the caller to avoid keeping track of the open container name.

Use the XOF\_WARN flag to generate a warning if the name given on the close does not match the current open container.

For TEXT and HTML output, containers are not rendered into output text, though for HTML they are used when the XOF\_XPATH flag is set.

```
    EXAMPLE:
       xo_open_container("system");
       xo_emit("The host name is {:host-name}\n", hn);
       xo_close_container("system");
    XML:
       <system><host-name>foo</host-name></system>
```

## DTRT MODE

Some users may find tracking the names of open containers, lists, and instances inconvenient. **libxo** offers a “Do The Right Thing” mode, where **libxo** will track the names of open containers, lists, and instances so the close function can be called without a name. To enable *DTRT* mode, turn on the XOF\_DTRT flag prior to making any other **libxo** output.

```
    xo_set_flags(NULL, XOF_DTRT);
```

Each open and close function has a version with the suffix “\_d”, which will close the open container, list, or instance:

```
    xo_open_container("top");
    ...
    xo_close_container_d();
```

Note that the XOF\_WARN flag will also cause **libxo** to track open containers, lists, and instances. A warning is generated when the name given to the close function and the name recorded do not match.

## SEE ALSO

[xo\_emit(3)](/xo_emit/3.md), [libxo(3)](/libxo/3.md)

## HISTORY

The **libxo** library first appeared in FreeBSD 11.0.

## AUTHORS

**libxo** was written by Phil Shafer ⟨*phil@freebsd.org*⟩.