1 /* 2 * augeas.h: public headers for augeas 3 * 4 * Copyright (C) 2007-2016 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-separated 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. LOADPATH can be NULL, indicating that 72 * nothing should be added to the load path. 73 * 74 * FLAGS is a bitmask made up of values from AUG_FLAGS. The flag 75 * AUG_NO_ERR_CLOSE can be used to get more information on why 76 * initialization failed. If it is set in FLAGS, the caller must check that 77 * aug_error returns AUG_NOERROR before using the returned augeas handle 78 * for any other operation. If the handle reports any error, the caller 79 * should only call the aug_error functions an aug_close on this handle. 80 * 81 * Returns: 82 * a handle to the Augeas tree upon success. If initialization fails, 83 * returns NULL if AUG_NO_ERR_CLOSE is not set in FLAGS. If 84 * AUG_NO_ERR_CLOSE is set, might return an Augeas handle even on 85 * failure. In that case, caller must check for errors using augeas_error, 86 * and, if an error is reported, only use the handle with the aug_error 87 * functions and aug_close. 88 */ 89 augeas *aug_init(const char *root, const char *loadpath, unsigned int flags); 90 91 /* Function: aug_defvar 92 * 93 * Define a variable NAME whose value is the result of evaluating EXPR. If 94 * a variable NAME already exists, its name will be replaced with the 95 * result of evaluating EXPR. Context will not be applied to EXPR. 96 * 97 * If EXPR is NULL, the variable NAME will be removed if it is defined. 98 * 99 * Path variables can be used in path expressions later on by prefixing 100 * them with '$'. 101 * 102 * Returns -1 on error; on success, returns 0 if EXPR evaluates to anything 103 * other than a nodeset, and the number of nodes if EXPR evaluates to a 104 * nodeset 105 */ 106 int aug_defvar(augeas *aug, const char *name, const char *expr); 107 108 /* Function: aug_defnode 109 * 110 * Define a variable NAME whose value is the result of evaluating EXPR, 111 * which must be non-NULL and evaluate to a nodeset. If a variable NAME 112 * already exists, its name will be replaced with the result of evaluating 113 * EXPR. 114 * 115 * If EXPR evaluates to an empty nodeset, a node is created, equivalent to 116 * calling AUG_SET(AUG, EXPR, VALUE) and NAME will be the nodeset containing 117 * that single node. 118 * 119 * If CREATED is non-NULL, it is set to 1 if a node was created, and 0 if 120 * it already existed. 121 * 122 * Returns -1 on error; on success, returns the number of nodes in the 123 * nodeset 124 */ 125 int aug_defnode(augeas *aug, const char *name, const char *expr, 126 const char *value, int *created); 127 128 /* Function: aug_get 129 * 130 * Lookup the value associated with PATH. VALUE can be NULL, in which case 131 * it is ignored. If VALUE is not NULL, it is used to return a pointer to 132 * the value associated with PATH if PATH matches exactly one node. If PATH 133 * matches no nodes or more than one node, *VALUE is set to NULL. Note that 134 * it is perfectly legal for nodes to have a NULL value, and that that by 135 * itself does not indicate an error. 136 * 137 * The string *VALUE must not be freed by the caller, and is valid as long 138 * as its node remains unchanged. 139 * 140 * Returns: 141 * 1 if there is exactly one node matching PATH, 0 if there is none, 142 * and a negative value if there is more than one node matching PATH, or if 143 * PATH is not a legal path expression. 144 */ 145 int aug_get(const augeas *aug, const char *path, const char **value); 146 147 /* Function: aug_label 148 * 149 * Lookup the label associated with PATH. LABEL can be NULL, in which case 150 * it is ignored. If LABEL is not NULL, it is used to return a pointer to 151 * the value associated with PATH if PATH matches exactly one node. If PATH 152 * matches no nodes or more than one node, *LABEL is set to NULL. 153 * 154 * The string *LABEL must not be freed by the caller, and is valid as long 155 * as its node remains unchanged. 156 * 157 * Returns: 158 * 1 if there is exactly one node matching PATH, 0 if there is none, 159 * and a negative value if there is more than one node matching PATH, or if 160 * PATH is not a legal path expression. 161 */ 162 int aug_label(const augeas *aug, const char *path, const char **label); 163 164 /* Function: aug_set 165 * 166 * Set the value associated with PATH to VALUE. VALUE is copied into the 167 * internal data structure, and the caller is responsible for freeing 168 * it. Intermediate entries are created if they don't exist. 169 * 170 * Returns: 171 * 0 on success, -1 on error. It is an error if more than one node 172 * matches PATH. 173 */ 174 int aug_set(augeas *aug, const char *path, const char *value); 175 176 /* Function: aug_setm 177 * 178 * Set the value of multiple nodes in one operation. Find or create a node 179 * matching SUB by interpreting SUB as a path expression relative to each 180 * node matching BASE. SUB may be NULL, in which case all the nodes 181 * matching BASE will be modified. 182 * 183 * Returns: 184 * number of modified nodes on success, -1 on error 185 */ 186 int aug_setm(augeas *aug, const char *base, const char *sub, const char *value); 187 188 /* Function: aug_span 189 * 190 * Get the span according to input file of the node associated with PATH. If 191 * the node is associated with a file, the filename, label and value start and 192 * end positions are set, and return value is 0. The caller is responsible for 193 * freeing returned filename. If an argument for return value is NULL, then the 194 * corresponding value is not set. If the node associated with PATH doesn't 195 * belong to a file or is doesn't exists, filename and span are not set and 196 * return value is -1. 197 * 198 * Returns: 199 * 0 on success with filename, label_start, label_stop, value_start, value_end, 200 * span_start, span_end 201 * -1 on error 202 */ 203 204 int aug_span(augeas *aug, const char *path, char **filename, 205 unsigned int *label_start, unsigned int *label_end, 206 unsigned int *value_start, unsigned int *value_end, 207 unsigned int *span_start, unsigned int *span_end); 208 209 /* Function: aug_insert 210 * 211 * Create a new sibling LABEL for PATH by inserting into the tree just 212 * before PATH if BEFORE == 1 or just after PATH if BEFORE == 0. 213 * 214 * PATH must match exactly one existing node in the tree, and LABEL must be 215 * a label, i.e. not contain a '/', '*' or end with a bracketed index 216 * '[N]'. 217 * 218 * Returns: 219 * 0 on success, and -1 if the insertion fails. 220 */ 221 int aug_insert(augeas *aug, const char *path, const char *label, int before); 222 223 /* Function: aug_rm 224 * 225 * Remove path and all its children. Returns the number of entries removed. 226 * All nodes that match PATH, and their descendants, are removed. 227 */ 228 int aug_rm(augeas *aug, const char *path); 229 230 /* Function: aug_mv 231 * 232 * Move the node SRC to DST. SRC must match exactly one node in the 233 * tree. DST must either match exactly one node in the tree, or may not 234 * exist yet. If DST exists already, it and all its descendants are 235 * deleted. If DST does not exist yet, it and all its missing ancestors are 236 * created. 237 * 238 * Note that the node SRC always becomes the node DST: when you move /a/b 239 * to /x, the node /a/b is now called /x, no matter whether /x existed 240 * initially or not. 241 * 242 * Returns: 243 * 0 on success and -1 on failure. 244 */ 245 int aug_mv(augeas *aug, const char *src, const char *dst); 246 247 /* Function: aug_cp 248 * 249 * Copy the node SRC to DST. SRC must match exactly one node in the 250 * tree. DST must either match exactly one node in the tree, or may not 251 * exist yet. If DST exists already, it and all its descendants are 252 * deleted. If DST does not exist yet, it and all its missing ancestors are 253 * created. 254 * 255 * Returns: 256 * 0 on success and -1 on failure. 257 */ 258 int aug_cp(augeas *aug, const char *src, const char *dst); 259 260 /* Function: aug_rename 261 * 262 * Rename the label of all nodes matching SRC to LBL. 263 * 264 * Returns: 265 * The number of nodes renamed on success and -1 on failure. 266 */ 267 int aug_rename(augeas *aug, const char *src, const char *lbl); 268 269 /* Function: aug_match 270 * 271 * Returns: 272 * the number of matches of the path expression PATH in AUG. If 273 * MATCHES is non-NULL, an array with the returned number of elements will 274 * be allocated and filled with the paths of the matches. The caller must 275 * free both the array and the entries in it. The returned paths are 276 * sufficiently qualified to make sure that they match exactly one node in 277 * the current tree. 278 * 279 * If MATCHES is NULL, nothing is allocated and only the number 280 * of matches is returned. 281 * 282 * Returns -1 on error, or the total number of matches (which might be 0). 283 * 284 * Path expressions: 285 * Path expressions use a very simple subset of XPath: the path PATH 286 * consists of a number of segments, separated by '/'; each segment can 287 * either be a '*', matching any tree node, or a string, optionally 288 * followed by an index in brackets, matching tree nodes labelled with 289 * exactly that string. If no index is specified, the expression matches 290 * all nodes with that label; the index can be a positive number N, which 291 * matches exactly the Nth node with that label (counting from 1), or the 292 * special expression 'last()' which matches the last node with the given 293 * label. All matches are done in fixed positions in the tree, and nothing 294 * matches more than one path segment. 295 * 296 */ 297 int aug_match(const augeas *aug, const char *path, char ***matches); 298 299 /* Function: aug_save 300 * 301 * Write all pending changes to disk. 302 * 303 * Returns: 304 * -1 if an error is encountered, 305 * 0 on success. Only files that had any changes made to them are written. 306 * 307 * If AUG_SAVE_NEWFILE is set in the FLAGS passed to AUG_INIT, create 308 * changed files as new files with the extension ".augnew", and leave the 309 * original file unmodified. 310 * 311 * Otherwise, if AUG_SAVE_BACKUP is set in the FLAGS passed to AUG_INIT, 312 * move the original file to a new file with extension ".augsave". 313 * 314 * If neither of these flags is set, overwrite the original file. 315 */ 316 int aug_save(augeas *aug); 317 318 /* Function: aug_load 319 * 320 * Load files into the tree. Which files to load and what lenses to use on 321 * them is specified under /augeas/load in the tree; each entry 322 * /augeas/load/NAME specifies a 'transform', by having itself exactly one 323 * child 'lens' and any number of children labelled 'incl' and 'excl'. The 324 * value of NAME has no meaning. 325 * 326 * The 'lens' grandchild of /augeas/load specifies which lens to use, and 327 * can either be the fully qualified name of a lens 'Module.lens' or 328 * '@Module'. The latter form means that the lens from the transform marked 329 * for autoloading in MODULE should be used. 330 * 331 * The 'incl' and 'excl' grandchildren of /augeas/load indicate which files 332 * to transform. Their value are used as glob patterns. Any file that 333 * matches at least one 'incl' pattern and no 'excl' pattern is 334 * transformed. The order of 'incl' and 'excl' entries is irrelevant. 335 * 336 * When AUG_INIT is first called, it populates /augeas/load with the 337 * transforms marked for autoloading in all the modules it finds. 338 * 339 * Before loading any files, AUG_LOAD will remove everything underneath 340 * /augeas/files and /files, regardless of whether any entries have been 341 * modified or not. 342 * 343 * Returns -1 on error, 0 on success. Note that success includes the case 344 * where some files could not be loaded. Details of such files can be found 345 * as '/augeas//error'. 346 */ 347 int aug_load(augeas *aug); 348 349 /* Function: aug_text_store 350 * 351 * Use the value of node NODE as a string and transform it into a tree 352 * using the lens LENS and store it in the tree at PATH, which will be 353 * overwritten. PATH and NODE are path expressions. 354 * 355 * Returns: 356 * 0 on success, or a negative value on failure 357 */ 358 int aug_text_store(augeas *aug, const char *lens, const char *node, 359 const char *path); 360 361 /* Function: aug_text_retrieve 362 * 363 * Transform the tree at PATH into a string using lens LENS and store it in 364 * the node NODE_OUT, assuming the tree was initially generated using the 365 * value of node NODE_IN. PATH, NODE_IN, and NODE_OUT are path expressions. 366 * 367 * Returns: 368 * 0 on success, or a negative value on failure 369 */ 370 int aug_text_retrieve(struct augeas *aug, const char *lens, 371 const char *node_in, const char *path, 372 const char *node_out); 373 374 /* Function: aug_escape_name 375 * 376 * Escape special characters in a string such that it can be used as part 377 * of a path expressions and only matches a node named exactly 378 * IN. Characters that have special meanings in path expressions, such as 379 * '[' and ']' are prefixed with a '\\'. Note that this function assumes 380 * that it is passed a name, not a path, and will therefore escape '/', 381 * too. 382 * 383 * On return, *OUT is NULL if IN does not need any escaping at all, and 384 * points to an escaped copy of IN otherwise. 385 * 386 * Returns: 387 * 0 on success, or a negative value on failure 388 */ 389 int aug_escape_name(augeas *aug, const char *in, char **out); 390 391 /* Function: aug_print 392 * 393 * Print each node matching PATH and its descendants to OUT. 394 * 395 * Returns: 396 * 0 on success, or a negative value on failure 397 */ 398 int aug_print(const augeas *aug, FILE *out, const char *path); 399 400 /* Function: aug_source 401 * 402 * For the node matching PATH, return the path to the node representing the 403 * file to which PATH belongs. If PATH belongs to a file, *FILE_PATH will 404 * contain the path to the toplevel node of that file underneath /files. If 405 * it does not, *FILE_PATH will be NULL. 406 * 407 * The caller is responsible for freeing *FILE_PATH 408 * 409 * Returns: 410 * 0 on success, or a negative value on failure. It is an error if PATH 411 * matches more than one node. 412 */ 413 int aug_source(const augeas *aug, const char *path, char **file_path); 414 415 /* Function: aug_to_xml 416 * 417 * Turn the Augeas tree(s) matching PATH into an XML tree XMLDOC. The 418 * parameter FLAGS is currently unused and must be set to 0. 419 * 420 * Returns: 421 * 0 on success, or a negative value on failure 422 * 423 * In case of failure, *xmldoc is set to NULL 424 */ 425 int aug_to_xml(const augeas *aug, const char *path, xmlNode **xmldoc, 426 unsigned int flags); 427 428 /* 429 * Function: aug_transform 430 * 431 * Add a transform for FILE using LENS. 432 * EXCL specifies if this the file is to be included (0) 433 * or excluded (1) from the LENS. 434 * The LENS maybe be a module name or a full lens name. 435 * If a module name is given, then lns will be the lens assumed. 436 * 437 * Returns: 438 * 1 on success, -1 on failure 439 */ 440 int aug_transform(augeas *aug, const char *lens, const char *file, int excl); 441 442 /* 443 * Function: aug_load_file 444 * 445 * Load a FILE using the lens that would ordinarily be used by aug_load, 446 * i.e. the lens whose autoload statement matches the FILE. Similar to 447 * aug_load, this function returns successfully even if FILE does not exist 448 * or if the FILE can not be processed by the associated lens. It is an 449 * error though if no lens can be found to process FILE. In that case, the 450 * error code in AUG will be set to AUG_ENOLENS. 451 * 452 * Returns: 453 * 0 on success, -1 on failure 454 */ 455 int aug_load_file(augeas *aug, const char *file); 456 457 /* 458 * Function: aug_srun 459 * 460 * Run one or more newline-separated commands. The output of the commands 461 * will be printed to OUT. Running just 'help' will print what commands are 462 * available. Commands accepted by this are identical to what augtool 463 * accepts. 464 * 465 * Returns: 466 * the number of executed commands on success, -1 on failure, and -2 if a 467 * 'quit' command was encountered 468 */ 469 int aug_srun(augeas *aug, FILE *out, const char *text); 470 471 /* Function: aug_close 472 * 473 * Close this Augeas instance and free any storage associated with 474 * it. After running AUG_CLOSE, AUG is invalid and can not be used for any 475 * more operations. 476 */ 477 void aug_close(augeas *aug); 478 479 // We can't put //* into the examples in these comments since the C 480 // preprocessor complains about that. So we'll resort to the equivalent but 481 // more wordy notation /descendant::* 482 483 /* 484 * Function: aug_ns_attr 485 * 486 * Look up the ith node in the variable VAR and retrieve information about 487 * it. Set *VALUE to the value of the node, *LABEL to its label, and 488 * *FILE_PATH to the path of the file it belongs to, or to NULL if that 489 * node does not belong to a file. It is permissible to pass NULL for any 490 * of these variables to indicate that the caller is not interested in that 491 * attribute. 492 * 493 * It is assumed that VAR was defined with a path expression evaluating to 494 * a nodeset, like '/files/etc/hosts/descendant::*'. This function is 495 * equivalent to, but faster than, aug_get(aug, "$VAR[I+1]", value), 496 * respectively the corresponding calls to aug_label and aug_source. Note 497 * that the index is 0-based, not 1-based. 498 * 499 * If VAR does not exist, or is not a nodeset, or if it has fewer than I 500 * nodes, this call fails. 501 * 502 * The caller is responsible for freeing *FILE_PATH, but must not free 503 * *VALUE or *LABEL. Those pointers are only valid up to the next call to a 504 * function in this API that might modify the tree. 505 * 506 * Returns: 507 * 1 on success (for consistency with aug_get), a negative value on failure 508 */ 509 int aug_ns_attr(const augeas* aug, const char *var, int i, 510 const char **value, const char **label, char **file_path); 511 512 /* 513 * Function: aug_ns_label 514 * 515 * Look up the LABEL and its INDEX amongst its siblings for the ith node in 516 * variable VAR. (See aug_ns_attr for details of what is expected of VAR) 517 * 518 * Either of LABEL and INDEX may be NULL. The *INDEX will be set to the 519 * number of siblings + 1 of the node $VAR[I+1] that precede it and have 520 * the same label if there are at least two siblings with that label. If 521 * the node $VAR[I+1] does not have any siblings with the same label as 522 * itself, *INDEX will be set to 0. 523 * 524 * The caller must not free *LABEL. The pointer is only valid up to the 525 * next call to a function in this API that might modify the tree. 526 * 527 * Returns: 528 * 1 on success (for consistency with aug_get), a negative value on failure 529 */ 530 int aug_ns_label(const augeas *aug, const char *var, int i, 531 const char **label, int *index); 532 533 /* 534 * Function: aug_ns_value 535 * 536 * Look up the VALUE of the ith node in variable VAR. (See aug_ns_attr for 537 * details of what is expected of VAR) 538 * 539 * The caller must not free *VALUE. The pointer is only valid up to the 540 * next call to a function in this API that might modify the tree. 541 * 542 * Returns: 543 * 1 on success (for consistency with aug_get), a negative value on failure 544 */ 545 int aug_ns_value(const augeas *aug, const char *var, int i, 546 const char **value); 547 548 /* 549 * Function: aug_ns_count 550 * 551 * Return the number of nodes in variable VAR. (See aug_ns_attr for details 552 * of what is expected of VAR) 553 * 554 * Returns: the number of nodes in VAR, or a negative value on failure 555 */ 556 int aug_ns_count(const augeas *aug, const char *var); 557 558 /* 559 * Function: aug_ns_count 560 * 561 * Put the fully qualified path to the ith node in VAR into *PATH. (See 562 * aug_ns_attr for details of what is expected of VAR) 563 * 564 * The caller is responsible for freeing *PATH, which is allocated by this 565 * function. 566 * 567 * Returns: 1 on success (for consistency with aug_get), a negative value 568 * on failure 569 */ 570 int aug_ns_path(const augeas *aug, const char *var, int i, char **path); 571 572 /* 573 * Error reporting 574 */ 575 576 typedef enum { 577 AUG_NOERROR, /* No error */ 578 AUG_ENOMEM, /* Out of memory */ 579 AUG_EINTERNAL, /* Internal error (bug) */ 580 AUG_EPATHX, /* Invalid path expression */ 581 AUG_ENOMATCH, /* No match for path expression */ 582 AUG_EMMATCH, /* Too many matches for path expression */ 583 AUG_ESYNTAX, /* Syntax error in lens file */ 584 AUG_ENOLENS, /* Lens lookup failed */ 585 AUG_EMXFM, /* Multiple transforms */ 586 AUG_ENOSPAN, /* No span for this node */ 587 AUG_EMVDESC, /* Cannot move node into its descendant */ 588 AUG_ECMDRUN, /* Failed to execute command */ 589 AUG_EBADARG, /* Invalid argument in function call */ 590 AUG_ELABEL, /* Invalid label */ 591 AUG_ECPDESC /* Cannot copy node into its descendant */ 592 } aug_errcode_t; 593 594 /* Return the error code from the last API call */ 595 int aug_error(augeas *aug); 596 597 /* Return a human-readable message for the error code */ 598 const char *aug_error_message(augeas *aug); 599 600 /* Return a human-readable message elaborating the error code; might be 601 * NULL. For example, when the error code is AUG_EPATHX, this will explain 602 * how the path expression is invalid */ 603 const char *aug_error_minor_message(augeas *aug); 604 605 /* Return details about the error, which might be NULL. For example, for 606 * AUG_EPATHX, indicates where in the path expression the error 607 * occurred. The returned value can only be used until the next API call 608 */ 609 const char *aug_error_details(augeas *aug); 610 611 612 #ifdef __cplusplus 613 } 614 #endif 615 616 #endif 617 618 619 /* 620 * Local variables: 621 * indent-tabs-mode: nil 622 * c-indent-level: 4 623 * c-basic-offset: 4 624 * tab-width: 4 625 * End: 626 */ 627