1.\" # 2.\" # Copyright (c) 2015, 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, January 2015 9.\" 10.Dd January 22, 2015 11.Dt LIBXO 3 12.Os 13.Sh NAME 14.Nm xo_open_marker , xo_open_marker_h , xo_close_marker , xo_close_marker_h 15.Nd prevent and allow closing of open constructs 16.Sh LIBRARY 17.Lb libxo 18.Sh SYNOPSIS 19.In libxo/xo.h 20.Ft int 21.Fn xo_open_marker "const char *name" 22.Ft int 23.Fn xo_open_marker_h "xo_handle_t *handle" "const char *name" 24.Ft int 25.Fn xo_close_marker "const char *name" 26.Ft int 27.Fn xo_close_marker_h "xo_handle_t *handle" "const char *name" 28.Sh DESCRIPTION 29.Nm libxo 30represents hierarchy using two constructs: 31.Dq containers 32and 33.Dq lists . 34A marker can be used to affect how open constructs are closed, either 35by preventing their (implicit or explicit) closure or by forcing their 36closure. 37While a marker is open, no other open constructs can be closed. 38When a marker is closed, all constructs open since the marker was opened 39will be closed. 40A marker is used to "freeze" any open constructs. 41Calls to 42.Fn xo_close_* 43functions that would normally close them will be ignored, effectively 44blocking their closure. 45However when 46.Fn xo_close_marker 47is called, any containers, lists, or leaf-lists open since the 48matching 49.Fn xo_open_marker 50call will be close and the marker discarded. 51Markers use names which are not user-visible, allowing the caller to 52choose appropriate internal names. 53The marker has no value and is not emitted in any form. 54.Pp 55To open a marker, call 56.Fn xo_open_marker 57or 58.Fn xo_open_marker_h . 59The former uses the default handle and 60the latter accepts a specific handle. 61.Pp 62To close a marker, use the 63.Fn xo_close_marker 64or 65.Fn xo_close_marker_h 66functions. 67.Pp 68Each open call must have a matching close call. 69.Pp 70In this example, the 71.Fn xo_close_container 72call on line [1] will be ignored, since the open marker "outer" 73will prevent close of any open constructs that precede it. 74The 75.Fn xo_close_marker 76call on line [2] will close the "system" container, since it was 77opened after the "outer" marker. 78.Bd -literal -offset indent -compact 79 Example: 80 81 xo_open_container("top"); 82 xo_open_marker("outer"); 83 xo_open_container("system"); 84 xo_emit("{:host-name/%s%s%s", hostname, 85 domainname ? "." : "", domainname ?: ""); 86 xo_close_container("top"); /* [1] */ 87 xo_close_marker("outer"); /* [2] */ 88 xo_close_container("top"); 89.Ed 90.Pp 91In this example, the code whiffles through a list of fish, calling a 92function to emit details about each fish. The marker "fish-guts" is 93used to ensure that any constructs opened by the function are closed 94properly. 95.Bd -literal -offset indent 96 for (i = 0; fish[i]; i++) { 97 xo_open_instance("fish"); 98 xo_open_marker("fish-guts"); 99 dump_fish_details(i); 100 xo_close_marker("fish-guts"); 101 } 102.Ed 103.Sh SEE ALSO 104.Xr xo_emit 3 , 105.Xr libxo 3 106