# internal.h

Summary

internal.h |
Macros |
AUGEAS_LENS_DIR | The default location for lens definitions
AUGEAS_ROOT_ENV | The env var that points to the chroot holding files we may modify.
AUGEAS_FILES_TREE | The root for actual file contents
AUGEAS_META_TREE | Augeas reports some information in this subtree
AUGEAS_META_FILES | Information about files
AUGEAS_META_TEXT | Information about text (see aug_text_store and aug_text_retrieve)
AUGEAS_META_ROOT | The root directory
AUGEAS_META_SAVE_MODE | How we save files.
AUGEAS_CLONE_IF_RENAME_FAILS | Control what save does when renaming the temporary file to its final destination fails with EXDEV or EBUSY: when this tree node exists, copy the file contents.
AUGEAS_CONTEXT | Context prepended to all non-absolute paths
AUGEAS_SPAN_OPTION | Enable or disable node indexes
AUGEAS_LENS_ENV |
MAX_ENV_SIZE | Fairly arbitrary bound on the length of the path we accept from AUGEAS_SPEC_ENV
PATH_SEP_CHAR | Character separating paths in a list of paths
Functions |
escape | Escape nonprintable characters within TEXT, similar to how it’s done in C string literals.
unescape |
print_chars |
print_pos | Print a pretty representation of being at position POS within TEXT
xread_file | Read the contents of file PATH and return them as one long string.
augeas | The data structure representing a connection to Augeas.
tree | An entry in the global config tree.
Functions |
make_tree | Allocate a new tree node with the given LABEL, VALUE, and CHILDREN, which are not copied.
memstream | Wrappers to simulate OPEN_MEMSTREAM where that’s not available.
Functions |
init_memstream | Initialize a memstream.
close_memstream | Close a memstream.

### Macros

### AUGEAS_LENS_DIR

The default location for lens definitions

### AUGEAS_ROOT_ENV

The env var that points to the chroot holding files we may modify. Mostly useful for testing

### AUGEAS_FILES_TREE

The root for actual file contents

### AUGEAS_META_TREE

Augeas reports some information in this subtree

### AUGEAS_META_FILES

Information about files

### AUGEAS_META_TEXT

Information about text (see aug_text_store and aug_text_retrieve)

### AUGEAS_META_ROOT

The root directory

### AUGEAS_META_SAVE_MODE

How we save files. One of ‘backup’, ‘overwrite’ or ‘newfile’

### AUGEAS_CLONE_IF_RENAME_FAILS

Control what save does when renaming the temporary file to its final destination fails with EXDEV or EBUSY: when this tree node exists, copy the file contents. If it is not present, simply give up and report an error.

### AUGEAS_CONTEXT

Context prepended to all non-absolute paths

### AUGEAS_SPAN_OPTION

Enable or disable node indexes

### AUGEAS_LENS_ENV

- Name of env var that contains list of paths to search for additional spec files

### MAX_ENV_SIZE

Fairly arbitrary bound on the length of the path we accept from AUGEAS_SPEC_ENV

### PATH_SEP_CHAR

Character separating paths in a list of paths

### Functions

### escape

> char *escape( | const | char | * | text,
> |  | int |  | cnt,
> | const | char | * | extra | )

Escape nonprintable characters within TEXT, similar to how it’s done in C string literals. Caller must free the returned string.

### unescape

> char *unescape( | const | char | * | s,
> |  | int |  | len,
> | const | char | * | extra | )

### print_chars

> int print_chars( |  | FILE | * | out,
> | const | char | * | text,
> |  | int |  | cnt | )

### print_pos

> void print_pos( |  | FILE | * | out,
> | const | char | * | text,
> |  | int |  | pos | )

Print a pretty representation of being at position POS within TEXT

### xread_file

> char* xread_file( | const | char | * | path | )

Read the contents of file PATH and return them as one long string. The caller must free the result. Return NULL if any error occurs.

## augeas

> struct augeas

The data structure representing a connection to Augeas.

## tree

> struct tree

An entry in the global config tree. The data structure allows associating values with interior nodes, but the API currently marks that as an error.

To make dealing with parents uniform, even for the root, we create standalone trees with a fake root, called origin. That root is generally not referenced from anywhere. Standalone trees should be created with MAKE_TREE_ORIGIN.

The DIRTY flag is used to track which parts of the tree might need to be saved. For any node that is marked dirty, all of its ancestors must be marked dirty, too. Instead of setting this flag directly, the function TREE_MARK_DIRTY in augeas.c should be used (and only functions in that file should have a need to mark nodes as dirty)

The FILE flag is set for entries underneath /augeas/files that hold the metadata for a file by ADD_FILE_INFO. The FILE flag is set for entries underneath /files for the toplevel node corresponding to a file by TREE_FREPLACE and is used by AUG_SOURCE to find the file to which a node belongs.

Summary

Functions |
make_tree | Allocate a new tree node with the given LABEL, VALUE, and CHILDREN, which are not copied.

### Functions

### make_tree

> struct tree *make_tree( |  | char | * | label,
> |  | char | * | value,
> | struct | tree | * | parent,
> | struct | tree | * | children | )

Allocate a new tree node with the given LABEL, VALUE, and CHILDREN, which are not copied. The new tree is marked as dirty

## memstream

> struct memstream

Wrappers to simulate OPEN_MEMSTREAM where that’s not available. The STREAM member is opened by INIT_MEMSTREAM and closed by CLOSE_MEMSTREAM. The BUF is allocated automatically, but can not be used until after CLOSE_MEMSTREAM has been called. It is the callers responsibility to free up BUF.

Summary

Functions |
init_memstream | Initialize a memstream.
close_memstream | Close a memstream.

### Functions

### init_memstream

> int __aug_init_memstream( | struct | memstream | * | ms | )

Initialize a memstream. On systems that have OPEN_MEMSTREAM, it is used to open MS->STREAM. On systems without OPEN_MEMSTREAM, MS->STREAM is backed by a temporary file.

MS must be allocated in advance; INIT_MEMSTREAM initializes it.

### close_memstream

> int __aug_close_memstream( | struct | memstream | * | ms | )

Close a memstream. After calling this, MS->STREAM can not be used anymore and a string representing whatever was written to it is available in MS->BUF. The caller must free MS->BUF.

The caller must free the MEMSTREAM structure.

> char *escape( | const | char | * | text,
> |  | int |  | cnt,
> | const | char | * | extra | )

Escape nonprintable characters within TEXT, similar to how it’s done in C string literals.

> char *unescape( | const | char | * | s,
> |  | int |  | len,
> | const | char | * | extra | )

> int print_chars( |  | FILE | * | out,
> | const | char | * | text,
> |  | int |  | cnt | )

> void print_pos( |  | FILE | * | out,
> | const | char | * | text,
> |  | int |  | pos | )

Print a pretty representation of being at position POS within TEXT

> char* xread_file( | const | char | * | path | )

Read the contents of file PATH and return them as one long string.

> struct augeas

The data structure representing a connection to Augeas.

> struct tree

An entry in the global config tree.

> struct tree *make_tree( |  | char | * | label,
> |  | char | * | value,
> | struct | tree | * | parent,
> | struct | tree | * | children | )

Allocate a new tree node with the given LABEL, VALUE, and CHILDREN, which are not copied.

> struct memstream

Wrappers to simulate OPEN_MEMSTREAM where that’s not available.

> int __aug_init_memstream( | struct | memstream | * | ms | )

Initialize a memstream.

> int __aug_close_memstream( | struct | memstream | * | ms | )

Close a memstream.
Close