2 * augeas.h: public headers for augeas
4 * Copyright (C) 2007-2016 David Lutterkort
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, write to the Free Software
18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20 * Author: David Lutterkort <dlutter@redhat.com>
24 #include <libxml/tree.h>
29 typedef struct augeas augeas;
33 * Flags to influence the behavior of Augeas. Pass a bitmask of these flags
38 AUG_SAVE_BACKUP = (1 << 0), /* Keep the original file with a
40 AUG_SAVE_NEWFILE = (1 << 1), /* Save changes into a file with
41 extension .augnew, and do not
42 overwrite the original file. Takes
43 precedence over AUG_SAVE_BACKUP */
44 AUG_TYPE_CHECK = (1 << 2), /* Typecheck lenses; since it can be very
45 expensive it is not done by default */
46 AUG_NO_STDINC = (1 << 3), /* Do not use the builtin load path for
48 AUG_SAVE_NOOP = (1 << 4), /* Make save a no-op process, just record
49 what would have changed */
50 AUG_NO_LOAD = (1 << 5), /* Do not load the tree from AUG_INIT */
51 AUG_NO_MODL_AUTOLOAD = (1 << 6),
52 AUG_ENABLE_SPAN = (1 << 7), /* Track the span in the input of nodes */
53 AUG_NO_ERR_CLOSE = (1 << 8), /* Do not close automatically when
54 encountering error during aug_init */
55 AUG_TRACE_MODULE_LOADING = (1 << 9) /* For use by augparse -t */
64 * Initialize the library.
66 * Use ROOT as the filesystem root. If ROOT is NULL, use the value of the
67 * environment variable AUGEAS_ROOT. If that doesn't exist eitehr, use "/".
69 * LOADPATH is a colon-spearated list of directories that modules should be
70 * searched in. This is in addition to the standard load path and the
71 * directories in AUGEAS_LENS_LIB
73 * FLAGS is a bitmask made up of values from AUG_FLAGS. The flag
74 * AUG_NO_ERR_CLOSE can be used to get more information on why
75 * initialization failed. If it is set in FLAGS, the caller must check that
76 * aug_error returns AUG_NOERROR before using the returned augeas handle
77 * for any other operation. If the handle reports any error, the caller
78 * should only call the aug_error functions an aug_close on this handle.
81 * a handle to the Augeas tree upon success. If initialization fails,
82 * returns NULL if AUG_NO_ERR_CLOSE is not set in FLAGS. If
83 * AUG_NO_ERR_CLOSE is set, might return an Augeas handle even on
84 * failure. In that case, caller must check for errors using augeas_error,
85 * and, if an error is reported, only use the handle with the aug_error
86 * functions and aug_close.
88 augeas *aug_init(const char *root, const char *loadpath, unsigned int flags);
90 /* Function: aug_defvar
92 * Define a variable NAME whose value is the result of evaluating EXPR. If
93 * a variable NAME already exists, its name will be replaced with the
94 * result of evaluating EXPR. Context will not be applied to EXPR.
96 * If EXPR is NULL, the variable NAME will be removed if it is defined.
98 * Path variables can be used in path expressions later on by prefixing
101 * Returns -1 on error; on success, returns 0 if EXPR evaluates to anything
102 * other than a nodeset, and the number of nodes if EXPR evaluates to a
105 int aug_defvar(augeas *aug, const char *name, const char *expr);
107 /* Function: aug_defnode
109 * Define a variable NAME whose value is the result of evaluating EXPR,
110 * which must be non-NULL and evaluate to a nodeset. If a variable NAME
111 * already exists, its name will be replaced with the result of evaluating
114 * If EXPR evaluates to an empty nodeset, a node is created, equivalent to
115 * calling AUG_SET(AUG, EXPR, VALUE) and NAME will be the nodeset containing
118 * If CREATED is non-NULL, it is set to 1 if a node was created, and 0 if
119 * it already existed.
121 * Returns -1 on error; on success, returns the number of nodes in the
124 int aug_defnode(augeas *aug, const char *name, const char *expr,
125 const char *value, int *created);
129 * Lookup the value associated with PATH. VALUE can be NULL, in which case
130 * it is ignored. If VALUE is not NULL, it is used to return a pointer to
131 * the value associated with PATH if PATH matches exactly one node. If PATH
132 * matches no nodes or more than one node, *VALUE is set to NULL. Note that
133 * it is perfectly legal for nodes to have a NULL value, and that that by
134 * itself does not indicate an error.
136 * The string *VALUE must not be freed by the caller, and is valid as long
137 * as its node remains unchanged.
140 * 1 if there is exactly one node matching PATH, 0 if there is none,
141 * and a negative value if there is more than one node matching PATH, or if
142 * PATH is not a legal path expression.
144 int aug_get(const augeas *aug, const char *path, const char **value);
146 /* Function: aug_label
148 * Lookup the label associated with PATH. LABEL can be NULL, in which case
149 * it is ignored. If LABEL is not NULL, it is used to return a pointer to
150 * the value associated with PATH if PATH matches exactly one node. If PATH
151 * matches no nodes or more than one node, *LABEL is set to NULL.
153 * The string *LABEL must not be freed by the caller, and is valid as long
154 * as its node remains unchanged.
157 * 1 if there is exactly one node matching PATH, 0 if there is none,
158 * and a negative value if there is more than one node matching PATH, or if
159 * PATH is not a legal path expression.
161 int aug_label(const augeas *aug, const char *path, const char **label);
165 * Set the value associated with PATH to VALUE. VALUE is copied into the
166 * internal data structure, and the caller is responsible for freeing
167 * it. Intermediate entries are created if they don't exist.
170 * 0 on success, -1 on error. It is an error if more than one node
173 int aug_set(augeas *aug, const char *path, const char *value);
175 /* Function: aug_setm
177 * Set the value of multiple nodes in one operation. Find or create a node
178 * matching SUB by interpreting SUB as a path expression relative to each
179 * node matching BASE. SUB may be NULL, in which case all the nodes
180 * matching BASE will be modified.
183 * number of modified nodes on success, -1 on error
185 int aug_setm(augeas *aug, const char *base, const char *sub, const char *value);
187 /* Function: aug_span
189 * Get the span according to input file of the node associated with PATH. If
190 * the node is associated with a file, the filename, label and value start and
191 * end positions are set, and return value is 0. The caller is responsible for
192 * freeing returned filename. If an argument for return value is NULL, then the
193 * corresponding value is not set. If the node associated with PATH doesn't
194 * belong to a file or is doesn't exists, filename and span are not set and
195 * return value is -1.
198 * 0 on success with filename, label_start, label_stop, value_start, value_end,
199 * span_start, span_end
203 int aug_span(augeas *aug, const char *path, char **filename,
204 unsigned int *label_start, unsigned int *label_end,
205 unsigned int *value_start, unsigned int *value_end,
206 unsigned int *span_start, unsigned int *span_end);
208 /* Function: aug_insert
210 * Create a new sibling LABEL for PATH by inserting into the tree just
211 * before PATH if BEFORE == 1 or just after PATH if BEFORE == 0.
213 * PATH must match exactly one existing node in the tree, and LABEL must be
214 * a label, i.e. not contain a '/', '*' or end with a bracketed index
218 * 0 on success, and -1 if the insertion fails.
220 int aug_insert(augeas *aug, const char *path, const char *label, int before);
224 * Remove path and all its children. Returns the number of entries removed.
225 * All nodes that match PATH, and their descendants, are removed.
227 int aug_rm(augeas *aug, const char *path);
231 * Move the node SRC to DST. SRC must match exactly one node in the
232 * tree. DST must either match exactly one node in the tree, or may not
233 * exist yet. If DST exists already, it and all its descendants are
234 * deleted. If DST does not exist yet, it and all its missing ancestors are
237 * Note that the node SRC always becomes the node DST: when you move /a/b
238 * to /x, the node /a/b is now called /x, no matter whether /x existed
242 * 0 on success and -1 on failure.
244 int aug_mv(augeas *aug, const char *src, const char *dst);
248 * Copy the node SRC to DST. SRC must match exactly one node in the
249 * tree. DST must either match exactly one node in the tree, or may not
250 * exist yet. If DST exists already, it and all its descendants are
251 * deleted. If DST does not exist yet, it and all its missing ancestors are
255 * 0 on success and -1 on failure.
257 int aug_cp(augeas *aug, const char *src, const char *dst);
259 /* Function: aug_rename
261 * Rename the label of all nodes matching SRC to LBL.
264 * The number of nodes renamed on success and -1 on failure.
266 int aug_rename(augeas *aug, const char *src, const char *lbl);
268 /* Function: aug_match
271 * the number of matches of the path expression PATH in AUG. If
272 * MATCHES is non-NULL, an array with the returned number of elements will
273 * be allocated and filled with the paths of the matches. The caller must
274 * free both the array and the entries in it. The returned paths are
275 * sufficiently qualified to make sure that they match exactly one node in
278 * If MATCHES is NULL, nothing is allocated and only the number
279 * of matches is returned.
281 * Returns -1 on error, or the total number of matches (which might be 0).
284 * Path expressions use a very simple subset of XPath: the path PATH
285 * consists of a number of segments, separated by '/'; each segment can
286 * either be a '*', matching any tree node, or a string, optionally
287 * followed by an index in brackets, matching tree nodes labelled with
288 * exactly that string. If no index is specified, the expression matches
289 * all nodes with that label; the index can be a positive number N, which
290 * matches exactly the Nth node with that label (counting from 1), or the
291 * special expression 'last()' which matches the last node with the given
292 * label. All matches are done in fixed positions in the tree, and nothing
293 * matches more than one path segment.
296 int aug_match(const augeas *aug, const char *path, char ***matches);
298 /* Function: aug_save
300 * Write all pending changes to disk.
303 * -1 if an error is encountered,
304 * 0 on success. Only files that had any changes made to them are written.
306 * If AUG_SAVE_NEWFILE is set in the FLAGS passed to AUG_INIT, create
307 * changed files as new files with the extension ".augnew", and leave the
308 * original file unmodified.
310 * Otherwise, if AUG_SAVE_BACKUP is set in the FLAGS passed to AUG_INIT,
311 * move the original file to a new file with extension ".augsave".
313 * If neither of these flags is set, overwrite the original file.
315 int aug_save(augeas *aug);
317 /* Function: aug_load
319 * Load files into the tree. Which files to load and what lenses to use on
320 * them is specified under /augeas/load in the tree; each entry
321 * /augeas/load/NAME specifies a 'transform', by having itself exactly one
322 * child 'lens' and any number of children labelled 'incl' and 'excl'. The
323 * value of NAME has no meaning.
325 * The 'lens' grandchild of /augeas/load specifies which lens to use, and
326 * can either be the fully qualified name of a lens 'Module.lens' or
327 * '@Module'. The latter form means that the lens from the transform marked
328 * for autoloading in MODULE should be used.
330 * The 'incl' and 'excl' grandchildren of /augeas/load indicate which files
331 * to transform. Their value are used as glob patterns. Any file that
332 * matches at least one 'incl' pattern and no 'excl' pattern is
333 * transformed. The order of 'incl' and 'excl' entries is irrelevant.
335 * When AUG_INIT is first called, it populates /augeas/load with the
336 * transforms marked for autoloading in all the modules it finds.
338 * Before loading any files, AUG_LOAD will remove everything underneath
339 * /augeas/files and /files, regardless of whether any entries have been
342 * Returns -1 on error, 0 on success. Note that success includes the case
343 * where some files could not be loaded. Details of such files can be found
344 * as '/augeas//error'.
346 int aug_load(augeas *aug);
348 /* Function: aug_text_store
350 * Use the value of node NODE as a string and transform it into a tree
351 * using the lens LENS and store it in the tree at PATH, which will be
352 * overwritten. PATH and NODE are path expressions.
355 * 0 on success, or a negative value on failure
357 int aug_text_store(augeas *aug, const char *lens, const char *node,
360 /* Function: aug_text_retrieve
362 * Transform the tree at PATH into a string using lens LENS and store it in
363 * the node NODE_OUT, assuming the tree was initially generated using the
364 * value of node NODE_IN. PATH, NODE_IN, and NODE_OUT are path expressions.
367 * 0 on success, or a negative value on failure
369 int aug_text_retrieve(struct augeas *aug, const char *lens,
370 const char *node_in, const char *path,
371 const char *node_out);
373 /* Function: aug_escape_name
375 * Escape special characters in a string such that it can be used as part
376 * of a path expressions and only matches a node named exactly
377 * IN. Characters that have special meanings in path expressions, such as
378 * '[' and ']' are prefixed with a '\\'. Note that this function assumes
379 * that it is passed a name, not a path, and will therefore escape '/',
382 * On return, *OUT is NULL if IN does not need any escaping at all, and
383 * points to an escaped copy of IN otherwise.
386 * 0 on success, or a negative value on failure
388 int aug_escape_name(augeas *aug, const char *in, char **out);
390 /* Function: aug_print
392 * Print each node matching PATH and its descendants to OUT.
395 * 0 on success, or a negative value on failure
397 int aug_print(const augeas *aug, FILE *out, const char *path);
399 /* Function: aug_source
401 * For the node matching PATH, return the path to the node representing the
402 * file to which PATH belongs. If PATH belongs to a file, *FILE_PATH will
403 * contain the path to the toplevel node of that file underneath /files. If
404 * it does not, *FILE_PATH will be NULL.
407 * 0 on success, or a negative value on failure. It is an error if PATH
408 * matches more than one node.
410 int aug_source(const augeas *aug, const char *path, char **file_path);
412 /* Function: aug_to_xml
414 * Turn the Augeas tree(s) matching PATH into an XML tree XMLDOC. The
415 * parameter FLAGS is currently unused and must be set to 0.
418 * 0 on success, or a negative value on failure
420 * In case of failure, *xmldoc is set to NULL
422 int aug_to_xml(const augeas *aug, const char *path, xmlNode **xmldoc,
426 * Function: aug_transform
428 * Add a transform for FILE using LENS.
429 * EXCL specifies if this the file is to be included (0)
430 * or excluded (1) from the LENS.
431 * The LENS maybe be a module name or a full lens name.
432 * If a module name is given, then lns will be the lens assumed.
435 * 1 on success, -1 on failure
437 int aug_transform(augeas *aug, const char *lens, const char *file, int excl);
440 * Function: aug_load_file
442 * Load a FILE using the lens that would ordinarily be used by aug_load,
443 * i.e. the lens whose autoload statement matches the FILE. Similar to
444 * aug_load, this function returns successfully even if FILE does not exist
445 * or if the FILE can not be processed by the associated lens. It is an
446 * error though if no lens can be found to process FILE. In that case, the
447 * error code in AUG will be set to AUG_ENOLENS.
450 * 0 on success, -1 on failure
452 int aug_load_file(augeas *aug, const char *file);
457 * Run one or more newline-separated commands. The output of the commands
458 * will be printed to OUT. Running just 'help' will print what commands are
459 * available. Commands accepted by this are identical to what augtool
463 * the number of executed commands on success, -1 on failure, and -2 if a
464 * 'quit' command was encountered
466 int aug_srun(augeas *aug, FILE *out, const char *text);
468 /* Function: aug_close
470 * Close this Augeas instance and free any storage associated with
471 * it. After running AUG_CLOSE, AUG is invalid and can not be used for any
474 void aug_close(augeas *aug);
481 AUG_NOERROR, /* No error */
482 AUG_ENOMEM, /* Out of memory */
483 AUG_EINTERNAL, /* Internal error (bug) */
484 AUG_EPATHX, /* Invalid path expression */
485 AUG_ENOMATCH, /* No match for path expression */
486 AUG_EMMATCH, /* Too many matches for path expression */
487 AUG_ESYNTAX, /* Syntax error in lens file */
488 AUG_ENOLENS, /* Lens lookup failed */
489 AUG_EMXFM, /* Multiple transforms */
490 AUG_ENOSPAN, /* No span for this node */
491 AUG_EMVDESC, /* Cannot move node into its descendant */
492 AUG_ECMDRUN, /* Failed to execute command */
493 AUG_EBADARG, /* Invalid argument in funcion call */
494 AUG_ELABEL, /* Invalid label */
495 AUG_ECPDESC /* Cannot copy node into its descendant */
498 /* Return the error code from the last API call */
499 int aug_error(augeas *aug);
501 /* Return a human-readable message for the error code */
502 const char *aug_error_message(augeas *aug);
504 /* Return a human-readable message elaborating the error code; might be
505 * NULL. For example, when the error code is AUG_EPATHX, this will explain
506 * how the path expression is invalid */
507 const char *aug_error_minor_message(augeas *aug);
509 /* Return details about the error, which might be NULL. For example, for
510 * AUG_EPATHX, indicates where in the path expression the error
511 * occurred. The returned value can only be used until the next API call
513 const char *aug_error_details(augeas *aug);
525 * indent-tabs-mode: nil