Functionality for manipulating name/value pairs. More...

#include <sys/time.h>
#include <glib.h>
#include <libxml/tree.h>
#include <crm/crm.h>

Include dependency graph for nvpair.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	pcmk_nvpair_s

Typedefs
typedef struct pcmk_nvpair_s	pcmk_nvpair_t

Functions
GSList *	pcmk_prepend_nvpair (GSList nvpairs, const char name, const char *value)
	Prepend a name/value pair to a list. More...

void	pcmk_free_nvpairs (GSList *nvpairs)
	Free a list of name/value pairs. More...

GSList *	pcmk_sort_nvpairs (GSList *list)
	Sort a list of name/value pairs. More...

GSList *	pcmk_xml_attrs2nvpairs (const xmlNode *xml)
	Create a list of name/value pairs from an XML node's attributes. More...

void	pcmk_nvpairs2xml_attrs (GSList list, xmlNode xml)
	Add XML attributes based on a list of name/value pairs. More...

xmlNode *	crm_create_nvpair_xml (xmlNode parent, const char id, const char name, const char value)
	Create an XML name/value pair. More...

void	hash2nvpair (gpointer key, gpointer value, gpointer user_data)
	Add XML nvpair element based on hash table entry. More...

void	hash2field (gpointer key, gpointer value, gpointer user_data)
	Set XML attribute based on hash table entry. More...

void	hash2metafield (gpointer key, gpointer value, gpointer user_data)
	Set XML attribute based on hash table entry, as meta-attribute name. More...

void	hash2smartfield (gpointer key, gpointer value, gpointer user_data)
	Safely add hash table entry to XML as attribute or name-value pair. More...

GHashTable *	xml2list (const xmlNode *parent)
	Retrieve XML attributes as a hash table. More...

const char *	crm_xml_add (xmlNode node, const char name, const char *value)
	Create an XML attribute with specified name and value. More...

const char *	crm_xml_add_int (xmlNode node, const char name, int value)
	Create an XML attribute with specified name and integer value. More...

const char *	crm_xml_add_ll (xmlNode node, const char name, long long value)
	Create an XML attribute with specified name and long long int value. More...

const char *	crm_xml_add_ms (xmlNode node, const char name, guint ms)
	Create an XML attribute with specified name and unsigned value. More...

const char *	crm_xml_add_timeval (xmlNode xml, const char name_sec, const char name_usec, const struct timeval value)
	Create XML attributes for seconds and microseconds. More...

const char *	crm_element_value (const xmlNode data, const char name)
	Retrieve the value of an XML attribute. More...

int	crm_element_value_int (const xmlNode data, const char name, int *dest)
	Retrieve the integer value of an XML attribute. More...

int	crm_element_value_ll (const xmlNode data, const char name, long long *dest)
	Retrieve the long long integer value of an XML attribute. More...

int	crm_element_value_ms (const xmlNode data, const char name, guint *dest)
	Retrieve the millisecond value of an XML attribute. More...

int	crm_element_value_epoch (const xmlNode xml, const char name, time_t *dest)
	Retrieve the seconds-since-epoch value of an XML attribute. More...

int	crm_element_value_timeval (const xmlNode data, const char name_sec, const char name_usec, struct timeval dest)
	Retrieve the value of XML second/microsecond attributes as time. More...

char *	crm_element_value_copy (const xmlNode data, const char name)
	Retrieve a copy of the value of an XML attribute. More...

char *	crm_meta_name (const char *field)
	Get the environment variable equivalent of a meta-attribute name. More...

const char *	crm_meta_value (GHashTable hash, const char field)
	Get the value of a meta-attribute. More...

Detailed Description

Functionality for manipulating name/value pairs.

Definition in file nvpair.h.

Typedef Documentation

◆ pcmk_nvpair_t

typedef struct pcmk_nvpair_s pcmk_nvpair_t

Function Documentation

◆ crm_create_nvpair_xml()

xmlNode* crm_create_nvpair_xml	(	xmlNode *	parent,
		const char *	id,
		const char *	name,
		const char *	value
	)

Create an XML name/value pair.

Parameters

[in,out]	parent	If not `NULL`, make new XML node a child of this one
[in]	id	Set this as XML ID (or NULL to auto-generate)
[in]	name	Name to use
[in]	value	Value to use

Returns: New XML object on success, NULL otherwise

Definition at line 883 of file nvpair.c.

◆ crm_element_value()

const char* crm_element_value	(	const xmlNode *	data,
		const char *	name
	)

Retrieve the value of an XML attribute.

Parameters

[in]	data	XML node to check
[in]	name	Attribute name to check

Returns: Value of specified attribute (may be NULL)

Definition at line 458 of file nvpair.c.

◆ crm_element_value_copy()

char* crm_element_value_copy	(	const xmlNode *	data,
		const char *	name
	)

Retrieve a copy of the value of an XML attribute.

This is like crm_element_value() but allocating new memory for the result.

Parameters

[in]	data	XML node to check
[in]	name	Attribute name to check

Returns: Value of specified attribute (may be NULL)

Note: The caller is responsible for freeing the result.

Definition at line 758 of file nvpair.c.

◆ crm_element_value_epoch()

int crm_element_value_epoch	(	const xmlNode *	xml,
		const char *	name,
		time_t *	dest
	)

Retrieve the seconds-since-epoch value of an XML attribute.

This is like crm_element_value() but returning the value as a time_t.

Parameters

[in]	xml	XML node to check
[in]	name	Attribute name to check
[out]	dest	Where to store attribute value

Returns: pcmk_ok on success, -1 otherwise

Definition at line 651 of file nvpair.c.

◆ crm_element_value_int()

int crm_element_value_int	(	const xmlNode *	data,
		const char *	name,
		int *	dest
	)

Retrieve the integer value of an XML attribute.

This is like crm_element_value() but getting the value as an integer.

Parameters

[in]	data	XML node to check
[in]	name	Attribute name to check
[out]	dest	Where to store element value

Returns: 0 on success, -1 otherwise

Definition at line 494 of file nvpair.c.

◆ crm_element_value_ll()

int crm_element_value_ll	(	const xmlNode *	data,
		const char *	name,
		long long *	dest
	)

Retrieve the long long integer value of an XML attribute.

This is like crm_element_value() but getting the value as a long long int.

Parameters

[in]	data	XML node to check
[in]	name	Attribute name to check
[out]	dest	Where to store element value

Returns: 0 on success, -1 otherwise

Definition at line 583 of file nvpair.c.

◆ crm_element_value_ms()

int crm_element_value_ms	(	const xmlNode *	data,
		const char *	name,
		guint *	dest
	)

Retrieve the millisecond value of an XML attribute.

This is like crm_element_value() but returning the value as a guint.

Parameters

[in]	data	XML node to check
[in]	name	Attribute name to check
[out]	dest	Where to store attribute value

Returns: pcmk_ok on success, -1 otherwise

Definition at line 614 of file nvpair.c.

◆ crm_element_value_timeval()

int crm_element_value_timeval	(	const xmlNode *	xml,
		const char *	name_sec,
		const char *	name_usec,
		struct timeval *	dest
	)

Retrieve the value of XML second/microsecond attributes as time.

This is like crm_element_value() but returning value as a struct timeval.

Parameters

[in]	xml	XML to parse
[in]	name_sec	Name of XML attribute for seconds
[in]	name_usec	Name of XML attribute for microseconds
[out]	dest	Where to store result

Returns: pcmk_ok on success, -errno on error

Note: Values default to 0 if XML or XML attribute does not exist

Definition at line 680 of file nvpair.c.

◆ crm_meta_name()

char* crm_meta_name ( const char * attr_name )

Get the environment variable equivalent of a meta-attribute name.

Parameters

[in] attr_name Name of meta-attribute

Returns: Newly allocated string for attr_name with "CRM_meta_" prefix and underbars instead of dashes

Note: This asserts on an invalid argument or memory allocation error, so callers can assume the result is non-NULL. The caller is responsible for freeing the result using free().

Definition at line 1043 of file nvpair.c.

◆ crm_meta_value()

const char* crm_meta_value	(	GHashTable *	meta,
		const char *	attr_name
	)

Get the value of a meta-attribute.

Get the value of a meta-attribute from a hash table whose keys are meta-attribute environment variable names (as crm_meta_name() would create, like pcmk__graph_action_t:params, not pcmk_resource_t:meta).

Parameters

[in]	meta	Hash table of meta-attributes
[in]	attr_name	Name of meta-attribute to get

Returns: Value of given meta-attribute

Definition at line 1071 of file nvpair.c.

◆ crm_xml_add()

const char* crm_xml_add	(	xmlNode *	node,
		const char *	name,
		const char *	value
	)

Create an XML attribute with specified name and value.

Parameters

[in,out]	node	XML node to modify
[in]	name	Attribute name to set
[in]	value	Attribute value to set

Returns: New value on success, NULL otherwise

Note: This does nothing if node, name, or value are NULL or empty.

Definition at line 313 of file nvpair.c.

◆ crm_xml_add_int()

const char* crm_xml_add_int	(	xmlNode *	node,
		const char *	name,
		int	value
	)

Create an XML attribute with specified name and integer value.

This is like crm_xml_add() but taking an integer value.

Parameters

[in,out]	node	XML node to modify
[in]	name	Attribute name to set
[in]	value	Attribute value to set

Returns: New value as string on success, NULL otherwise

Note: This does nothing if node or name are NULL or empty.

Definition at line 360 of file nvpair.c.

◆ crm_xml_add_ll()

const char* crm_xml_add_ll	(	xmlNode *	xml,
		const char *	name,
		long long	value
	)

Create an XML attribute with specified name and long long int value.

This is like crm_xml_add() but taking a long long int value. It is a useful equivalent for defined types like time_t, etc.

Parameters

[in,out]	xml	XML node to modify
[in]	name	Attribute name to set
[in]	value	Attribute value to set

Returns: New value as string on success, NULL otherwise

Note: This does nothing if xml or name are NULL or empty. This does not support greater than 64-bit values.

Definition at line 410 of file nvpair.c.

◆ crm_xml_add_ms()

const char* crm_xml_add_ms	(	xmlNode *	node,
		const char *	name,
		guint	ms
	)

Create an XML attribute with specified name and unsigned value.

This is like crm_xml_add() but taking a guint value.

Parameters

[in,out]	node	XML node to modify
[in]	name	Attribute name to set
[in]	ms	Attribute value to set

Returns: New value as string on success, NULL otherwise

Note: This does nothing if node or name are NULL or empty.

Definition at line 382 of file nvpair.c.

◆ crm_xml_add_timeval()

const char* crm_xml_add_timeval	(	xmlNode *	xml,
		const char *	name_sec,
		const char *	name_usec,
		const struct timeval *	value
	)

Create XML attributes for seconds and microseconds.

This is like crm_xml_add() but taking a struct timeval.

Parameters

[in,out]	xml	XML node to modify
[in]	name_sec	Name of XML attribute for seconds
[in]	name_usec	Name of XML attribute for microseconds (or NULL)
[in]	value	Time value to set

Returns: New seconds value as string on success, NULL otherwise

Note: This does nothing if xml, name_sec, or value is NULL.

Definition at line 434 of file nvpair.c.

◆ hash2field()

void hash2field	(	gpointer	key,
		gpointer	value,
		gpointer	user_data
	)

Set XML attribute based on hash table entry.

Suitable for g_hash_table_foreach(), this function takes a hash table key and value, with an XML node passed as user data, and adds an XML attribute with the specified name and value if it does not already exist.

Parameters

[in]	key	Key of hash table entry
[in]	value	Value of hash table entry
[in,out]	user_data	XML node

Definition at line 820 of file nvpair.c.

◆ hash2metafield()

void hash2metafield	(	gpointer	key,
		gpointer	value,
		gpointer	user_data
	)

Set XML attribute based on hash table entry, as meta-attribute name.

Suitable for g_hash_table_foreach(), this function takes a hash table key and value, with an XML node passed as user data, and adds an XML attribute with the meta-attribute version of the specified name and value if it does not already exist and if the name does not appear to be cluster-internal.

Parameters

[in]	key	Key of hash table entry
[in]	value	Value of hash table entry
[in,out]	user_data	XML node

Definition at line 848 of file nvpair.c.

◆ hash2nvpair()

void hash2nvpair	(	gpointer	key,
		gpointer	value,
		gpointer	user_data
	)

Add XML nvpair element based on hash table entry.

Suitable for g_hash_table_foreach(), this function takes a hash table key and value, with an XML node passed as the user data, and adds an nvpair XML element with the specified name and value.

Parameters

[in]	key	Key of hash table entry
[in]	value	Value of hash table entry
[in,out]	user_data	XML node

Definition at line 918 of file nvpair.c.

◆ hash2smartfield()

void hash2smartfield	(	gpointer	key,
		gpointer	value,
		gpointer	user_data
	)

Safely add hash table entry to XML as attribute or name-value pair.

Suitable for g_hash_table_foreach(), this function takes a hash table key and value, with an XML node passed as user data, and adds an XML attribute with the specified name and value if it does not already exist. If the key name starts with a digit, then it's not a valid XML attribute name. In that case, this will instead add a

Parameters


  
    NAME child to the XML.
    [in] key Key of hash table entry 
    [in] value Value of hash table entry 
    [in,out] user_data XML node

Definition at line 778 of file nvpair.c.

◆ pcmk_free_nvpairs()

void pcmk_free_nvpairs ( GSList * nvpairs )

Free a list of name/value pairs.

Parameters

[in,out] list List to free

Definition at line 103 of file nvpair.c.

◆ pcmk_nvpairs2xml_attrs()

void pcmk_nvpairs2xml_attrs	(	GSList *	list,
		xmlNode *	xml
	)

Add XML attributes based on a list of name/value pairs.

Parameters

[in,out]	list	List of name/value pairs
[in,out]	xml	XML node to add attributes to

Definition at line 199 of file nvpair.c.

◆ pcmk_prepend_nvpair()

GSList* pcmk_prepend_nvpair	(	GSList *	nvpairs,
		const char *	name,
		const char *	value
	)

Prepend a name/value pair to a list.

Parameters

[in,out]	nvpairs	List to modify
[in]	name	New entry's name
[in]	value	New entry's value

Returns: New head of list

Note: The caller is responsible for freeing the list with pcmk_free_nvpairs().

Definition at line 92 of file nvpair.c.

◆ pcmk_sort_nvpairs()

GSList* pcmk_sort_nvpairs ( GSList * list )

Sort a list of name/value pairs.

Parameters

[in,out] list List to sort

Returns: New head of list

Definition at line 144 of file nvpair.c.

◆ pcmk_xml_attrs2nvpairs()

GSList* pcmk_xml_attrs2nvpairs ( const xmlNode * xml )

Create a list of name/value pairs from an XML node's attributes.

Parameters

[in] XML to parse

Returns: New list of name/value pairs

Note: It is the caller's responsibility to free the list with pcmk_free_nvpairs().

Definition at line 159 of file nvpair.c.

◆ xml2list()

GHashTable* xml2list ( const xmlNode * parent )

Retrieve XML attributes as a hash table.

Given an XML element, this will look for any <attributes> element child, creating a hash table of (newly allocated string) name/value pairs taken first from the attributes element's NAME=VALUE XML attributes, and then from any <param name=NAME value=VALUE> children of attributes.

Parameters

[in] XML node to parse

Returns: Hash table with name/value pairs

Note: It is the caller's responsibility to free the result using g_hash_table_destroy().

Definition at line 943 of file nvpair.c.

	NAME	child to the XML.
[in]	key	Key of hash table entry
[in]	value	Value of hash table entry
[in,out]	user_data	XML node

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ pcmk_nvpair_t

Function Documentation

◆ crm_create_nvpair_xml()

◆ crm_element_value()

◆ crm_element_value_copy()

◆ crm_element_value_epoch()

◆ crm_element_value_int()

◆ crm_element_value_ll()

◆ crm_element_value_ms()

◆ crm_element_value_timeval()

◆ crm_meta_name()

◆ crm_meta_value()

◆ crm_xml_add()

◆ crm_xml_add_int()

◆ crm_xml_add_ll()

◆ crm_xml_add_ms()

◆ crm_xml_add_timeval()

◆ hash2field()

◆ hash2metafield()

◆ hash2nvpair()

◆ hash2smartfield()

◆ pcmk_free_nvpairs()

◆ pcmk_nvpairs2xml_attrs()

◆ pcmk_prepend_nvpair()

◆ pcmk_sort_nvpairs()

◆ pcmk_xml_attrs2nvpairs()

◆ xml2list()