pacemaker  2.1.3-ea053b43a
Scalable High-Availability cluster resource manager
xml.h
Go to the documentation of this file.
1 /*
2  * Copyright 2004-2021 the Pacemaker project contributors
3  *
4  * The version control history for this file may have further details.
5  *
6  * This source code is licensed under the GNU Lesser General Public License
7  * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
8  */
9 
10 #ifndef PCMK__CRM_COMMON_XML__H
11 # define PCMK__CRM_COMMON_XML__H
12 
13 
14 # include <stdio.h>
15 # include <sys/types.h>
16 # include <unistd.h>
17 
18 # include <stdlib.h>
19 # include <errno.h>
20 # include <fcntl.h>
21 
22 # include <libxml/tree.h>
23 # include <libxml/xpath.h>
24 
25 # include <crm/crm.h>
26 # include <crm/common/nvpair.h>
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
38 /* Define compression parameters for IPC messages
39  *
40  * Compression costs a LOT, so we don't want to do it unless we're hitting
41  * message limits. Currently, we use 128KB as the threshold, because higher
42  * values don't play well with the heartbeat stack. With an earlier limit of
43  * 10KB, compressing 184 of 1071 messages accounted for 23% of the total CPU
44  * used by the cib.
45  */
46 # define CRM_BZ2_BLOCKS 4
47 # define CRM_BZ2_WORK 20
48 # define CRM_BZ2_THRESHOLD 128 * 1024
49 
50 # define XML_PARANOIA_CHECKS 0
51 
52 typedef const xmlChar *pcmkXmlStr;
53 
54 gboolean add_message_xml(xmlNode * msg, const char *field, xmlNode * xml);
55 xmlNode *get_message_xml(xmlNode * msg, const char *field);
56 
57 xmlDoc *getDocPtr(xmlNode * node);
58 
59 /*
60  * Replacement function for xmlCopyPropList which at the very least,
61  * doesn't work the way *I* would expect it to.
62  *
63  * Copy all the attributes/properties from src into target.
64  *
65  * Not recursive, does not return anything.
66  *
67  */
68 void copy_in_properties(xmlNode * target, xmlNode * src);
69 void expand_plus_plus(xmlNode * target, const char *name, const char *value);
70 void fix_plus_plus_recursive(xmlNode * target);
71 
72 /*
73  * Create a node named "name" as a child of "parent"
74  * If parent is NULL, creates an unconnected node.
75  *
76  * Returns the created node
77  *
78  */
79 xmlNode *create_xml_node(xmlNode * parent, const char *name);
80 
81 /*
82  * Create a node named "name" as a child of "parent", giving it the provided
83  * text content.
84  * If parent is NULL, creates an unconnected node.
85  *
86  * Returns the created node
87  *
88  */
89 xmlNode *pcmk_create_xml_text_node(xmlNode * parent, const char *name, const char *content);
90 
91 /*
92  * Create a new HTML node named "element_name" as a child of "parent", giving it the
93  * provided text content. Optionally, apply a CSS #id and #class.
94  *
95  * Returns the created node.
96  */
97 xmlNode *pcmk_create_html_node(xmlNode * parent, const char *element_name, const char *id,
98  const char *class_name, const char *text);
99 
100 /*
101  *
102  */
103 void purge_diff_markers(xmlNode * a_node);
104 
105 /*
106  * Returns a deep copy of src_node
107  *
108  */
109 xmlNode *copy_xml(xmlNode * src_node);
110 
111 /*
112  * Add a copy of xml_node to new_parent
113  */
114 xmlNode *add_node_copy(xmlNode * new_parent, xmlNode * xml_node);
115 
116 int add_node_nocopy(xmlNode * parent, const char *name, xmlNode * child);
117 
118 /*
119  * XML I/O Functions
120  *
121  * Whitespace between tags is discarded.
122  */
123 xmlNode *filename2xml(const char *filename);
124 
125 xmlNode *stdin2xml(void);
126 
127 xmlNode *string2xml(const char *input);
128 
129 int write_xml_fd(xmlNode * xml_node, const char *filename, int fd, gboolean compress);
130 int write_xml_file(xmlNode * xml_node, const char *filename, gboolean compress);
131 
132 char *dump_xml_formatted(xmlNode * msg);
133 /* Also dump the text node with xml_log_option_text enabled */
134 char *dump_xml_formatted_with_text(xmlNode * msg);
135 
136 char *dump_xml_unformatted(xmlNode * msg);
137 
138 /*
139  * Diff related Functions
140  */
141 xmlNode *diff_xml_object(xmlNode * left, xmlNode * right, gboolean suppress);
142 
143 xmlNode *subtract_xml_object(xmlNode * parent, xmlNode * left, xmlNode * right,
144  gboolean full, gboolean * changed, const char *marker);
145 
146 gboolean can_prune_leaf(xmlNode * xml_node);
147 
148 /*
149  * Searching & Modifying
150  */
151 xmlNode *find_xml_node(xmlNode * cib, const char *node_path, gboolean must_find);
152 
153 void xml_remove_prop(xmlNode * obj, const char *name);
154 
155 gboolean replace_xml_child(xmlNode * parent, xmlNode * child, xmlNode * update,
156  gboolean delete_only);
157 
158 gboolean update_xml_child(xmlNode * child, xmlNode * to_update);
159 
160 int find_xml_children(xmlNode ** children, xmlNode * root,
161  const char *tag, const char *field, const char *value,
162  gboolean search_matches);
163 
164 xmlNode *get_xpath_object(const char *xpath, xmlNode * xml_obj, int error_level);
165 xmlNode *get_xpath_object_relative(const char *xpath, xmlNode * xml_obj, int error_level);
166 
167 static inline const char *
168 crm_element_name(const xmlNode *xml)
169 {
170  return xml? (const char *)(xml->name) : NULL;
171 }
172 
173 static inline const char *
174 crm_map_element_name(const xmlNode *xml)
175 {
176  const char *name = crm_element_name(xml);
177 
178  if (strcmp(name, "master") == 0) {
179  return "clone";
180  } else {
181  return name;
182  }
183 }
184 
185 gboolean xml_has_children(const xmlNode * root);
186 
187 char *calculate_on_disk_digest(xmlNode * local_cib);
188 char *calculate_operation_digest(xmlNode * local_cib, const char *version);
189 char *calculate_xml_versioned_digest(xmlNode * input, gboolean sort, gboolean do_filter,
190  const char *version);
191 
192 /* schema-related functions (from schemas.c) */
193 gboolean validate_xml(xmlNode * xml_blob, const char *validation, gboolean to_logs);
194 gboolean validate_xml_verbose(xmlNode * xml_blob);
195 
233 int update_validation(xmlNode **xml_blob, int *best, int max,
234  gboolean transform, gboolean to_logs);
235 
236 int get_schema_version(const char *name);
237 const char *get_schema_name(int version);
238 const char *xml_latest_schema(void);
239 gboolean cli_config_update(xmlNode ** xml, int *best_version, gboolean to_logs);
240 
246 void crm_xml_init(void);
247 void crm_xml_cleanup(void);
248 
249 void pcmk_free_xml_subtree(xmlNode *xml);
250 void free_xml(xmlNode * child);
251 
252 xmlNode *first_named_child(const xmlNode *parent, const char *name);
253 xmlNode *crm_next_same_xml(const xmlNode *sibling);
254 
255 xmlNode *sorted_xml(xmlNode * input, xmlNode * parent, gboolean recursive);
256 xmlXPathObjectPtr xpath_search(xmlNode * xml_top, const char *path);
257 void crm_foreach_xpath_result(xmlNode *xml, const char *xpath,
258  void (*helper)(xmlNode*, void*), void *user_data);
259 xmlNode *expand_idref(xmlNode * input, xmlNode * top);
260 
261 void freeXpathObject(xmlXPathObjectPtr xpathObj);
262 xmlNode *getXpathResult(xmlXPathObjectPtr xpathObj, int index);
263 void dedupXpathResults(xmlXPathObjectPtr xpathObj);
264 
265 static inline int numXpathResults(xmlXPathObjectPtr xpathObj)
266 {
267  if(xpathObj == NULL || xpathObj->nodesetval == NULL) {
268  return 0;
269  }
270  return xpathObj->nodesetval->nodeNr;
271 }
272 
273 bool xml_tracking_changes(xmlNode * xml);
274 bool xml_document_dirty(xmlNode *xml);
275 void xml_track_changes(xmlNode * xml, const char *user, xmlNode *acl_source, bool enforce_acls);
276 void xml_calculate_changes(xmlNode *old_xml, xmlNode *new_xml);
277 void xml_calculate_significant_changes(xmlNode *old_xml, xmlNode *new_xml);
278 void xml_accept_changes(xmlNode * xml);
279 void xml_log_changes(uint8_t level, const char *function, xmlNode *xml);
280 void xml_log_patchset(uint8_t level, const char *function, xmlNode *xml);
281 bool xml_patch_versions(xmlNode *patchset, int add[3], int del[3]);
282 
283 xmlNode *xml_create_patchset(
284  int format, xmlNode *source, xmlNode *target, bool *config, bool manage_version);
285 int xml_apply_patchset(xmlNode *xml, xmlNode *patchset, bool check_version);
286 
287 void patchset_process_digest(xmlNode *patch, xmlNode *source, xmlNode *target, bool with_digest);
288 
289 void save_xml_to_file(xmlNode * xml, const char *desc, const char *filename);
290 char *xml_get_path(xmlNode *xml);
291 
292 char * crm_xml_escape(const char *text);
293 void crm_xml_sanitize_id(char *id);
294 void crm_xml_set_id(xmlNode *xml, const char *format, ...) G_GNUC_PRINTF(2, 3);
295 
299 void crm_destroy_xml(gpointer data);
300 
301 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
302 #include <crm/common/xml_compat.h>
303 #endif
304 
305 #ifdef __cplusplus
306 }
307 #endif
308 
309 #endif
xmlNode * find_xml_node(xmlNode *cib, const char *node_path, gboolean must_find)
Definition: xml.c:445
xmlNode * get_xpath_object_relative(const char *xpath, xmlNode *xml_obj, int error_level)
Definition: xpath.c:192
A dumping ground.
xmlNode * get_message_xml(xmlNode *msg, const char *field)
Definition: messages.c:154
char data[0]
Definition: cpg.c:55
const char * name
Definition: cib.c:24
xmlNode * first_named_child(const xmlNode *parent, const char *name)
Definition: xml.c:2794
void crm_xml_cleanup(void)
Definition: xml.c:2857
xmlNode * pcmk_create_html_node(xmlNode *parent, const char *element_name, const char *id, const char *class_name, const char *text)
Definition: xml.c:733
void xml_track_changes(xmlNode *xml, const char *user, xmlNode *acl_source, bool enforce_acls)
Definition: xml.c:275
void crm_xml_init(void)
Initialize the CRM XML subsystem.
Definition: xml.c:2835
int write_xml_file(xmlNode *xml_node, const char *filename, gboolean compress)
Write XML to a file.
Definition: xml.c:1300
int get_schema_version(const char *name)
Definition: schemas.c:1024
void copy_in_properties(xmlNode *target, xmlNode *src)
Definition: xml.c:520
void xml_accept_changes(xmlNode *xml)
Definition: xml.c:420
xmlNode * filename2xml(const char *filename)
Definition: xml.c:1045
void dedupXpathResults(xmlXPathObjectPtr xpathObj)
Definition: xpath.c:101
void purge_diff_markers(xmlNode *a_node)
Definition: patchset.c:1405
xmlNode * get_xpath_object(const char *xpath, xmlNode *xml_obj, int error_level)
Definition: xpath.c:214
Deprecated Pacemaker XML API.
xmlNode * string2xml(const char *input)
Definition: xml.c:869
void crm_xml_sanitize_id(char *id)
Sanitize a string so it is usable as an XML ID.
Definition: xml.c:1129
gboolean validate_xml(xmlNode *xml_blob, const char *validation, gboolean to_logs)
Definition: schemas.c:698
xmlDoc * getDocPtr(xmlNode *node)
Definition: xml.c:658
gboolean validate_xml_verbose(xmlNode *xml_blob)
Definition: schemas.c:670
void expand_plus_plus(xmlNode *target, const char *name, const char *value)
Definition: xml.c:559
bool xml_tracking_changes(xmlNode *xml)
Definition: xml.c:290
xmlNode * copy_xml(xmlNode *src_node)
Definition: xml.c:830
char * calculate_operation_digest(xmlNode *local_cib, const char *version)
Calculate and return digest of XML operation.
Definition: digest.c:170
xmlNode * stdin2xml(void)
Definition: xml.c:930
void pcmk_free_xml_subtree(xmlNode *xml)
Definition: xml.c:755
int xml_apply_patchset(xmlNode *xml, xmlNode *patchset, bool check_version)
Definition: patchset.c:1325
gboolean update_xml_child(xmlNode *child, xmlNode *to_update)
Definition: xml.c:2613
xmlNode * pcmk_create_xml_text_node(xmlNode *parent, const char *name, const char *content)
Definition: xml.c:721
xmlNode * add_node_copy(xmlNode *new_parent, xmlNode *xml_node)
Definition: xml.c:674
void crm_xml_set_id(xmlNode *xml, const char *format,...) G_GNUC_PRINTF(2
xmlNode * expand_idref(xmlNode *input, xmlNode *top)
Definition: xml.c:2867
bool xml_document_dirty(xmlNode *xml)
Definition: xml.c:297
xmlNode * create_xml_node(xmlNode *parent, const char *name)
Definition: xml.c:696
char * dump_xml_formatted(xmlNode *msg)
Definition: xml.c:2007
void void crm_destroy_xml(gpointer data)
xmlNode destructor which can be used in glib collections
Definition: xml.c:2900
gboolean add_message_xml(xmlNode *msg, const char *field, xmlNode *xml)
Definition: messages.c:162
void free_xml(xmlNode *child)
Definition: xml.c:824
gboolean xml_has_children(const xmlNode *root)
Definition: xml.c:2028
char * calculate_on_disk_digest(xmlNode *local_cib)
Calculate and return digest of XML tree, suitable for storing on disk.
Definition: digest.c:151
xmlNode * sorted_xml(xmlNode *input, xmlNode *parent, gboolean recursive)
Definition: xml.c:2762
const char * xml_latest_schema(void)
Definition: schemas.c:112
void patchset_process_digest(xmlNode *patch, xmlNode *source, xmlNode *target, bool with_digest)
Definition: patchset.c:426
const xmlChar * pcmkXmlStr
Definition: xml.h:52
Functionality for manipulating name/value pairs.
int find_xml_children(xmlNode **children, xmlNode *root, const char *tag, const char *field, const char *value, gboolean search_matches)
Definition: xml.c:2647
const char * target
Definition: pcmk_fence.c:28
bool xml_patch_versions(xmlNode *patchset, int add[3], int del[3])
Definition: patchset.c:801
void xml_log_changes(uint8_t level, const char *function, xmlNode *xml)
Definition: xml.c:385
const char * path
Definition: cib.c:26
xmlXPathObjectPtr xpath_search(xmlNode *xml_top, const char *path)
Definition: xpath.c:139
xmlNode * input
void xml_remove_prop(xmlNode *obj, const char *name)
Definition: xml.c:2037
xmlNode * getXpathResult(xmlXPathObjectPtr xpathObj, int index)
Definition: xpath.c:58
char * calculate_xml_versioned_digest(xmlNode *input, gboolean sort, gboolean do_filter, const char *version)
Calculate and return digest of XML tree.
Definition: digest.c:187
gboolean can_prune_leaf(xmlNode *xml_node)
Definition: xml.c:2392
char * xml_get_path(xmlNode *xml)
Definition: xpath.c:291
char * dump_xml_unformatted(xmlNode *msg)
Definition: xml.c:2018
void save_xml_to_file(xmlNode *xml, const char *desc, const char *filename)
Definition: xml.c:2056
void crm_foreach_xpath_result(xmlNode *xml, const char *xpath, void(*helper)(xmlNode *, void *), void *user_data)
Run a supplied function for each result of an xpath search.
Definition: xpath.c:173
int update_validation(xmlNode **xml_blob, int *best, int max, gboolean transform, gboolean to_logs)
Update CIB XML to most recent schema version.
Definition: schemas.c:1041
xmlNode * diff_xml_object(xmlNode *left, xmlNode *right, gboolean suppress)
Definition: patchset.c:1419
int add_node_nocopy(xmlNode *parent, const char *name, xmlNode *child)
Definition: xml.c:688
xmlNode * subtract_xml_object(xmlNode *parent, xmlNode *left, xmlNode *right, gboolean full, gboolean *changed, const char *marker)
Definition: patchset.c:1468
const char * parent
Definition: cib.c:25
void xml_log_patchset(uint8_t level, const char *function, xmlNode *xml)
Definition: patchset.c:457
void xml_calculate_significant_changes(xmlNode *old_xml, xmlNode *new_xml)
Definition: xml.c:2371
int write_xml_fd(xmlNode *xml_node, const char *filename, int fd, gboolean compress)
Write XML to a file descriptor.
Definition: xml.c:1272
char * crm_xml_escape(const char *text)
Replace special characters with their XML escape sequences.
Definition: xml.c:1345
gboolean cli_config_update(xmlNode **xml, int *best_version, gboolean to_logs)
Definition: schemas.c:1188
void fix_plus_plus_recursive(xmlNode *target)
Definition: xml.c:541
void freeXpathObject(xmlXPathObjectPtr xpathObj)
Definition: xpath.c:39
xmlNode * xml_create_patchset(int format, xmlNode *source, xmlNode *target, bool *config, bool manage_version)
Definition: patchset.c:369
void xml_calculate_changes(xmlNode *old_xml, xmlNode *new_xml)
Definition: xml.c:2378
char * dump_xml_formatted_with_text(xmlNode *msg)
Definition: xml.c:1995
uint32_t version
Definition: remote.c:147
gboolean replace_xml_child(xmlNode *parent, xmlNode *child, xmlNode *update, gboolean delete_only)
Definition: xml.c:2680
const char * get_schema_name(int version)
Definition: schemas.c:1015
xmlNode * crm_next_same_xml(const xmlNode *sibling)
Get next instance of same XML tag.
Definition: xml.c:2820