xml.h File Reference

Wrappers for and extensions to libxml2. More...

#include <stdio.h>
#include <sys/types.h>
#include <unistd.h>
#include <stdlib.h>
#include <errno.h>
#include <fcntl.h>
#include <libxml/tree.h>
#include <libxml/xpath.h>
#include <crm/crm.h>
#include <crm/common/nvpair.h>
#include <crm/common/xml_compat.h>

Include dependency graph for xml.h:

Go to the source code of this file.

Macros
#define	CRM_BZ2_BLOCKS   4
#define	CRM_BZ2_WORK   20
#define	CRM_BZ2_THRESHOLD   128 * 1024

Typedefs
typedef const xmlChar *	pcmkXmlStr

Functions
gboolean	add_message_xml (xmlNode *msg, const char *field, xmlNode *xml)
xmlNode *	get_message_xml (const xmlNode *msg, const char *field)
xmlDoc *	getDocPtr (xmlNode *node)
void	copy_in_properties (xmlNode *target, xmlNode *src)
void	expand_plus_plus (xmlNode *target, const char *name, const char *value)
	Update current XML attribute value per parsed integer assignment statement. More...
void	fix_plus_plus_recursive (xmlNode *target)
	Parse integer assignment statements on this node and all its child nodes. More...
xmlNode *	create_xml_node (xmlNode *parent, const char *name)
xmlNode *	pcmk_create_xml_text_node (xmlNode *parent, const char *name, const char *content)
xmlNode *	pcmk_create_html_node (xmlNode *parent, const char *element_name, const char *id, const char *class_name, const char *text)
void	purge_diff_markers (xmlNode *a_node)
xmlNode *	copy_xml (xmlNode *src_node)
xmlNode *	add_node_copy (xmlNode *new_parent, xmlNode *xml_node)
int	add_node_nocopy (xmlNode *parent, const char *name, xmlNode *child)
xmlNode *	filename2xml (const char *filename)
xmlNode *	stdin2xml (void)
xmlNode *	string2xml (const char *input)
int	write_xml_fd (xmlNode *xml_node, const char *filename, int fd, gboolean compress)
	Write XML to a file descriptor. More...
int	write_xml_file (xmlNode *xml_node, const char *filename, gboolean compress)
	Write XML to a file. More...
char *	dump_xml_formatted (xmlNode *msg)
char *	dump_xml_formatted_with_text (xmlNode *msg)
char *	dump_xml_unformatted (xmlNode *msg)
xmlNode *	diff_xml_object (xmlNode *left, xmlNode *right, gboolean suppress)
xmlNode *	subtract_xml_object (xmlNode *parent, xmlNode *left, xmlNode *right, gboolean full, gboolean *changed, const char *marker)
gboolean	can_prune_leaf (xmlNode *xml_node)
xmlNode *	find_xml_node (const xmlNode *root, const char *search_path, gboolean must_find)
void	xml_remove_prop (xmlNode *obj, const char *name)
gboolean	replace_xml_child (xmlNode *parent, xmlNode *child, xmlNode *update, gboolean delete_only)
gboolean	update_xml_child (xmlNode *child, xmlNode *to_update)
int	find_xml_children (xmlNode **children, xmlNode *root, const char *tag, const char *field, const char *value, gboolean search_matches)
xmlNode *	get_xpath_object (const char *xpath, xmlNode *xml_obj, int error_level)
xmlNode *	get_xpath_object_relative (const char *xpath, xmlNode *xml_obj, int error_level)
gboolean	xml_has_children (const xmlNode *root)
char *	calculate_on_disk_digest (xmlNode *local_cib)
	Calculate and return digest of XML tree, suitable for storing on disk. More...
char *	calculate_operation_digest (xmlNode *local_cib, const char *version)
	Calculate and return digest of XML operation. More...
char *	calculate_xml_versioned_digest (xmlNode *input, gboolean sort, gboolean do_filter, const char *version)
	Calculate and return digest of XML tree. More...
gboolean	validate_xml (xmlNode *xml_blob, const char *validation, gboolean to_logs)
gboolean	validate_xml_verbose (xmlNode *xml_blob)
int	update_validation (xmlNode **xml_blob, int *best, int max, gboolean transform, gboolean to_logs)
	Update CIB XML to most recent schema version. More...
int	get_schema_version (const char *name)
const char *	get_schema_name (int version)
const char *	xml_latest_schema (void)
gboolean	cli_config_update (xmlNode **xml, int *best_version, gboolean to_logs)
void	crm_xml_init (void)
	Initialize the CRM XML subsystem. More...
void	crm_xml_cleanup (void)
void	pcmk_free_xml_subtree (xmlNode *xml)
void	free_xml (xmlNode *child)
xmlNode *	first_named_child (const xmlNode *parent, const char *name)
xmlNode *	crm_next_same_xml (const xmlNode *sibling)
	Get next instance of same XML tag. More...
xmlNode *	sorted_xml (xmlNode *input, xmlNode *parent, gboolean recursive)
xmlXPathObjectPtr	xpath_search (xmlNode *xml_top, const char *path)
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. More...
xmlNode *	expand_idref (xmlNode *input, xmlNode *top)
void	freeXpathObject (xmlXPathObjectPtr xpathObj)
xmlNode *	getXpathResult (xmlXPathObjectPtr xpathObj, int index)
void	dedupXpathResults (xmlXPathObjectPtr xpathObj)
bool	xml_tracking_changes (xmlNode *xml)
bool	xml_document_dirty (xmlNode *xml)
void	xml_track_changes (xmlNode *xml, const char *user, xmlNode *acl_source, bool enforce_acls)
void	xml_calculate_changes (xmlNode *old_xml, xmlNode *new_xml)
void	xml_calculate_significant_changes (xmlNode *old_xml, xmlNode *new_xml)
void	xml_accept_changes (xmlNode *xml)
void	xml_log_changes (uint8_t level, const char *function, xmlNode *xml)
void	xml_log_patchset (uint8_t level, const char *function, xmlNode *xml)
bool	xml_patch_versions (const xmlNode *patchset, int add[3], int del[3])
xmlNode *	xml_create_patchset (int format, xmlNode *source, xmlNode *target, bool *config, bool manage_version)
int	xml_apply_patchset (xmlNode *xml, xmlNode *patchset, bool check_version)
void	patchset_process_digest (xmlNode *patch, xmlNode *source, xmlNode *target, bool with_digest)
void	save_xml_to_file (xmlNode *xml, const char *desc, const char *filename)
char *	crm_xml_escape (const char *text)
	Replace special characters with their XML escape sequences. More...
void	crm_xml_sanitize_id (char *id)
	Sanitize a string so it is usable as an XML ID. More...
void	crm_xml_set_id (xmlNode *xml, const char *format,...) G_GNUC_PRINTF(2

Detailed Description

Wrappers for and extensions to libxml2.

Definition in file xml.h.

Macro Definition Documentation

CRM_BZ2_BLOCKS

#define CRM_BZ2_BLOCKS   4

Definition at line 46 of file xml.h.

CRM_BZ2_THRESHOLD

#define CRM_BZ2_THRESHOLD   128 * 1024

Definition at line 48 of file xml.h.

CRM_BZ2_WORK

#define CRM_BZ2_WORK   20

Definition at line 47 of file xml.h.

Typedef Documentation

pcmkXmlStr

typedef const xmlChar* pcmkXmlStr

Definition at line 50 of file xml.h.

Function Documentation

add_message_xml()

gboolean add_message_xml	(	xmlNode *	msg,
		const char *	field,
		xmlNode *	xml
	)

Definition at line 160 of file messages.c.

add_node_copy()

xmlNode* add_node_copy	(	xmlNode *	new_parent,
		xmlNode *	xml_node
	)

Definition at line 727 of file xml.c.

add_node_nocopy()

int add_node_nocopy	(	xmlNode *	parent,
		const char *	name,
		xmlNode *	child
	)

Definition at line 741 of file xml.c.

calculate_on_disk_digest()

char* calculate_on_disk_digest

(

xmlNode *

input

)

Calculate and return digest of XML tree, suitable for storing on disk.

Parameters

[in]

input

Root of XML to digest

Returns

Newly allocated string containing digest

Definition at line 134 of file digest.c.

calculate_operation_digest()

char* calculate_operation_digest	(	xmlNode *	input,
		const char *	version
	)

Calculate and return digest of XML operation.

Parameters

[in]	input	Root of XML to digest
[in]	version	Unused

Returns

Newly allocated string containing digest

Definition at line 153 of file digest.c.

calculate_xml_versioned_digest()

char* calculate_xml_versioned_digest	(	xmlNode *	input,
		gboolean	sort,
		gboolean	do_filter,
		const char *	version
	)

Calculate and return digest of XML tree.

Parameters

[in]	input	Root of XML to digest
[in]	sort	Whether to sort XML before calculating digest
[in]	do_filter	Whether to filter certain XML attributes
[in]	version	CRM feature set version (used to select v1/v2 digest)

Returns

Newly allocated string containing digest

Definition at line 170 of file digest.c.

can_prune_leaf()

gboolean can_prune_leaf

(

xmlNode *

xml_node

)

Definition at line 2526 of file xml.c.

cli_config_update()

gboolean cli_config_update	(	xmlNode **	xml,
		int *	best_version,
		gboolean	to_logs
	)

Definition at line 1197 of file schemas.c.

copy_in_properties()

void copy_in_properties	(	xmlNode *	target,
		xmlNode *	src
	)

Definition at line 545 of file xml.c.

copy_xml()

xmlNode* copy_xml

(

xmlNode *

src_node

)

Definition at line 891 of file xml.c.

create_xml_node()

xmlNode* create_xml_node	(	xmlNode *	parent,
		const char *	name
	)

Definition at line 749 of file xml.c.

crm_foreach_xpath_result()

void crm_foreach_xpath_result	(	xmlNode *	xml,
		const char *	xpath,
		void(*)(xmlNode *, void *)	helper,
		void *	user_data
	)

Run a supplied function for each result of an xpath search.

Parameters

[in,out]	xml	XML to search
[in]	xpath	XPath search string
[in]	helper	Function to call for each result
[in,out]	user_data	Data to pass to supplied function

Note

The helper function will be passed the XML node of the result, and the supplied user_data. This function does not otherwise use user_data.

Definition at line 173 of file xpath.c.

crm_next_same_xml()

xmlNode* crm_next_same_xml

(

const xmlNode *

sibling

)

Get next instance of same XML tag.

Parameters

[in]

sibling

XML tag to start from

Returns

Next sibling XML tag with same name

Definition at line 2956 of file xml.c.

crm_xml_cleanup()

void crm_xml_cleanup

(

void

)

Definition at line 2993 of file xml.c.

crm_xml_escape()

char* crm_xml_escape

(

const char *

text

)

Replace special characters with their XML escape sequences.

Parameters

[in]

text

Text to escape

Returns

Newly allocated string equivalent to text but with special characters replaced with XML escape sequences (or NULL if text is NULL)

Definition at line 1406 of file xml.c.

crm_xml_init()

void crm_xml_init

(

void

)

Initialize the CRM XML subsystem.

This method sets global XML settings and loads pacemaker schemas into the cache.

Definition at line 2971 of file xml.c.

crm_xml_sanitize_id()

void crm_xml_sanitize_id

(

char *

id

)

Sanitize a string so it is usable as an XML ID.

Parameters

[in,out]

id

String to sanitize

Definition at line 1190 of file xml.c.

crm_xml_set_id()

void crm_xml_set_id	(	xmlNode *	xml,
		const char *	format,
			...
	)

dedupXpathResults()

void dedupXpathResults

(

xmlXPathObjectPtr

xpathObj

)

Definition at line 101 of file xpath.c.

diff_xml_object()

xmlNode* diff_xml_object	(	xmlNode *	left,
		xmlNode *	right,
		gboolean	suppress
	)

Definition at line 1411 of file patchset.c.

dump_xml_formatted()

char* dump_xml_formatted

(

xmlNode *

msg

)

Definition at line 2106 of file xml.c.

dump_xml_formatted_with_text()

char* dump_xml_formatted_with_text

(

xmlNode *

msg

)

Definition at line 2089 of file xml.c.

dump_xml_unformatted()

char* dump_xml_unformatted

(

xmlNode *

msg

)

Definition at line 2121 of file xml.c.

expand_idref()

xmlNode* expand_idref	(	xmlNode *	input,
		xmlNode *	top
	)

Definition at line 3002 of file xml.c.

expand_plus_plus()

void expand_plus_plus	(	xmlNode *	target,
		const char *	name,
		const char *	value
	)

Update current XML attribute value per parsed integer assignment statement.

Parameters

[in,out]	target	an XML node, containing a XML attribute that is initialized to some numeric value, to be processed
[in]	name	name of the XML attribute, e.g. X, whose value should be updated
[in]	value	assignment statement, e.g. "X++" or "X+=5", to be applied to the initialized value.

Note

The original XML attribute value is treated as 0 if non-numeric and truncated to be an integer if decimal-point-containing.

The final XML attribute value is truncated to not exceed 1000000.

Undefined behavior if unexpected input.

Definition at line 612 of file xml.c.

filename2xml()

xmlNode* filename2xml

(

const char *

filename

)

Definition at line 1106 of file xml.c.

find_xml_children()

int find_xml_children	(	xmlNode **	children,
		xmlNode *	root,
		const char *	tag,
		const char *	field,
		const char *	value,
		gboolean	search_matches
	)

Definition at line 2783 of file xml.c.

find_xml_node()

xmlNode* find_xml_node	(	const xmlNode *	root,
		const char *	search_path,
		gboolean	must_find
	)

Definition at line 470 of file xml.c.

first_named_child()

xmlNode* first_named_child	(	const xmlNode *	parent,
		const char *	name
	)

Definition at line 2930 of file xml.c.

fix_plus_plus_recursive()

void fix_plus_plus_recursive

(

xmlNode *

target

)

Parse integer assignment statements on this node and all its child nodes.

Parameters

[in,out]

target

Root XML node to be processed

Note

This function is recursive

Definition at line 578 of file xml.c.

free_xml()

void free_xml

(

xmlNode *

child

)

Definition at line 885 of file xml.c.

freeXpathObject()

void freeXpathObject

(

xmlXPathObjectPtr

xpathObj

)

Definition at line 39 of file xpath.c.

get_message_xml()

xmlNode* get_message_xml	(	const xmlNode *	msg,
		const char *	field
	)

Definition at line 154 of file messages.c.

get_schema_name()

const char* get_schema_name

(

int

version

)

Definition at line 1024 of file schemas.c.

get_schema_version()

int get_schema_version

(

const char *

name

)

Definition at line 1033 of file schemas.c.

get_xpath_object()

xmlNode* get_xpath_object	(	const char *	xpath,
		xmlNode *	xml_obj,
		int	error_level
	)

Definition at line 214 of file xpath.c.

get_xpath_object_relative()

xmlNode* get_xpath_object_relative	(	const char *	xpath,
		xmlNode *	xml_obj,
		int	error_level
	)

Definition at line 192 of file xpath.c.

getDocPtr()

xmlDoc* getDocPtr

(

xmlNode *

node

)

Definition at line 711 of file xml.c.

getXpathResult()

xmlNode* getXpathResult	(	xmlXPathObjectPtr	xpathObj,
		int	index
	)

Definition at line 58 of file xpath.c.

patchset_process_digest()

void patchset_process_digest	(	xmlNode *	patch,
		xmlNode *	source,
		xmlNode *	target,
		bool	with_digest
	)

Definition at line 425 of file patchset.c.

pcmk_create_html_node()

xmlNode* pcmk_create_html_node	(	xmlNode *	parent,
		const char *	element_name,
		const char *	id,
		const char *	class_name,
		const char *	text
	)

Definition at line 786 of file xml.c.

pcmk_create_xml_text_node()

xmlNode* pcmk_create_xml_text_node	(	xmlNode *	parent,
		const char *	name,
		const char *	content
	)

Definition at line 774 of file xml.c.

pcmk_free_xml_subtree()

void pcmk_free_xml_subtree

(

xmlNode *

xml

)

Free an XML element and all of its children, removing it from its parent

Parameters

[in,out]

xml

XML element to free

Definition at line 808 of file xml.c.

purge_diff_markers()

void purge_diff_markers

(

xmlNode *

a_node

)

Definition at line 1397 of file patchset.c.

replace_xml_child()

gboolean replace_xml_child	(	xmlNode *	parent,
		xmlNode *	child,
		xmlNode *	update,
		gboolean	delete_only
	)

Definition at line 2816 of file xml.c.

save_xml_to_file()

void save_xml_to_file	(	xmlNode *	xml,
		const char *	desc,
		const char *	filename
	)

Definition at line 2163 of file xml.c.

sorted_xml()

xmlNode* sorted_xml	(	xmlNode *	input,
		xmlNode *	parent,
		gboolean	recursive
	)

Definition at line 2898 of file xml.c.

stdin2xml()

xmlNode* stdin2xml

(

void

)

Definition at line 991 of file xml.c.

string2xml()

xmlNode* string2xml

(

const char *

input

)

Definition at line 930 of file xml.c.

subtract_xml_object()

xmlNode* subtract_xml_object	(	xmlNode *	parent,
		xmlNode *	left,
		xmlNode *	right,
		gboolean	full,
		gboolean *	changed,
		const char *	marker
	)

Definition at line 1460 of file patchset.c.

update_validation()

int update_validation	(	xmlNode **	xml_blob,
		int *	best,
		int	max,
		gboolean	transform,
		gboolean	to_logs
	)

Update CIB XML to most recent schema version.

"Update" means either actively employ XSLT-based transformation(s) (if intermediate product to transform valid per its declared schema version, transformation available, proceeded successfully with a result valid per expectated newer schema version), or just try to bump the marked validating schema until all gradually rising schema versions attested or the first such attempt subsequently fails to validate. Which of the two styles will be used depends on transform parameter (positive/negative, respectively).

Parameters

[in,out]	xml_blob	XML tree representing CIB, may be swapped with an "updated" one
[out]	best	The highest configuration version (per its index in the global schemas table) it was possible to reach during the update steps while ensuring the validity of the result; if no validation success was observed against possibly multiple schemas, the value is less or equal the result of get_schema_version applied on the input xml_blob value (unless that function maps it to -1, then 0 would be used instead)
[in]	max	When transform is positive, this allows to set upper boundary schema (per its index in the global schemas table) beyond which it's forbidden to update by the means of XSLT transformation
[in]	transform	Whether to employ XSLT-based transformation so as to allow overcoming possible incompatibilities between major schema versions (see above)
[in]	to_logs	If true, output notable progress info to internal log streams; if false, to stderr

Returns

pcmk_ok if no non-recoverable error encountered (up to caller to evaluate if the update satisfies the requirements per returned best value), negative value carrying the reason otherwise

Definition at line 1050 of file schemas.c.

update_xml_child()

gboolean update_xml_child	(	xmlNode *	child,
		xmlNode *	to_update
	)

Definition at line 2749 of file xml.c.

validate_xml()

gboolean validate_xml	(	xmlNode *	xml_blob,
		const char *	validation,
		gboolean	to_logs
	)

Definition at line 707 of file schemas.c.

validate_xml_verbose()

gboolean validate_xml_verbose

(

xmlNode *

xml_blob

)

Definition at line 679 of file schemas.c.

write_xml_fd()

int write_xml_fd	(	xmlNode *	xml_node,
		const char *	filename,
		int	fd,
		gboolean	compress
	)

Write XML to a file descriptor.

Parameters

[in]	xml_node	XML to write
[in]	filename	Name of file being written (for logging only)
[in]	fd	Open file descriptor corresponding to filename
[in]	compress	Whether to compress XML before writing

Returns

Number of bytes written on success, -errno otherwise

Definition at line 1333 of file xml.c.

write_xml_file()

int write_xml_file	(	xmlNode *	xml_node,
		const char *	filename,
		gboolean	compress
	)

Write XML to a file.

Parameters

[in]	xml_node	XML to write
[in]	filename	Name of file to write
[in]	compress	Whether to compress XML before writing

Returns

Number of bytes written on success, -errno otherwise

Definition at line 1361 of file xml.c.

xml_accept_changes()

void xml_accept_changes

(

xmlNode *

xml

)

Definition at line 445 of file xml.c.

xml_apply_patchset()

int xml_apply_patchset	(	xmlNode *	xml,
		xmlNode *	patchset,
		bool	check_version
	)

Definition at line 1317 of file patchset.c.

xml_calculate_changes()

void xml_calculate_changes	(	xmlNode *	old_xml,
		xmlNode *	new_xml
	)

Definition at line 2512 of file xml.c.

xml_calculate_significant_changes()

void xml_calculate_significant_changes	(	xmlNode *	old_xml,
		xmlNode *	new_xml
	)

Definition at line 2505 of file xml.c.

xml_create_patchset()

xmlNode* xml_create_patchset	(	int	format,
		xmlNode *	source,
		xmlNode *	target,
		bool *	config,
		bool	manage_version
	)

Definition at line 368 of file patchset.c.

xml_document_dirty()

bool xml_document_dirty

(

xmlNode *

xml

)

Definition at line 323 of file xml.c.

xml_has_children()

gboolean xml_has_children

(

const xmlNode *

root

)

Definition at line 2136 of file xml.c.

xml_latest_schema()

const char* xml_latest_schema

(

void

)

Definition at line 113 of file schemas.c.

xml_log_changes()

void xml_log_changes	(	uint8_t	level,
		const char *	function,
		xmlNode *	xml
	)

Definition at line 410 of file xml.c.

xml_log_patchset()

void xml_log_patchset	(	uint8_t	level,
		const char *	function,
		xmlNode *	xml
	)

Definition at line 456 of file patchset.c.

xml_patch_versions()

bool xml_patch_versions	(	const xmlNode *	patchset,
		int	add[3],
		int	del[3]
	)

Definition at line 793 of file patchset.c.

xml_remove_prop()

void xml_remove_prop	(	xmlNode *	obj,
		const char *	name
	)

Definition at line 2145 of file xml.c.

xml_track_changes()

void xml_track_changes	(	xmlNode *	xml,
		const char *	user,
		xmlNode *	acl_source,
		bool	enforce_acls
	)

Definition at line 301 of file xml.c.

xml_tracking_changes()

bool xml_tracking_changes

(

xmlNode *

xml

)

Definition at line 316 of file xml.c.

xpath_search()

xmlXPathObjectPtr xpath_search	(	xmlNode *	xml_top,
		const char *	path
	)

Definition at line 139 of file xpath.c.