Public API

This page gives a brief overview of the public API. More documentation can be found in the (yet to be written) man pages and in the include file augeas.h. That file declares the entire public API of Augeas.

Initializing and Closing Augeas
Reading and Writing Values
Inserting, Moving, Deleting and Searching Nodes
Saving the Tree

Initializing and Closing Augeas

Before calling any other Augeas function, you must obtain a handle from

augeas *aug_init(const char *root, const char *loadpath, unsigned int flags)

with arguments

ROOT: a file system path; all files loaded by Augeas are loaded underneath ROOT
LOADPATH: a colon separated list of directories; these directories are searched for schema definitions
FLAGS: a bitmask of AUG_FLAGS to control how Augeas saves modified files and whether the slower operations of the type checker should be performed

The call returns a pointer to a new AUGEAS structure on success; that structure must be passed to any other calls in the API. If initialization fails, the call returns NULL.

To free up resources associated with an AUGEAS structure, call

void aug_close(augeas *aug);

Reading and Writing Values

Get node value and node existance

int aug_get(augeas *aug, const char *path, const char **value)

Lookup the value associated with PATH. VALUE can be NULL, in which case it is ignored. If VALUE is not NULL, it is used to return a pointer to the value associated with PATH if PATH matches exactly one node. If PATH matches no nodes or more than one node, *VALUE is set to NULL. Note that it is perfectly legal for nodes to have a NULL value, and that that by itself does not indicate an error.

The string *VALUE must not be freed by the caller, and is valid as long as its node remains unchanged.

Return 1 if there is exactly one node matching PATH, 0 if there is none, and a negative value if there is more than one node matching PATH, or if PATH is not a legal path expression.

Set node value

int aug_set(augeas *aug, const char *path, const char *value)

Set the value associated with PATH to VALUE. VALUE is copied into the internal data structure, and the caller is responsible for freeing it. Intermediate entries are created if they don't exist.

Fails and returns -1 if path expression PATH matches more than one node. If no node exists for PATH, one is created, including intermediate nodes, and its value is set to VALUE, which may be NULL.

Set the value of multiple nodes

int aug_setm(augeas *aug, const char *base, const char *sub, const char *value)

Set the value of multiple nodes in one operation. Find or create a node matching SUB by interpreting SUB as a path expression relative to each node matching BASE. SUB may be NULL, in which case all the nodes matching BASE will be modified.

Returns the number of modified nodes on success, and -1 on error.

Inserting, Moving, Deleting and Searching Nodes

Inserting a node

int aug_insert(augeas *aug, const char *path, const char *label, int  before)

Insert a new sibling of path expression PATH with label LABEL before or after PATH, depending on BEFORE. PATH must match exactly one node in the tree.

Moving a subtree

int aug_mv(augeas *aug, const char *src, const char *dst)

Move the node SRC to DST. SRC must match exactly one node in the tree. DST must either match exactly one node in the tree, or may not exist yet. If DST exists already, it and all its descendants are deleted before moving SRC there. If DST does not exist yet, it and all its missing ancestors are created.

Note that the node SRC always becomes the node DST: when you move /a/b to /x, the node /a/b is now called /x, no matter whether /x existed initially or not.

Return 0 on success and -1 on failure.

Deleting nodes

int aug_rm(augeas *aug, const char *path)

Remove all nodes matching path expression PATH and all their children. Returns total number of nodes removed, or -1 if PATH is an invalid path expression.

Searching Nodes

int aug_match(augeas *aug, const char *path, char ***matches)

Find all nodes matching path expression PATH and return the number of matching nodes. If CHILDREN is not NULL, allocate a new array of strings and return it as *CHILDREN. The array is filled with path expressions matching exactly one of the nodes matched by PATH.

Saving the Tree

int aug_save(augeas *aug)

Save the parts of the tree that have been changed into their respective files. Return 0 on success and -1 on failure. When saving fails, details about errors can be found in nodes matching /augeas//error.

Only files that have actually changed will be written - for example, setting a node to the same value it already had will not result in any file changes. In other words, there is no way to 'touch' a file with Augeas.

Augeas tries to be as safe as possible when saving files; in particular, it will try and write the new file contents into a temporary file with extension .augnew and move that file into the right place after writing the entire file succeeded using rename(2). In some cases, for example when the original file is bind-mounted, that is not possible, and Augeas will fall back to overwriting the file in place. Note that Augeas writes the tree out file-by-file, so that it is still possible that writing some files succeeds while writing others fails.

The exact behavior of aug_save can be fine-tuned by modifying the node /augeas/save prior to calling aug_save. The valid values for this node are

overwrite: Overwrite files in place
backup: Save the original file with the extension .augorig and write the new file under the original file name
newfile: Write the modified file into a file with extension .augnew without modifying the original file
noop: Perform all the steps necessary for a file, including generating the contents of files from the tree, but do not make any changes in the filesystem. This mode is very useful for making sure that all changes can be saved without error, and to find out which files would actually be modified.

After calling aug_save, the list of files that has been changed can be found in the nodes /augeas/events/saved.

Getting the span of a node related to a file

int aug_span(augeas *aug, const char *path, char **filename,
      unsigned int *label_start, unsigned int *label_end,
      unsigned int *value_start, unsigned int *value_end,
      unsigned int *span_start, unsigned int *span_end)

Get the span according to input file of the node associated with PATH. If the node is associated with a file, the filename, label and value start and end positions are set, and return value is 0. The caller is responsible for freeing returned filename. If an argument for return value is NULL, then the corresponding value is not set. If the node associated with PATH doesn't belong to a file or is doesn't exists, filename and span are not set and return value is -1.