src/augeas.h

   1 /*
   2  * augeas.h: public headers for augeas
   3  *
   4  * Copyright (C) 2007-2015 David Lutterkort
   5  *
   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.
  10  *
  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.
  15  *
  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
  19  *
  20  * Author: David Lutterkort <dlutter@redhat.com>
  21  */
  22
  23 #include <stdio.h>
  24 #include <libxml/tree.h>
  25
  26 #ifndef AUGEAS_H_
  27 #define AUGEAS_H_
  28
  29 typedef struct augeas augeas;
  30
  31 /* Enum: aug_flags
  32  *
  33  * Flags to influence the behavior of Augeas. Pass a bitmask of these flags
  34  * to AUG_INIT.
  35  */
  36 enum aug_flags {
  37     AUG_NONE = 0,
  38     AUG_SAVE_BACKUP  = (1 << 0),  /* Keep the original file with a
  39                                      .augsave extension */
  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
  47                                      modules */
  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 */
  56 };
  57
  58 #ifdef __cplusplus
  59 extern "C" {
  60 #endif
  61
  62 /* Function: aug_init
  63  *
  64  * Initialize the library.
  65  *
  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 "/".
  68  *
  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
  72  *
  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.
  79  *
  80  * Returns:
  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.
  87  */
  88 augeas *aug_init(const char *root, const char *loadpath, unsigned int flags);
  89
  90 /* Function: aug_defvar
  91  *
  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.
  95  *
  96  * If EXPR is NULL, the variable NAME will be removed if it is defined.
  97  *
  98  * Path variables can be used in path expressions later on by prefixing
  99  * them with '$'.
 100  *
 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
 103  * nodeset
 104  */
 105 int aug_defvar(augeas *aug, const char *name, const char *expr);
 106
 107 /* Function: aug_defnode
 108  *
 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
 112  * EXPR.
 113  *
 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
 116  * that single node.
 117  *
 118  * If CREATED is non-NULL, it is set to 1 if a node was created, and 0 if
 119  * it already existed.
 120  *
 121  * Returns -1 on error; on success, returns the number of nodes in the
 122  * nodeset
 123  */
 124 int aug_defnode(augeas *aug, const char *name, const char *expr,
 125                 const char *value, int *created);
 126
 127 /* Function: aug_get
 128  *
 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.
 135  *
 136  * The string *VALUE must not be freed by the caller, and is valid as long
 137  * as its node remains unchanged.
 138  *
 139  * Returns:
 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.
 143  */
 144 int aug_get(const augeas *aug, const char *path, const char **value);
 145
 146 /* Function: aug_label
 147  *
 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.
 152  *
 153  * The string *LABEL must not be freed by the caller, and is valid as long
 154  * as its node remains unchanged.
 155  *
 156  * Returns:
 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.
 160  */
 161 int aug_label(const augeas *aug, const char *path, const char **label);
 162
 163 /* Function: aug_set
 164  *
 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.
 168  *
 169  * Returns:
 170  * 0 on success, -1 on error. It is an error if more than one node
 171  * matches PATH.
 172  */
 173 int aug_set(augeas *aug, const char *path, const char *value);
 174
 175 /* Function: aug_setm
 176  *
 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.
 181  *
 182  * Returns:
 183  * number of modified nodes on success, -1 on error
 184  */
 185 int aug_setm(augeas *aug, const char *base, const char *sub, const char *value);
 186
 187 /* Function: aug_span
 188  *
 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.
 196  *
 197  * Returns:
 198  * 0 on success with filename, label_start, label_stop, value_start, value_end,
 199  *   span_start, span_end
 200  * -1 on error
 201  */
 202
 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);
 207
 208 /* Function: aug_insert
 209  *
 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.
 212  *
 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
 215  * '[N]'.
 216  *
 217  * Returns:
 218  * 0 on success, and -1 if the insertion fails.
 219  */
 220 int aug_insert(augeas *aug, const char *path, const char *label, int before);
 221
 222 /* Function: aug_rm
 223  *
 224  * Remove path and all its children. Returns the number of entries removed.
 225  * All nodes that match PATH, and their descendants, are removed.
 226  */
 227 int aug_rm(augeas *aug, const char *path);
 228
 229 /* Function: aug_mv
 230  *
 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
 235  * created.
 236  *
 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
 239  * initially or not.
 240  *
 241  * Returns:
 242  * 0 on success and -1 on failure.
 243  */
 244 int aug_mv(augeas *aug, const char *src, const char *dst);
 245
 246 /* Function: aug_cp
 247  *
 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
 252  * created.
 253  *
 254  * Returns:
 255  * 0 on success and -1 on failure.
 256  */
 257 int aug_cp(augeas *aug, const char *src, const char *dst);
 258
 259 /* Function: aug_rename
 260  *
 261  * Rename the label of all nodes matching SRC to LBL.
 262  *
 263  * Returns:
 264  * The number of nodes renamed on success and -1 on failure.
 265  */
 266 int aug_rename(augeas *aug, const char *src, const char *lbl);
 267
 268 /* Function: aug_match
 269  *
 270  * Returns:
 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
 276  * the current tree.
 277  *
 278  * If MATCHES is NULL, nothing is allocated and only the number
 279  * of matches is returned.
 280  *
 281  * Returns -1 on error, or the total number of matches (which might be 0).
 282  *
 283  * Path expressions:
 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.
 294  *
 295  */
 296 int aug_match(const augeas *aug, const char *path, char ***matches);
 297
 298 /* Function: aug_save
 299  *
 300  * Write all pending changes to disk.
 301  *
 302  * Returns:
 303  * -1 if an error is encountered,
 304  * 0 on success. Only files that had any changes made to them are written.
 305  *
 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.
 309  *
 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".
 312  *
 313  * If neither of these flags is set, overwrite the original file.
 314  */
 315 int aug_save(augeas *aug);
 316
 317 /* Function: aug_load
 318  *
 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.
 324  *
 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.
 329  *
 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.
 334  *
 335  * When AUG_INIT is first called, it populates /augeas/load with the
 336  * transforms marked for autoloading in all the modules it finds.
 337  *
 338  * Before loading any files, AUG_LOAD will remove everything underneath
 339  * /augeas/files and /files, regardless of whether any entries have been
 340  * modified or not.
 341  *
 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'.
 345  */
 346 int aug_load(augeas *aug);
 347
 348 /* Function: aug_text_store
 349  *
 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.
 353  *
 354  * Returns:
 355  * 0 on success, or a negative value on failure
 356  */
 357 int aug_text_store(augeas *aug, const char *lens, const char *node,
 358                    const char *path);
 359
 360 /* Function: aug_text_retrieve
 361  *
 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.
 365  *
 366  * Returns:
 367  * 0 on success, or a negative value on failure
 368  */
 369 int aug_text_retrieve(struct augeas *aug, const char *lens,
 370                       const char *node_in, const char *path,
 371                       const char *node_out);
 372
 373 /* Function: aug_escape_name
 374  *
 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 '/',
 380  * too.
 381  *
 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.
 384  *
 385  * Returns:
 386  * 0 on success, or a negative value on failure
 387  */
 388 int aug_escape_name(augeas *aug, const char *in, char **out);
 389
 390 /* Function: aug_print
 391  *
 392  * Print each node matching PATH and its descendants to OUT.
 393  *
 394  * Returns:
 395  * 0 on success, or a negative value on failure
 396  */
 397 int aug_print(const augeas *aug, FILE *out, const char *path);
 398
 399 /* Function: aug_to_xml
 400  *
 401  * Turn the Augeas tree(s) matching PATH into an XML tree XMLDOC. The
 402  * parameter FLAGS is currently unused and must be set to 0.
 403  *
 404  * Returns:
 405  * 0 on success, or a negative value on failure
 406  *
 407  * In case of failure, *xmldoc is set to NULL
 408  */
 409 int aug_to_xml(const augeas *aug, const char *path, xmlNode **xmldoc,
 410                unsigned int flags);
 411
 412 /*
 413  * Function: aug_transform
 414  *
 415  * Add a transform for FILE using LENS.
 416  * EXCL specifies if this the file is to be included (0)
 417  * or excluded (1) from the LENS.
 418  * The LENS maybe be a module name or a full lens name.
 419  * If a module name is given, then lns will be the lens assumed.
 420  *
 421  * Returns:
 422  * 1 on success, -1 on failure
 423  */
 424 int aug_transform(augeas *aug, const char *lens, const char *file, int excl);
 425
 426 /*
 427  * Function: aug_load_file
 428  *
 429  * Load a FILE using the lens that would ordinarily be used by aug_load,
 430  * i.e. the lens whose autoload statement matches the FILE. Similar to
 431  * aug_load, this function returns successfully even if FILE does not exist
 432  * or if the FILE can not be processed by the associated lens. It is an
 433  * error though if no lens can be found to process FILE. In that case, the
 434  * error code in AUG will be set to AUG_ENOLENS.
 435  *
 436  * Returns:
 437  * 0 on success, -1 on failure
 438  */
 439 int aug_load_file(augeas *aug, const char *file);
 440
 441 /*
 442  * Function: aug_srun
 443  *
 444  * Run one or more newline-separated commands. The output of the commands
 445  * will be printed to OUT. Running just 'help' will print what commands are
 446  * available. Commands accepted by this are identical to what augtool
 447  * accepts.
 448  *
 449  * Returns:
 450  * the number of executed commands on success, -1 on failure, and -2 if a
 451  * 'quit' command was encountered
 452  */
 453 int aug_srun(augeas *aug, FILE *out, const char *text);
 454
 455 /* Function: aug_close
 456  *
 457  * Close this Augeas instance and free any storage associated with
 458  * it. After running AUG_CLOSE, AUG is invalid and can not be used for any
 459  * more operations.
 460  */
 461 void aug_close(augeas *aug);
 462
 463 /*
 464  * Error reporting
 465  */
 466
 467 typedef enum {
 468     AUG_NOERROR,        /* No error */
 469     AUG_ENOMEM,         /* Out of memory */
 470     AUG_EINTERNAL,      /* Internal error (bug) */
 471     AUG_EPATHX,         /* Invalid path expression */
 472     AUG_ENOMATCH,       /* No match for path expression */
 473     AUG_EMMATCH,        /* Too many matches for path expression */
 474     AUG_ESYNTAX,        /* Syntax error in lens file */
 475     AUG_ENOLENS,        /* Lens lookup failed */
 476     AUG_EMXFM,          /* Multiple transforms */
 477     AUG_ENOSPAN,        /* No span for this node */
 478     AUG_EMVDESC,        /* Cannot move node into its descendant */
 479     AUG_ECMDRUN,        /* Failed to execute command */
 480     AUG_EBADARG,        /* Invalid argument in funcion call */
 481     AUG_ELABEL,         /* Invalid label */
 482     AUG_ECPDESC         /* Cannot copy node into its descendant */
 483 } aug_errcode_t;
 484
 485 /* Return the error code from the last API call */
 486 int aug_error(augeas *aug);
 487
 488 /* Return a human-readable message for the error code */
 489 const char *aug_error_message(augeas *aug);
 490
 491 /* Return a human-readable message elaborating the error code; might be
 492  * NULL. For example, when the error code is AUG_EPATHX, this will explain
 493  * how the path expression is invalid */
 494 const char *aug_error_minor_message(augeas *aug);
 495
 496 /* Return details about the error, which might be NULL. For example, for
 497  * AUG_EPATHX, indicates where in the path expression the error
 498  * occurred. The returned value can only be used until the next API call
 499  */
 500 const char *aug_error_details(augeas *aug);
 501
 502
 503 #ifdef __cplusplus
 504 }
 505 #endif
 506
 507 #endif
 508
 509
 510 /*
 511  * Local variables:
 512  *  indent-tabs-mode: nil
 513  *  c-indent-level: 4
 514  *  c-basic-offset: 4
 515  *  tab-width: 4
 516  * End:
 517  */