Collaboration diagram for Data Tree:

Modules
	Validity flags

	Diff options

	Data parser options

	Data path creation options

	Data duplication options

Data Structures
union	lyd_value_u
	node's value representation More...

struct	lyd_attr
	Attribute structure. More...

struct	lyd_node
	Generic structure for a data node, directly applicable to the data nodes defined as LYS_CONTAINER, LYS_LIST and LYS_CHOICE. More...

struct	lyd_node_leaf_list
	Structure for data nodes defined as LYS_LEAF or LYS_LEAFLIST. More...

union	lyd_anydata_value
	Anydata value union. More...

struct	lyd_node_anydata
	Structure for data nodes defined as LYS_ANYDATA or LYS_ANYXML. More...

struct	lyd_difflist
	Structure for the result of lyd_diff(), describing differences between two data trees. More...

Macros
#define	LY_VALUE_UNRES 0x01
	Flags for values. More...

#define	LY_VALUE_USER 0x02

#define	LYD_OPT_EXPLICIT 0x0100

#define	LY_TREE_FOR(START, ELEM)
	Macro to iterate via all sibling elements without affecting the list itself. More...

#define	LY_TREE_FOR_SAFE(START, NEXT, ELEM)
	Macro to iterate via all sibling elements allowing to modify the list itself (e.g. removing elements) More...

#define	LY_TREE_DFS_BEGIN(START, NEXT, ELEM)
	Macro to iterate via all elements in a tree. This is the opening part to the LY_TREE_DFS_END - they always have to be used together. More...

#define	TYPES_COMPATIBLE(type1, type2) _Generic(*(type1), type2: 1, default: 0)
	Macro to iterate via all elements in a tree. This is the closing part to the LY_TREE_DFS_BEGIN - they always have to be used together. More...

Typedefs
typedef union lyd_value_u	lyd_val
	node's value representation More...

Enumerations
enum	LYD_FORMAT { LYD_UNKNOWN, LYD_XML, LYD_JSON, LYD_LYB }
	Data input/output formats supported by libyang parser and printer functions. More...

enum	LYD_ANYDATA_VALUETYPE { LYD_ANYDATA_CONSTSTRING = 0x00, LYD_ANYDATA_STRING = 0x01, LYD_ANYDATA_JSON = 0x02, LYD_ANYDATA_JSOND = 0x03, LYD_ANYDATA_SXML = 0x04, LYD_ANYDATA_SXMLD = 0x05, LYD_ANYDATA_XML = 0x08, LYD_ANYDATA_DATATREE = 0x10, LYD_ANYDATA_LYB = 0x20, LYD_ANYDATA_LYBD = 0x21 }
	List of possible value types stored in lyd_node_anydata. More...

enum	LYD_DIFFTYPE { LYD_DIFF_END = 0, LYD_DIFF_DELETED, LYD_DIFF_CHANGED, LYD_DIFF_MOVEDAFTER1, LYD_DIFF_CREATED, LYD_DIFF_MOVEDAFTER2 }
	list of possible types of differences in lyd_difflist More...

Functions
void	lyd_free_diff (struct lyd_difflist *diff)
	Free the result of lyd_diff(). It frees the structure of the lyd_diff() result, not the referenced nodes. More...

struct lyd_difflist *	lyd_diff (struct lyd_node first, struct lyd_node second, int options)
	Compare two data trees and provide list of differences. More...

char *	lyd_path (const struct lyd_node *node)
	Build data path (usable as path, see howtoxpath) of the data node. More...

struct lyd_node *	lyd_parse_mem (struct ly_ctx ctx, const char data, LYD_FORMAT format, int options,...)
	Parse (and validate) data from memory. More...

struct lyd_node *	lyd_parse_fd (struct ly_ctx *ctx, int fd, LYD_FORMAT format, int options,...)
	Read (and validate) data from the given file descriptor. More...

struct lyd_node *	lyd_parse_path (struct ly_ctx ctx, const char path, LYD_FORMAT format, int options,...)
	Read (and validate) data from the given file path. More...

struct lyd_node *	lyd_parse_xml (struct ly_ctx ctx, struct lyxml_elem *root, int options,...)
	Parse (and validate) XML tree. More...

struct lyd_node *	lyd_new (struct lyd_node parent, const struct lys_module module, const char *name)
	Create a new container node in a data tree. More...

struct lyd_node *	lyd_new_leaf (struct lyd_node parent, const struct lys_module module, const char name, const char val_str)
	Create a new leaf or leaflist node in a data tree with a string value that is converted to the actual value. More...

int	lyd_change_leaf (struct lyd_node_leaf_list leaf, const char val_str)
	Change value of a leaf node. More...

struct lyd_node *	lyd_new_anydata (struct lyd_node parent, const struct lys_module module, const char name, void value, LYD_ANYDATA_VALUETYPE value_type)
	Create a new anydata or anyxml node in a data tree. More...

struct lyd_node *	lyd_new_output (struct lyd_node parent, const struct lys_module module, const char *name)
	Create a new container node in a data tree. Ignore RPC/action input nodes and instead use RPC/action output ones. More...

struct lyd_node *	lyd_new_output_leaf (struct lyd_node parent, const struct lys_module module, const char name, const char val_str)
	Create a new leaf or leaflist node in a data tree with a string value that is converted to the actual value. Ignore RPC/action input nodes and instead use RPC/action output ones. More...

struct lyd_node *	lyd_new_output_anydata (struct lyd_node parent, const struct lys_module module, const char name, void value, LYD_ANYDATA_VALUETYPE value_type)
	Create a new anydata or anyxml node in a data tree. Ignore RPC/action input nodes and instead use RPC/action output ones. More...

struct lyd_node *	lyd_new_yangdata (const struct lys_module module, const char name_template, const char *name)
	Create a new yang-data template in a data tree. It creates container, which name is in third parameter. More...

struct lyd_node *	lyd_new_path (struct lyd_node data_tree, const struct ly_ctx ctx, const char path, void value, LYD_ANYDATA_VALUETYPE value_type, int options)
	Create a new data node based on a simple XPath. More...

unsigned int	lyd_list_pos (const struct lyd_node *node)
	Learn the relative instance position of a list or leaf-list within other instances of the same schema node. More...

struct lyd_node *	lyd_dup (const struct lyd_node *node, int options)
	Create a copy of the specified data tree `node`. Schema references are kept the same. Use carefully, since libyang silently creates default nodes, it is always better to use lyd_dup_withsiblings() to duplicate the complete data tree. More...

struct lyd_node *	lyd_dup_withsiblings (const struct lyd_node *node, int options)
	Create a copy of the specified data tree and all its siblings (preceding as well as following). Schema references are kept the same. More...

struct lyd_node *	lyd_dup_to_ctx (const struct lyd_node node, int options, struct ly_ctx ctx)
	Create a copy of the specified data tree `node` in the different context. All the schema references and strings are re-mapped into the specified context. More...

int	lyd_merge (struct lyd_node target, const struct lyd_node source, int options)
	Merge a (sub)tree into a data tree. More...

int	lyd_merge_to_ctx (struct lyd_node *trg, const struct lyd_node src, int options, struct ly_ctx *ctx)
	Same as lyd_merge(), but moves the resulting data into the specified context. More...

int	lyd_insert (struct lyd_node parent, struct lyd_node node)
	Insert the `node` element as child to the `parent` element. The `node` is inserted as a last child of the `parent`. More...

int	lyd_insert_sibling (struct lyd_node *sibling, struct lyd_node node)
	Insert the `node` element as a last sibling of the specified `sibling` element. More...

int	lyd_insert_before (struct lyd_node sibling, struct lyd_node node)
	Insert the `node` element after the `sibling` element. If `node` and `siblings` are already siblings (just moving `node` position). More...

int	lyd_insert_after (struct lyd_node sibling, struct lyd_node node)
	Insert the `node` element after the `sibling` element. If `node` and `siblings` are already siblings (just moving `node` position). More...

int	lyd_schema_sort (struct lyd_node *sibling, int recursive)
	Order siblings according to the schema node ordering. More...

struct ly_set *	lyd_find_path (const struct lyd_node ctx_node, const char path)
	Search in the given data for instances of nodes matching the provided path. More...

struct ly_set *	lyd_find_instance (const struct lyd_node data, const struct lys_node schema)
	Search in the given data for instances of the provided schema node. More...

int	lyd_find_sibling (const struct lyd_node siblings, const struct lyd_node target, struct lyd_node **match)
	Search in the given siblings for the target instance. If cache is enabled and the siblings are NOT top-level nodes, this function finds the node in a constant time! More...

int	lyd_find_sibling_set (const struct lyd_node siblings, const struct lyd_node target, struct ly_set **set)
	Search in the given siblings for all target instances. If cache is enabled and the siblings are NOT top-level nodes, this function finds the node(s) in a constant time! More...

int	lyd_find_sibling_val (const struct lyd_node siblings, const struct lys_node schema, const char key_or_value, struct lyd_node *match)
	Search in the given siblings for the schema instance. If cache is enabled and the siblings are NOT top-level nodes, this function finds the node in a constant time! More...

struct lyd_node *	lyd_first_sibling (struct lyd_node *node)
	Get the first sibling of the given node. More...

int	lyd_validate (struct lyd_node *node, int options, void var_arg,...)
	Validate `node` data subtree. More...

int	lyd_validate_modules (struct lyd_node node, const struct lys_module modules, int mod_count, int options,...)
	Validate `node` data tree but only subtrees that belong to the schema found in `modules`. All other schemas are effectively disabled for the validation. More...

void	lyd_free_val_diff (struct lyd_difflist *diff)
	Free special diff that was returned by lyd_validate() or lyd_validate_modules(). More...

int	lyd_validate_value (struct lys_node node, const char value)
	Check restrictions applicable to the particular leaf/leaf-list on the given string value. More...

int	lyd_value_type (struct lys_node node, const char value, struct lys_type **type)
	Check restrictions applicable to the particular leaf/leaf-list on the given string value and optionally return its final type. More...

int	lyd_wd_default (struct lyd_node_leaf_list *node)
	Get know if the node contain (despite implicit or explicit) default value. More...

int	lyd_node_should_print (const struct lyd_node *node, int options)
	Learn if a node is supposed to be printed based on the options. More...

int	lyd_unlink (struct lyd_node *node)
	Unlink the specified data subtree. All referenced namespaces are copied. More...

void	lyd_free (struct lyd_node *node)
	Free (and unlink) the specified data subtree. Use carefully, since libyang silently creates default nodes, it is always better to use lyd_free_withsiblings() to free the complete data tree. More...

void	lyd_free_withsiblings (struct lyd_node *node)
	Free (and unlink) the specified data tree and all its siblings (preceding as well as following). More...

struct lyd_attr *	lyd_insert_attr (struct lyd_node parent, const struct lys_module mod, const char name, const char value)
	Insert attribute into the data node. More...

void	lyd_free_attr (struct ly_ctx ctx, struct lyd_node parent, struct lyd_attr *attr, int recursive)
	Destroy data attribute. More...

struct lys_module *	lyd_node_module (const struct lyd_node *node)
	Return main module of the data tree node. More...

struct lys_type *	lyd_leaf_type (const struct lyd_node_leaf_list *leaf)
	Get the type structure of a leaf. More...

int	lyd_print_mem (char *strp, const struct lyd_node root, LYD_FORMAT format, int options)
	Print data tree in the specified format. More...

int	lyd_print_fd (int fd, const struct lyd_node *root, LYD_FORMAT format, int options)
	Print data tree in the specified format. More...

int	lyd_print_file (FILE f, const struct lyd_node root, LYD_FORMAT format, int options)
	Print data tree in the specified format. More...

int	lyd_print_path (const char path, const struct lyd_node root, LYD_FORMAT format, int options)
	Print data tree in the specified format. More...

int	lyd_print_clb (ssize_t(writeclb)(void arg, const void buf, size_t count), void arg, const struct lyd_node *root, LYD_FORMAT format, int options)
	Print data tree in the specified format. More...

double	lyd_dec64_to_double (const struct lyd_node *node)
	Get the double value of a decimal64 leaf/leaf-list. More...

int	lyd_lyb_data_length (const char *data)
	Get the length of a printed LYB data tree. More...

Detailed Description

Data structures and functions to manipulate and access instance data tree.

Data Structure Documentation

union lyd_value_u

node's value representation

Definition at line 94 of file tree_data.h.

Data Fields
const char *	binary	base64 encoded, NULL terminated string
struct lys_type_bit **	bit	bitmap of pointers to the schema definition of the bit value that are set, its size is always the number of defined bits in the schema
int8_t	bln	0 as false, 1 as true
int64_t	dec64	decimal64: value = dec64 / 10^fraction-digits
struct lys_type_enum *	enm	pointer to the schema definition of the enumeration value
struct lys_ident *	ident	pointer to the schema definition of the identityref value
struct lyd_node *	instance	pointer to the instance-identifier target, note that if the tree was modified, the target (address) can be invalid - the pointer is correctly checked and updated by lyd_validate()
int8_t	int8	8-bit signed integer
int16_t	int16	16-bit signed integer
int32_t	int32	32-bit signed integer
int64_t	int64	64-bit signed integer
struct lyd_node *	leafref	pointer to the referenced leaf/leaflist instance in data tree
const char *	string	string
uint8_t	uint8	8-bit unsigned integer
uint16_t	uint16	16-bit signed integer
uint32_t	uint32	32-bit signed integer
uint64_t	uint64	64-bit signed integer
void *	ptr	arbitrary data stored using a type plugin

struct lyd_attr

Attribute structure.

The structure provides information about attributes of a data element. Such attributes must map to annotations as specified in RFC 7952. The only exception is the filter type (in NETCONF get operations) and edit-config's operation attributes. In XML, they are represented as standard XML attributes. In JSON, they are represented as JSON elements starting with the '@' character (for more information, see the YANG metadata RFC.

Definition at line 128 of file tree_data.h.

Data Fields
struct lyd_node *	parent	data node where the attribute is placed
struct lyd_attr *	next	pointer to the next attribute of the same element
struct lys_ext_instance_complex *	annotation	pointer to the attribute/annotation's definition
const char *	name	attribute name
const char *	value_str	string representation of value (for comparison, printing,...), always corresponds to value_type
lyd_val	value	node's value representation, always corresponds to schema->type.base
LY_DATA_TYPE _PACKED	value_type	type of the value in the node, mainly for union to avoid repeating of type detection
uint8_t	value_flags	value type flags

struct lyd_node

Generic structure for a data node, directly applicable to the data nodes defined as LYS_CONTAINER, LYS_LIST and LYS_CHOICE.

Completely fits to containers and choices and is compatible (can be used interchangeably except the child member) with all other lyd_node_* structures. All data nodes are provides as lyd_node structure by default. According to the schema's lys_node::nodetype member, the specific object is supposed to be cast to lyd_node_leaf_list or lyd_node_anydata structures. This structure fits only to LYS_CONTAINER, LYS_LIST and LYS_CHOICE values.

To traverse all the child elements or attributes, use LY_TREE_FOR or LY_TREE_FOR_SAFE macro. To traverse the whole subtree, use LY_TREE_DFS_BEGIN macro.

Definition at line 183 of file tree_data.h.

Data Fields
struct lys_node *	schema	pointer to the schema definition of this node
uint8_t	validity	validity flags
uint8_t	dflt:1	flag for implicit default node
uint8_t	when_status:3	bit for checking if the when-stmt condition is resolved - internal use only, do not use this value!
struct lyd_attr *	attr	pointer to the list of attributes of this node
struct lyd_node *	next	pointer to the next sibling node (NULL if there is no one)
struct lyd_node *	prev	pointer to the previous sibling node Note Note that this pointer is never NULL. If there is no sibling node, pointer points to the node itself. In case of the first node, this pointer points to the last node in the list.
struct lyd_node *	parent	pointer to the parent node, NULL in case of root node
struct lyd_node *	child	pointer to the first child node Note Since other lyd_node_* structures represent end nodes, this member is replaced in those structures. Therefore, be careful with accessing this member without having information about the node type from the schema's lys_node::nodetype member.

struct lyd_node_leaf_list

Structure for data nodes defined as LYS_LEAF or LYS_LEAFLIST.

Extension for lyd_node structure. It replaces the lyd_node::child member by three new members (value, value_str and value_type) to provide information about the value. The first five members (schema, attr, next, prev and parent) are compatible with the lyd_node's members.

To traverse through all the child elements or attributes, use LY_TREE_FOR or LY_TREE_FOR_SAFE macro.

Definition at line 224 of file tree_data.h.

Data Fields
struct lys_node *	schema	pointer to the schema definition of this node which is lys_node_leaflist structure
uint8_t	validity	validity flags
uint8_t	dflt:1	flag for implicit default node
uint8_t	when_status:3	bit for checking if the when-stmt condition is resolved - internal use only, do not use this value!
struct lyd_attr *	attr	pointer to the list of attributes of this node
struct lyd_node *	next	pointer to the next sibling node (NULL if there is no one)
struct lyd_node *	prev	pointer to the previous sibling node Note Note that this pointer is never NULL. If there is no sibling node, pointer points to the node itself. In case of the first node, this pointer points to the last node in the list.
struct lyd_node *	parent	pointer to the parent node, NULL in case of root node
const char *	value_str	string representation of value (for comparison, printing,...), always corresponds to value_type
lyd_val	value	node's value representation, always corresponds to schema->type.base
LY_DATA_TYPE _PACKED	value_type	type of the value in the node, mainly for union to avoid repeating of type detection
uint8_t	value_flags	value type flags

union lyd_anydata_value

Anydata value union.

Definition at line 271 of file tree_data.h.

Data Fields
const char *	str	string value, in case of printing as XML, characters like '<' or '&' are escaped
char *	mem	raw memory (used for LYB format)
struct lyxml_elem *	xml	xml tree
struct lyd_node *	tree	libyang data tree, does not change the root's parent, so it is not possible to get from the data tree into the anydata/anyxml

struct lyd_node_anydata

Structure for data nodes defined as LYS_ANYDATA or LYS_ANYXML.

Extension for lyd_node structure - replaces the lyd_node::child member by new value member. The first five members (schema, attr, next, prev and parent) are compatible with the lyd_node's members.

To traverse through all the child elements or attributes, use LY_TREE_FOR or LY_TREE_FOR_SAFE macro.

Definition at line 287 of file tree_data.h.

Data Fields
struct lys_node *	schema	pointer to the schema definition of this node which is lys_node_anydata structure
uint8_t	validity	validity flags
uint8_t	dflt:1	flag for implicit default node
uint8_t	when_status:3	bit for checking if the when-stmt condition is resolved - internal use only, do not use this value!
struct lyd_attr *	attr	pointer to the list of attributes of this node
struct lyd_node *	next	pointer to the next sibling node (NULL if there is no one)
struct lyd_node *	prev	pointer to the previous sibling node Note Note that this pointer is never NULL. If there is no sibling node, pointer points to the node itself. In case of the first node, this pointer points to the last node in the list.
struct lyd_node *	parent	pointer to the parent node, NULL in case of root node
LYD_ANYDATA_VALUETYPE	value_type	type of the stored anydata value
lyd_anydata_value	value	stored anydata value

struct lyd_difflist

Structure for the result of lyd_diff(), describing differences between two data trees.

Definition at line 364 of file tree_data.h.

Data Fields
LYD_DIFFTYPE *	type	array of the differences types, terminated by LYD_DIFF_END value.
struct lyd_node **	first	array of nodes in the first tree for the specific type of difference, see the description of LYD_DIFFTYPE values for more information.
struct lyd_node **	second	array of nodes in the second tree for the specific type of difference, see the description of LYD_DIFFTYPE values for more information.

Macro Definition Documentation

#define LY_VALUE_UNRES 0x01

Flags for values.

flag for unresolved leafref or instance-identifier, leafref - value union is filled as if being the target node's type, instance-identifier - value union should not be accessed

Definition at line 260 of file tree_data.h.

#define LY_VALUE_USER 0x02

flag for a user type stored value

Definition at line 265 of file tree_data.h.

#define LYD_OPT_EXPLICIT 0x0100

Definition at line 1100 of file tree_data.h.

#define LY_TREE_FOR	(	START,
		ELEM
	)

Value:

for ((ELEM) = (START); \
         (ELEM); \
         (ELEM) = (ELEM)->next)

Macro to iterate via all sibling elements without affecting the list itself.

Works for all types of nodes despite it is data or schema tree, but all the parameters must be pointers to the same type.

Use with opening curly bracket '{'. All parameters must be of the same type.

Parameters

START	Pointer to the starting element.
ELEM	Iterator.

Definition at line 40 of file tree_schema.h.

#define LY_TREE_FOR_SAFE	(	START,
		NEXT,
		ELEM
	)

Value:

for ((ELEM) = (START); \
         (ELEM) ? (NEXT = (ELEM)->next, 1) : 0; \
         (ELEM) = (NEXT))

Macro to iterate via all sibling elements allowing to modify the list itself (e.g. removing elements)

Works for all types of nodes despite it is data or schema tree, but all the parameters must be pointers to the same type.

Use with opening curly bracket '{'. All parameters must be of the same type.

Parameters

START	Pointer to the starting element.
NEXT	Temporary storage to allow removing of the current iterator content.
ELEM	Iterator.

Definition at line 58 of file tree_schema.h.

#define LY_TREE_DFS_BEGIN	(	START,
		NEXT,
		ELEM
	)

Value:

for ((ELEM) = (NEXT) = (START);                                           \
         (ELEM);                                                              \
         (ELEM) = (NEXT))

Macro to iterate via all elements in a tree. This is the opening part to the LY_TREE_DFS_END - they always have to be used together.

The function follows deep-first search algorithm:

Works for all types of nodes despite it is data or schema tree, but all the parameters must be pointers to the same type. Use the same parameters for LY_TREE_DFS_BEGIN and LY_TREE_DFS_END.

Since the next node is selected as part of LY_TREE_DFS_END, do not use continue statement between the LY_TREE_DFS_BEGIN and LY_TREE_DFS_END.

Use with opening curly bracket '{' after the macro.

Parameters

START	Pointer to the starting element processed first.
NEXT	Temporary storage, do not use.
ELEM	Iterator intended for use in the block.

Definition at line 90 of file tree_schema.h.

#define TYPES_COMPATIBLE	(	type1,
		type2
	)	_Generic(*(type1), type2: 1, default: 0)

Macro to iterate via all elements in a tree. This is the closing part to the LY_TREE_DFS_BEGIN - they always have to be used together.

Works for all types of nodes despite it is data or schema tree, but all the parameters must be pointers to the same type - basic type of the tree (struct lys_node*, struct lyd_node* or struct lyxml_elem*). Use the same parameters for LY_TREE_DFS_BEGIN and LY_TREE_DFS_END. If the START parameter is a derived type (e.g. lys_node_leaf), caller is supposed to cast it to the base type identical to the other parameters.

Use with closing curly bracket '}' after the macro.

Parameters

START	Pointer to the starting element processed first.
NEXT	Temporary storage, do not use.
ELEM	Iterator intended for use in the block.

Definition at line 119 of file tree_schema.h.

Typedef Documentation

typedef union lyd_value_u lyd_val

node's value representation

Enumeration Type Documentation

enum LYD_FORMAT

Data input/output formats supported by libyang parser and printer functions.

Enumerator
LYD_UNKNOWN	unknown format, used as return value in case of error
LYD_XML	XML format of the instance data
LYD_JSON	JSON format of the instance data
LYD_LYB	LYB format of the instance data

Definition at line 40 of file tree_data.h.

enum LYD_ANYDATA_VALUETYPE

List of possible value types stored in lyd_node_anydata.

Enumerator
LYD_ANYDATA_CONSTSTRING	value is constant string (const char *) which is internally duplicated for storing in the anydata structure; XML sensitive characters (such as & or >) are automatically escaped when the anydata is printed in XML format.
LYD_ANYDATA_STRING	value is dynamically allocated string (char*), so the data are used directly without duplication and caller is supposed to not manipulate with the data after a successful call (including calling free() on the provided data); XML sensitive characters (such as & or >) are automatically escaped when the anydata is printed in XML format
LYD_ANYDATA_JSON	value is string containing the data modeled by YANG and encoded as I-JSON. The string is handled as constant string. In case of using the value as input parameter, the LYD_ANYDATA_JSOND can be used for dynamically allocated string.
LYD_ANYDATA_JSOND	In case of using value as input parameter, this enumeration is supposed to be used for dynamically allocated strings (it is actually combination of LYD_ANYDATA_JSON and LYD_ANYDATA_STRING (and it can be also specified as ORed value of the mentioned values.
LYD_ANYDATA_SXML	value is string containing the serialized XML data. The string is handled as constant string. In case of using the value as input parameter, the LYD_ANYDATA_SXMLD can be used for dynamically allocated string.
LYD_ANYDATA_SXMLD	In case of using serialized XML value as input parameter, this enumeration is supposed to be used for dynamically allocated strings (it is actually combination of LYD_ANYDATA_SXML and LYD_ANYDATA_STRING (and it can be also specified as ORed value of the mentioned values).
LYD_ANYDATA_XML	value is struct lyxml_elem*, the structure is directly connected into the anydata node without duplication, caller is supposed to not manipulate with the data after a successful call (including calling lyxml_free() on the provided data)
LYD_ANYDATA_DATATREE	value is struct lyd_node* (first sibling), the structure is directly connected into the anydata node without duplication, caller is supposed to not manipulate with the data after a successful call (including calling lyd_free() on the provided data)
LYD_ANYDATA_LYB	value is a memory with serialized data tree in LYB format. The data are handled as a constant string. In case of using the value as input parameter, the LYD_ANYDATA_LYBD can be used for dynamically allocated string.
LYD_ANYDATA_LYBD	In case of using LYB value as input parameter, this enumeration is supposed to be used for dynamically allocated strings (it is actually combination of LYD_ANYDATA_LYB and LYD_ANYDATA_STRING (and it can be also specified as ORed value of the mentioned values).

Definition at line 50 of file tree_data.h.

enum LYD_DIFFTYPE

list of possible types of differences in lyd_difflist

Enumerator
LYD_DIFF_END	end of the differences list
LYD_DIFF_DELETED	deleted node Node is present in the first tree, but not in the second tree. To make both trees the same the node in lyd_difflist::first can be deleted from the first tree. The pointer at the same index in the lyd_difflist::second array is NULL. If the deleted node has some children, these do not appear in the resulting diff separately. In other words, a deleted node is considered deleted with all its children.
LYD_DIFF_CHANGED	value of a leaf or anyxml is changed, the lyd_difflist::first and lyd_difflist::second points to the leaf/anyxml instances in the first and the second tree respectively.
LYD_DIFF_MOVEDAFTER1	user-ordered (leaf-)list item was moved. To make both trees the same, all LYD_DIFF_MOVEDAFTER1 transactions must be applied to the first tree in the strict order they appear in the difflist. The lyd_difflist::first points to the first tree node being moved and the lyd_difflist::second points to the first tree node after which the first node is supposed to be moved. If the second pointer is NULL, the node is being moved into the beginning as the first node of the (leaf-)list instances.
LYD_DIFF_CREATED	newly created node Node is present in the second tree, but not in the first tree. To make both trees the same the node in lyd_difflist::second is supposed to be inserted (copied via lyd_dup()) into the node (as a child) at the same index in the lyd_difflist::first array (where is its parent). If the lyd_difflist::first at the index is NULL, the missing node is top-level. If the created node has some children, these do not appear in the resulting diff separately. In other words, a created node is considered created with all its children.
LYD_DIFF_MOVEDAFTER2	similar to LYD_DIFF_MOVEDAFTER1, but this time the moved item is in the second tree. This type is always used in combination with (as a successor of) LYD_DIFF_CREATED as an instruction to move the newly created node to a specific position. If it is not present, it means that even the parent of the user-ordered instances did not exist (or was empty) so it is safe to just create the instances in the same order. Note, that due to applicability to the second tree, the meaning of lyd_difflist:first and lyd_difflist:second is inverse in comparison to LYD_DIFF_MOVEDAFTER1. The lyd_difflist::second points to the (previously) created node in the second tree and the lyd_difflist::first points to the predecessor node in the second tree. If the predecessor is NULL, the node is supposed to bes the first sibling.

Definition at line 321 of file tree_data.h.

Function Documentation

void lyd_free_diff ( struct lyd_difflist * diff )

Free the result of lyd_diff(). It frees the structure of the lyd_diff() result, not the referenced nodes.

Parameters

[in] diff The lyd_diff() result to free.

struct lyd_difflist* lyd_diff	(	struct lyd_node *	first,
		struct lyd_node *	second,
		int	options
	)

Compare two data trees and provide list of differences.

Note, that the first and the second must have the same schema parent (or they must be top-level elements). In case of using LYD_OPT_NOSIBLINGS, they both must be instances of the same schema node.

Order of the resulting set follows these rules:

To change the first tree into the second tree, the resulting transactions are supposed to be applied in the order they appear in the result. First, the changed (LYD_DIFF_CHANGED) nodes are described followed by the deleted (LYD_DIFF_DELETED) nodes. Then, the moving of the user-ordered nodes present in both trees (LYD_DIFF_MOVEDAFTER1) follows and the last transactions in the results are the newly created (LYD_DIFF_CREATED) nodes. These nodes are supposed to be added as the last siblings, but in some case they can need additional move. In such a case, the LYD_DIFF_MOVEDAFTER2 transactions can appear.
The order of the changed (LYD_DIFF_CHANGED) and created (LYD_DIFF_CREATED) follows the nodes order in the second tree - the current siblings are processed first and then the children are processed. Note, that this is actually not the BFS:
```
    1     2
   / \   / \
  3   4 7   8
 / \
5   6
```
The order of the deleted (LYD_DIFF_DELETED) nodes is the DFS:
```
    1     6
   / \   / \
  2   5 7   8
 / \
3   4
```

To change the first tree into the second one, it is necessary to follow the order of transactions described in the result. Note, that it is not possible just to use the transactions in the reverse order to transform the second tree into the first one. The transactions can be generalized (to be used on a different instance of the first tree) using lyd_path() to get identifiers for the nodes used in the transactions.

Parameters

[in]	first	The first (sub)tree to compare. Without LYD_OPT_NOSIBLINGS option, all siblings are taken into comparison. If NULL, all the `second` nodes are supposed to be top level and they will be marked as LYD_DIFF_CREATED.
[in]	second	The second (sub)tree to compare. Without LYD_OPT_NOSIBLINGS option, all siblings are taken into comparison. If NULL, all the `first` nodes will be marked as LYD_DIFF_DELETED.
[in]	options	The Diff options are accepted.

Returns: NULL on error, the list of differences on success. In case the trees are the same, the first item in the lyd_difflist::type array is LYD_DIFF_END. The returned structure is supposed to be freed by lyd_free_diff().

char* lyd_path ( const struct lyd_node * node )

Build data path (usable as path, see howtoxpath) of the data node.

Parameters

[in] node Data node to be processed. Note that the node should be from a complete data tree, having a subtree (after using lyd_unlink()) can cause generating invalid paths.

Returns: NULL on error, on success the buffer for the resulting path is allocated and caller is supposed to free it with free().

struct lyd_node* lyd_parse_mem	(	struct ly_ctx *	ctx,
		const char *	data,
		LYD_FORMAT	format,
		int	options,
			...
	)

Parse (and validate) data from memory.

In case of LY_XML format, the data string is parsed completely. It means that when it contains a non well-formed XML with multiple root elements, all those sibling XML trees are parsed. The returned data node is a root of the first tree with other trees connected via the next pointer. This behavior can be changed by LYD_OPT_NOSIBLINGS option.

Parameters

[in]	ctx	Context to connect with the data tree being built here.
[in]	data	Serialized data in the specified format.
[in]	format	Format of the input data to be parsed.
[in]	options	Parser options, see Data parser options.
[in]	...	Variable arguments depend on `options`. If they include: LYD_OPT_DATA: LYD_OPT_CONFIG: LYD_OPT_GET: LYD_OPT_GETCONFIG: LYD_OPT_EDIT: no variable arguments expected. LYD_OPT_RPC: LYD_OPT_NOTIF: struct lyd_node data_tree - additional validated* top-level siblings of a data tree that will be used when checking any references ("when", "must" conditions, leafrefs, ...) in the action/nested notification subtree that require some nodes outside their subtree. It is assumed that all parents of the action/nested notification exist as required (RFC ref). LYD_OPT_RPCREPLY: const struct lyd_node rpc_act - pointer to the whole RPC or (top-level) action operation data tree (the request) of the reply. const struct lyd_node data_tree - additional validated top-level siblings of a data tree that will be used when checking any references ("when", "must" conditions, leafrefs, ...) that require some nodes outside their subtree.

Returns: Pointer to the built data tree or NULL in case of empty data. To free the returned structure, use lyd_free(). In these cases, the function sets #ly_errno to LY_SUCCESS. In case of error, #ly_errno contains appropriate error code (see #LY_ERR).

struct lyd_node* lyd_parse_fd	(	struct ly_ctx *	ctx,
		int	fd,
		LYD_FORMAT	format,
		int	options,
			...
	)

Read (and validate) data from the given file descriptor.

Note: Current implementation supports only reading data from standard (disk) file, not from sockets, pipes, etc.

In case of LY_XML format, the file content is parsed completely. It means that when it contains a non well-formed XML with multiple root elements, all those sibling XML trees are parsed. The returned data node is a root of the first tree with other trees connected via the next pointer. This behavior can be changed by LYD_OPT_NOSIBLINGS option.

Parameters

[in]	ctx	Context to connect with the data tree being built here.
[in]	fd	The standard file descriptor of the file containing the data tree in the specified format.
[in]	format	Format of the input data to be parsed.
[in]	options	Parser options, see Data parser options.
[in]	...	Variable arguments depend on `options`. If they include: LYD_OPT_DATA: LYD_OPT_CONFIG: LYD_OPT_GET: LYD_OPT_GETCONFIG: LYD_OPT_EDIT: no variable arguments expected. LYD_OPT_RPC: LYD_OPT_NOTIF: struct lyd_node data_tree - additional validated* top-level siblings of a data tree that will be used when checking any references ("when", "must" conditions, leafrefs, ...) in the action/nested notification subtree that require some nodes outside their subtree. It is assumed that all parents of the action/nested notification exist as required (RFC ref). LYD_OPT_RPCREPLY: const struct lyd_node rpc_act - pointer to the whole RPC or action operation data tree (the request) of the reply. const struct lyd_node data_tree - additional validated top-level siblings of a data tree that will be used when checking any references ("when", "must" conditions, leafrefs, ...) that require some nodes outside their subtree.

Returns: Pointer to the built data tree or NULL in case of empty file. To free the returned structure, use lyd_free(). In these cases, the function sets #ly_errno to LY_SUCCESS. In case of error, #ly_errno contains appropriate error code (see #LY_ERR).

struct lyd_node* lyd_parse_path	(	struct ly_ctx *	ctx,
		const char *	path,
		LYD_FORMAT	format,
		int	options,
			...
	)

Read (and validate) data from the given file path.

In case of LY_XML format, the file content is parsed completely. It means that when it contains a non well-formed XML with multiple root elements, all those sibling XML trees are parsed. The returned data node is a root of the first tree with other trees connected via the next pointer. This behavior can be changed by LYD_OPT_NOSIBLINGS option.

Parameters

[in]	ctx	Context to connect with the data tree being built here.
[in]	path	Path to the file containing the data tree in the specified format.
[in]	format	Format of the input data to be parsed.
[in]	options	Parser options, see Data parser options.
[in]	...	Variable arguments depend on `options`. If they include: LYD_OPT_DATA: LYD_OPT_CONFIG: LYD_OPT_GET: LYD_OPT_GETCONFIG: LYD_OPT_EDIT: no variable arguments expected. LYD_OPT_RPC: LYD_OPT_NOTIF: struct lyd_node data_tree - additional validated* top-level siblings of a data tree that will be used when checking any references ("when", "must" conditions, leafrefs, ...) in the action/nested notification subtree that require some nodes outside their subtree. It is assumed that all parents of the action/nested notification exist as required (RFC ref). LYD_OPT_RPCREPLY: const struct lyd_node rpc_act - pointer to the whole RPC or action operation data tree (the request) of the reply. const struct lyd_node data_tree - additional validated top-level siblings of a data tree that will be used when checking any references ("when", "must" conditions, leafrefs, ...) that require some nodes outside their subtree.

Returns: Pointer to the built data tree or NULL in case of empty file. To free the returned structure, use lyd_free(). In these cases, the function sets #ly_errno to LY_SUCCESS. In case of error, #ly_errno contains appropriate error code (see #LY_ERR).

struct lyd_node* lyd_parse_xml	(	struct ly_ctx *	ctx,
		struct lyxml_elem **	root,
		int	options,
			...
	)

Parse (and validate) XML tree.

The output data tree is parsed from the given XML tree previously parsed by one of the lyxml_read* functions.

If there are some sibling elements of the root (data were read with LYXML_PARSE_MULTIROOT option or the provided root is a root element of a subtree), all the sibling nodes (previous as well as following) are processed as well. The returned data node is a root of the first tree with other trees connected via the next pointer. This behavior can be changed by LYD_OPT_NOSIBLINGS option.

When the function is used with LYD_OPT_DESTRUCT, all the successfully parsed data including the XML root and all its siblings (if LYD_OPT_NOSIBLINGS is not used) are freed. Only with LYD_OPT_DESTRUCT option the root pointer is changed - if all the data are parsed, it is set to NULL, otherwise it will hold the XML tree without the successfully parsed elements.

The context must be the same as the context used to parse XML tree by lyxml_read* function.

Parameters

[in]	ctx	Context to connect with the data tree being built here.
[in,out]	root	XML tree to parse (convert) to data tree. By default, parser do not change the XML tree. However, when LYD_OPT_DESTRUCT is specified in `options`, parser frees all successfully parsed data.
[in]	options	Parser options, see Data parser options.
[in]	...	Variable arguments depend on `options`. If they include: LYD_OPT_DATA: LYD_OPT_CONFIG: LYD_OPT_GET: LYD_OPT_GETCONFIG: LYD_OPT_EDIT: no variable arguments expected. LYD_OPT_RPC: LYD_OPT_NOTIF: struct lyd_node data_tree - additional validated* top-level siblings of a data tree that will be used when checking any references ("when", "must" conditions, leafrefs, ...) in the action/nested notification subtree that require some nodes outside their subtree. It is assumed that all parents of the action/nested notification exist as required (RFC ref). LYD_OPT_RPCREPLY: const struct lyd_node rpc_act - pointer to the whole RPC or action operation data tree (the request) of the reply. const struct lyd_node data_tree - additional validated top-level siblings of a data tree that will be used when checking any references ("when", "must" conditions, leafrefs, ...) that require some nodes outside their subtree.

Returns: Pointer to the built data tree or NULL in case of empty root. To free the returned structure, use lyd_free(). In these cases, the function sets #ly_errno to LY_SUCCESS. In case of error, #ly_errno contains appropriate error code (see #LY_ERR).

struct lyd_node* lyd_new	(	struct lyd_node *	parent,
		const struct lys_module *	module,
		const char *	name
	)

Create a new container node in a data tree.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

Parameters

[in]	parent	Parent node for the node being created. NULL in case of creating top level element.
[in]	module	Module with the node being created.
[in]	name	Schema node name of the new data node. The node can be LYS_CONTAINER, LYS_LIST, LYS_NOTIF, LYS_RPC, or LYS_ACTION.

Returns: New node, NULL on error.

struct lyd_node* lyd_new_leaf	(	struct lyd_node *	parent,
		const struct lys_module *	module,
		const char *	name,
		const char *	val_str
	)

Create a new leaf or leaflist node in a data tree with a string value that is converted to the actual value.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

Parameters

[in]	parent	Parent node for the node being created. NULL in case of creating top level element.
[in]	module	Module with the node being created.
[in]	name	Schema node name of the new data node.
[in]	val_str	String form of the value of the node being created. In case the type is LY_TYPE_INST or LY_TYPE_IDENT, JSON node-id format is expected (nodes are prefixed with module names, not XML namespaces).

Returns: New node, NULL on error.

int lyd_change_leaf	(	struct lyd_node_leaf_list *	leaf,
		const char *	val_str
	)

Change value of a leaf node.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

Despite the prototype allows to provide a leaflist node as leaf parameter, only leafs are accepted. Also, the leaf will never be default after calling this function successfully.

Parameters

[in]	leaf	A leaf node to change.
[in]	val_str	String form of the new value to be set to the `leaf`. In case the type is LY_TYPE_INST or LY_TYPE_IDENT, JSON node-id format is expected (nodes are prefixed with module names, not XML namespaces).

Returns: 0 if the leaf was changed successfully (either its value changed or at least its default flag was cleared), <0 on error, 1 if the (canonical) value matched the original one and no value neither default flag change occurred.

struct lyd_node* lyd_new_anydata	(	struct lyd_node *	parent,
		const struct lys_module *	module,
		const char *	name,
		void *	value,
		LYD_ANYDATA_VALUETYPE	value_type
	)

Create a new anydata or anyxml node in a data tree.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

This function is supposed to be a replacement for the lyd_new_anyxml_str() and lyd_new_anyxml_xml().

Parameters

[in]	parent	Parent node for the node being created. NULL in case of creating top level element.
[in]	module	Module with the node being created.
[in]	name	Schema node name of the new data node. The schema node determines if the anydata or anyxml node is created.
[in]	value	Pointer to the value data to be stored in the anydata/anyxml node. The type of the data is determined according to the `value_type` parameter.
[in]	value_type	Type of the provided data `value`.

Returns: New node, NULL on error.

struct lyd_node* lyd_new_output	(	struct lyd_node *	parent,
		const struct lys_module *	module,
		const char *	name
	)

Create a new container node in a data tree. Ignore RPC/action input nodes and instead use RPC/action output ones.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

Parameters

[in]	parent	Parent node for the node being created. NULL in case of creating top level element.
[in]	module	Module with the node being created.
[in]	name	Schema node name of the new data node. The node should only be LYS_CONTAINER or LYS_LIST, but accepted are also LYS_NOTIF, LYS_RPC, or LYS_ACTION.

Returns: New node, NULL on error.

struct lyd_node* lyd_new_output_leaf	(	struct lyd_node *	parent,
		const struct lys_module *	module,
		const char *	name,
		const char *	val_str
	)

Create a new leaf or leaflist node in a data tree with a string value that is converted to the actual value. Ignore RPC/action input nodes and instead use RPC/action output ones.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

Parameters

[in]	parent	Parent node for the node being created. NULL in case of creating top level element.
[in]	module	Module with the node being created.
[in]	name	Schema node name of the new data node.
[in]	val_str	String form of the value of the node being created. In case the type is LY_TYPE_INST or LY_TYPE_IDENT, JSON node-id format is expected (nodes are prefixed with module names, not XML namespaces).

Returns: New node, NULL on error.

struct lyd_node* lyd_new_output_anydata	(	struct lyd_node *	parent,
		const struct lys_module *	module,
		const char *	name,
		void *	value,
		LYD_ANYDATA_VALUETYPE	value_type
	)

Create a new anydata or anyxml node in a data tree. Ignore RPC/action input nodes and instead use RPC/action output ones.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

Parameters

[in]	parent	Parent node for the node being created. NULL in case of creating top level element.
[in]	module	Module with the node being created.
[in]	name	Schema node name of the new data node. The schema node determines if the anydata or anyxml node is created.
[in]	value	Pointer to the value data to be stored in the anydata/anyxml node. The type of the data is determined according to the `value_type` parameter. Data are supposed to be dynamically allocated. Since it is directly attached into the created data node, caller is supposed to not manipulate with the data after a successful call (including calling free() on the provided data).
[in]	value_type	Type of the provided data `value`.

Returns: New node, NULL on error.

struct lyd_node* lyd_new_yangdata	(	const struct lys_module *	module,
		const char *	name_template,
		const char *	name
	)

Create a new yang-data template in a data tree. It creates container, which name is in third parameter.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

Parameters

[in]	module	Module with the node being created.
[in]	name_template	Yang-data template name. This name is used for searching of yang-data instance.
[in]	name	Schema node name of the new data node. This node is container.

Returns: New node, NULL on error.

struct lyd_node* lyd_new_path	(	struct lyd_node *	data_tree,
		const struct ly_ctx *	ctx,
		const char *	path,
		void *	value,
		LYD_ANYDATA_VALUETYPE	value_type,
		int	options
	)

Create a new data node based on a simple XPath.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

The new node is normally inserted at the end, either as the last child of a parent or as the last sibling if working with top-level elements. However, when manipulating RPC input or output, schema ordering is required and always guaranteed.

If path points to a list key and the list does not exist, the key value from the predicate is used and value is ignored.

Parameters

[in]	data_tree	Existing data tree to add to/modify (including siblings). If creating RPCs/actions, there should only be one RPC/action and either input or output, not both. Can be NULL.
[in]	ctx	Context to use. Mandatory if `data_tree` is NULL.
[in]	path	Simple data path (see howtoxpath). List nodes can have predicates, one for each list key in the correct order and with its value as well or using specific instance position, leaves and leaf-lists can have predicates too that have preference over `value`. When specifying an identityref value in a predicate, you MUST use the module name as the value prefix!
[in]	value	Value of the new leaf/lealf-list (const char*). If creating anydata or anyxml, the following `value_type` parameter is required to be specified correctly. If creating nodes of other types, the parameter is ignored.
[in]	value_type	Type of the provided `value` parameter in case of creating anydata or anyxml node.
[in]	options	Bitmask of options flags, see Data path creation options.

Returns: First created (or updated with LYD_PATH_OPT_UPDATE) node, NULL if LYD_PATH_OPT_UPDATE was used and the full path exists or the leaf original value matches value, NULL and ly_errno is set on error.

unsigned int lyd_list_pos ( const struct lyd_node * node )

Learn the relative instance position of a list or leaf-list within other instances of the same schema node.

Parameters

[in] node List or leaf-list to get the position of.

Returns: 0 on error or positive integer of the instance position.

struct lyd_node* lyd_dup	(	const struct lyd_node *	node,
		int	options
	)

Create a copy of the specified data tree node. Schema references are kept the same. Use carefully, since libyang silently creates default nodes, it is always better to use lyd_dup_withsiblings() to duplicate the complete data tree.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

Parameters

[in]	node	Data tree node to be duplicated.
[in]	options	Bitmask of options flags, see Data duplication options.

Returns: Created copy of the provided data node.

struct lyd_node* lyd_dup_withsiblings	(	const struct lyd_node *	node,
		int	options
	)

Create a copy of the specified data tree and all its siblings (preceding as well as following). Schema references are kept the same.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

Parameters

[in]	node	Data tree sibling node to be duplicated.
[in]	options	Bitmask of options flags, see Data duplication options.

Returns: Created copy of the provided data node and all of its siblings.

struct lyd_node* lyd_dup_to_ctx	(	const struct lyd_node *	node,
		int	options,
		struct ly_ctx *	ctx
	)

Create a copy of the specified data tree node in the different context. All the schema references and strings are re-mapped into the specified context.

If the target context does not contain the schemas used in the source data tree, error is raised and the new data tree is not created.

Parameters

[in]	node	Data tree node to be duplicated.
[in]	options	Bitmask of options flags, see Data duplication options.
[in]	ctx	Target context for the duplicated data.

Returns: Created copy of the provided data node.

int lyd_merge	(	struct lyd_node *	target,
		const struct lyd_node *	source,
		int	options
	)

Merge a (sub)tree into a data tree.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

Missing nodes are merged, leaf values updated. Any attributes on the data nodes are strictly tied to the nodes - if the node is merged, its attributes are merged with it, if the node is not merged, its attributes are not merged either.

If target and source do not share the top-level schema node, even if they are from different modules, source parents up to top-level node will be created and linked to the target (but only containers can be created this way, lists need keys, so if lists are missing, an error will be returned).

If the source data tree is in a different context, the resulting data are placed into the context of the target tree.

Parameters

[in]	target	Top-level (or an RPC output child) data tree to merge to. Must be valid.
[in]	source	Data tree to merge `target` with. Must be valid (at least as a subtree).
[in]	options	Bitmask of the following option flags: LYD_OPT_DESTRUCT - spend `source` in the function, otherwise `source` is left untouched, LYD_OPT_NOSIBLINGS - merge only the `source` subtree (ignore siblings), otherwise merge `source` and all its succeeding siblings (preceding ones are still ignored!), LYD_OPT_EXPLICIT - when merging an explicitly set node and a default node, always put the explicit node into `target`, otherwise the node which is in `source` is used.

Returns: 0 on success, nonzero in case of an error.

int lyd_merge_to_ctx	(	struct lyd_node **	trg,
		const struct lyd_node *	src,
		int	options,
		struct ly_ctx *	ctx
	)

Same as lyd_merge(), but moves the resulting data into the specified context.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

Parameters

[in]	trg	Top-level (or an RPC output child) data tree to merge to. Must be valid. If its context differs from the specified `ctx` of the result, the provided data tree is freed and the new tree in the required context is returned on success. To keep the `trg` tree, convert it to the target context using lyd_dup_to_ctx() and then call lyd_merge() instead of lyd_merge_to_ctx().
[in]	src	Data tree to merge `target` with. Must be valid (at least as a subtree).
[in]	options	Bitmask of the following option flags: LYD_OPT_DESTRUCT - spend `source` in the function, otherwise `source` is left untouched, LYD_OPT_NOSIBLINGS - merge only the `source` subtree (ignore siblings), otherwise merge `source` and all its succeeding siblings (preceding ones are still ignored!), LYD_OPT_EXPLICIT - when merging an explicitly set node and a default node, always put the explicit node into `target`, otherwise the node which is in `source` is used.
[in]	ctx	Target context in which the result will be created. Note that the successful merge requires to have all the used modules in the source and target data trees loaded in the target context.

Returns: 0 on success, nonzero in case of an error.

int lyd_insert	(	struct lyd_node *	parent,
		struct lyd_node *	node
	)

Insert the node element as child to the parent element. The node is inserted as a last child of the parent.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

if the node is part of some other tree, it is automatically unlinked.
if the node is the first node of a node list (with no parent), all the subsequent nodes are also inserted.
if the key of a list is being inserted, it is placed into a correct position instead of being placed as the last element.
if the target tree includes the default instance of the node being inserted, the default node is silently replaced by the new node.
if a default node is being inserted and the target tree already contains non-default instance, the existing instance is silently replaced. If it contains the exact same default node, it is replaced as well.
if a non-default node is being inserted and there is already its non-default instance in the target tree, the new node is inserted and it is up to the caller to solve the presence of multiple instances afterwards.

Note that this function differs from lyd_insert_before() and lyd_insert_after() because the position of the node being inserted is determined automatically according to the rules described above. In contrast to lyd_insert_parent(), lyd_insert() can not be used for top-level elements since the parent parameter must not be NULL. If inserting something larger and not fitting the mentioned use-cases (or simply if unsure), you can always use lyd_merge(), it should be able to handle any situation.

Parameters

[in]	parent	Parent node for the `node` being inserted.
[in]	node	The node being inserted.

Returns: 0 on success, nonzero in case of error, e.g. when the node is being inserted to an inappropriate place in the data tree.

int lyd_insert_sibling	(	struct lyd_node **	sibling,
		struct lyd_node *	node
	)

Insert the node element as a last sibling of the specified sibling element.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

if the node is part of some other tree, it is automatically unlinked.
if the node is the first node of a node list (with no parent), all the subsequent nodes are also inserted.
if the key of a list is being inserted, it is placed into a correct position instead of being placed as the last element.
if the target tree includes the default instance of the node being inserted, the default node is silently replaced by the new node.
if a default node is being inserted and the target tree already contains non-default instance, the existing instance is silently replaced. If it contains the exact same default node, it is replaced as well.
if a non-default node is being inserted and there is already its non-default instance in the target tree, the new node is inserted and it is up to the caller to solve the presence of multiple instances afterwards.

Note that this function differs from lyd_insert_before() and lyd_insert_after() because the position of the node being inserted is determined automatically as in the case of lyd_insert(). In contrast to lyd_insert(), lyd_insert_sibling() can be used to insert top-level elements. If inserting something larger and not fitting the mentioned use-cases (or simply if unsure), you can always use lyd_merge(), it should be able to handle any situation.

Parameters

[in,out]	sibling	Sibling node as a reference where to insert the `node`. When function succeeds, the sibling is always set to point to the first sibling node. Note that in some cases described above, the provided sibling node could be removed from the tree.
[in]	node	The node being inserted.

Returns: 0 on success, nonzero in case of error, e.g. when the node is being inserted to an inappropriate place in the data tree.

int lyd_insert_before	(	struct lyd_node *	sibling,
		struct lyd_node *	node
	)

Insert the node element after the sibling element. If node and siblings are already siblings (just moving node position).

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

if the target tree includes the default instance of the node being inserted, the default node is silently removed.
if a default node is being inserted and the target tree already contains non-default instance, the existing instance is removed. If it contains the exact same default node, it is removed as well.
if a non-default node is being inserted and there is already its non-default instance in the target tree, the new node is inserted and it is up to the caller to solve the presence of multiple instances afterwards.

Parameters

[in]	sibling	The data tree node before which the `node` will be inserted.
[in]	node	The data tree node to be inserted. If the node is connected somewhere, it is unlinked first.

Returns: 0 on success, nonzero in case of error, e.g. when the node is being inserted to an inappropriate place in the data tree.

int lyd_insert_after	(	struct lyd_node *	sibling,
		struct lyd_node *	node
	)

Insert the node element after the sibling element. If node and siblings are already siblings (just moving node position).

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

if the target tree includes the default instance of the node being inserted, the default node is silently removed.
if a default node is being inserted and the target tree already contains non-default instance, the existing instance is removed. If it contains the exact same default node, it is removed as well.
if a non-default node is being inserted and there is already its non-default instance in the target tree, the new node is inserted and it is up to the caller to solve the presence of multiple instances afterwards.

Parameters

[in]	sibling	The data tree node before which the `node` will be inserted. If `node` and `siblings` are already siblings (just moving `node` position), skip validation.
[in]	node	The data tree node to be inserted. If the node is connected somewhere, it is unlinked first.

Returns: 0 on success, nonzero in case of error, e.g. when the node is being inserted to an inappropriate place in the data tree.

int lyd_schema_sort	(	struct lyd_node *	sibling,
		int	recursive
	)

Order siblings according to the schema node ordering.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

If the siblings include data nodes from other modules, they are sorted based on the module order in the context.

Parameters

[in]	sibling	Node, whose siblings will be sorted.
[in]	recursive	Whether sort all siblings of siblings, recursively.

Returns: 0 on success, nonzero in case of an error.

struct ly_set* lyd_find_path	(	const struct lyd_node *	ctx_node,
		const char *	path
	)

Search in the given data for instances of nodes matching the provided path.

Learn more about the path format on page howtoxpath.

Parameters

[in]	ctx_node	Path context node.
[in]	path	Data path expression filtering the matching nodes.

Returns: Set of found data nodes. If no nodes are matching path or the result would be a number, a string, or a boolean, the returned set is empty. In case of an error, NULL is returned.

struct ly_set* lyd_find_instance	(	const struct lyd_node *	data,
		const struct lys_node *	schema
	)

Search in the given data for instances of the provided schema node.

The data is used to find the data root and function then searches in the whole tree and all sibling trees.

Parameters

[in]	data	A node in the data tree to search.
[in]	schema	Schema node of the data nodes caller want to find.

Returns: Set of found data nodes. If no data node is found, the returned set is empty. In case of error, NULL is returned.

int lyd_find_sibling	(	const struct lyd_node *	siblings,
		const struct lyd_node *	target,
		struct lyd_node **	match
	)

Search in the given siblings for the target instance. If cache is enabled and the siblings are NOT top-level nodes, this function finds the node in a constant time!

Parameters

[in]	siblings	Siblings to search in including preceding and succeeding nodes.
[in]	target	Target node to find. Lists must have all the keys. Invalid argument - key-less list or state (config false) leaf-list, use lyd_find_sibling_set instead.
[out]	match	Found data node, NULL if not found.

Returns: 0 on success (even on not found), -1 on error.

int lyd_find_sibling_set	(	const struct lyd_node *	siblings,
		const struct lyd_node *	target,
		struct ly_set **	set
	)

Search in the given siblings for all target instances. If cache is enabled and the siblings are NOT top-level nodes, this function finds the node(s) in a constant time!

Parameters

[in]	siblings	Siblings to search in including preceding and succeeding nodes.
[in]	target	Target node to find. Lists must have all the keys. Key-less lists are compared based on all its descendants (both direct and indirect).
[out]	set	Found nodes in a set, can be empty.

Returns: 0 on success (even on no nodes found), -1 on error. If an error occurs, NULL is returned.

int lyd_find_sibling_val	(	const struct lyd_node *	siblings,
		const struct lys_node *	schema,
		const char *	key_or_value,
		struct lyd_node **	match
	)

Search in the given siblings for the schema instance. If cache is enabled and the siblings are NOT top-level nodes, this function finds the node in a constant time!

Parameters

[in]	siblings	Siblings to search in including preceding and succeeding nodes.
[in]	schema	Schema node of the data node to find. Invalid argument - key-less list or state (config false) leaf-list, use lyd_find_sibling_set instead.
[in]	key_or_value	Expected value depends on the type of `schema:` LYS_CONTAINER: LYS_LEAF: LYS_ANYXML: LYS_ANYDATA: LYS_NOTIF: LYS_RPC: LYS_ACTION: NULL should be always set, will be ignored. LYS_LEAFLIST: Searched instance value. LYS_LIST: Searched instance all ordered key values in the form of "[key1='val1'][key2='val2']...", while the key name may have optional prefixes their module names.
[out]	match	Found data node, NULL if not found.

Returns: 0 on success (even on not found), -1 on error.

struct lyd_node* lyd_first_sibling ( struct lyd_node * node )

Get the first sibling of the given node.

Parameters

[in] node Node which first sibling is going to be the result.

Returns: The first sibling of the given node or the node itself if it is the first child of the parent.

int lyd_validate	(	struct lyd_node **	node,
		int	options,
		void *	var_arg,
			...
	)

Validate node data subtree.

Parameters

[in,out]	node	Data tree to be validated. In case the `options` includes LYD_OPT_WHENAUTODEL, libyang can modify the provided tree including the root `node`.
[in]	options	Options for the inserting data to the target data tree options, see Data parser options.
[in]	var_arg	Variable argument depends on `options`. If they include: LYD_OPT_DATA: LYD_OPT_CONFIG: LYD_OPT_GET: LYD_OPT_GETCONFIG: LYD_OPT_EDIT: struct ly_ctx ctx - context to use when `node` is NULL (for checking an empty tree), otherwise can be NULL. LYD_OPT_RPC: LYD_OPT_RPCREPLY: LYD_OPT_NOTIF: struct lyd_node data_tree - additional validated top-level siblings of a data tree that will be used when checking any references ("when", "must" conditions, leafrefs, ...) in the operation subtree that require some nodes outside their subtree. It is assumed that all parents of the action/nested notification exist as required (RFC ref).
[in]	...	Used only if options include LYD_OPT_VAL_DIFF. In that case a (struct lyd_difflist **) is expected into which all data node changes performed by the validation will be stored. Needs to be properly freed. Meaning of diff type is following: LYD_DIFF_CREATED: first - Path identifying the parent node (format of lyd_path()). second - Duplicated subtree of the created nodes. LYD_DIFF_DELETED: first - Unlinked subtree of the deleted nodes. second - Path identifying the original parent (format of lyd_path()).

Returns: 0 on success, nonzero in case of an error.

int lyd_validate_modules	(	struct lyd_node **	node,
		const struct lys_module **	modules,
		int	mod_count,
		int	options,
			...
	)

Validate node data tree but only subtrees that belong to the schema found in modules. All other schemas are effectively disabled for the validation.

Parameters

[in,out]	node	Data tree to be validated. In case the `options` includes LYD_OPT_WHENAUTODEL, libyang can modify the provided tree including the root `node`.
[in]	modules	List of module names to validate.
[in]	mod_count	Number of modules in `modules`.
[in]	options	Options for the inserting data to the target data tree options, see Data parser options. Accepted data type values include LYD_OPT_DATA, LYD_OPT_CONFIG, LYD_OPT_GET, LYD_OPT_GETCONFIG, and LYD_OPT_EDIT.
[in]	...	Used only if options include LYD_OPT_VAL_DIFF. In that case a (struct lyd_difflist **) is expected into which all data node changes performed by the validation will be stored. Needs to be properly freed. Meaning of diff type is following: LYD_DIFF_CREATED: first - Path identifying the parent node (format of lyd_path()). second - Duplicated subtree of the created nodes. LYD_DIFF_DELETED: first - Unlinked subtree of the deleted nodes. second - Path identifying the original parent (format of lyd_path()).

Returns: 0 on success, nonzero in case of an error.

void lyd_free_val_diff ( struct lyd_difflist * diff )

Free special diff that was returned by lyd_validate() or lyd_validate_modules().

Parameters

[in] diff Diff to free.

int lyd_validate_value	(	struct lys_node *	node,
		const char *	value
	)

Check restrictions applicable to the particular leaf/leaf-list on the given string value.

Validates the value only using the types' restrictions. Do not check the rest of restrictions dependent on the data tree (must, when statements or uniqueness of the leaf-list item).

The format of the data must follow rules for the lexical representation of the specific YANG type. Note that if there are some extensions of the lexical representation for the YANG module (default value), they are not supported by this function - it strictly follows rules for the lexical representations in data trees.

Parameters

[in]	node	Schema node of the leaf or leaf-list eventually holding the `value`.
[in]	value	Value to be checked (NULL is checked as empty string).

Returns: EXIT_SUCCESS if the value conforms to the restrictions, EXIT_FAILURE otherwise.

int lyd_value_type	(	struct lys_node *	node,
		const char *	value,
		struct lys_type **	type
	)

Check restrictions applicable to the particular leaf/leaf-list on the given string value and optionally return its final type.

Validates the value only using the types' restrictions. Do not check the rest of restrictions dependent on the data tree (must, when statements or uniqueness of the leaf-list item).

The format of the data must follow rules for the lexical representation of the specific YANG type. Note that if there are some extensions of the lexical representation for the YANG module (default value), they are not supported by this function - it strictly follows rules for the lexical representations in data trees.

Parameters

[in]	node	Schema node of the leaf or leaf-list eventually holding the `value`.
[in]	value	Value to be checked (NULL is checked as empty string).
[out]	type	Optional resolved value type, useful mainly for unions.

Returns: EXIT_SUCCESS if the value conforms to the restrictions, EXIT_FAILURE otherwise.

int lyd_wd_default ( struct lyd_node_leaf_list * node )

Get know if the node contain (despite implicit or explicit) default value.

Parameters

[in] node The leaf or leaf-list to check. Note, that leaf-list is marked as default only when the complete and only the default set is present (node's siblings are also checked).

Returns: 1 if the node contains the default value, 0 otherwise.

int lyd_node_should_print	(	const struct lyd_node *	node,
		int	options
	)

Learn if a node is supposed to be printed based on the options.

Parameters

[in]	node	Data node to examine.
[in]	options	printer flags. With-defaults flags and ::LYP_KEEPEMPTYCONT are relevant.

Returns: non-zero if should be printed, 0 if not.

int lyd_unlink ( struct lyd_node * node )

Unlink the specified data subtree. All referenced namespaces are copied.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

Note, that the node's connection with the schema tree is kept. Therefore, in case of reconnecting the node to a data tree using lyd_paste() it is necessary to paste it to the appropriate place in the data tree following the schema.

Parameters

[in] node Data tree node to be unlinked (together with all children).

Returns: 0 for success, nonzero for error

void lyd_free ( struct lyd_node * node )

Free (and unlink) the specified data subtree. Use carefully, since libyang silently creates default nodes, it is always better to use lyd_free_withsiblings() to free the complete data tree.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

Parameters

[in] node Root of the (sub)tree to be freed.

void lyd_free_withsiblings ( struct lyd_node * node )

Free (and unlink) the specified data tree and all its siblings (preceding as well as following).

If used on a top-level node it means that the whole data tree is being freed and unnecessary operations are skipped. Always use this function for freeing a whole data tree to achieve better performance.

PARTIAL CHANGE - validate after the final change on the data tree (see howtodatamanipulators).

Parameters

[in] node One of the siblings root element of the (sub)trees to be freed.

struct lyd_attr* lyd_insert_attr	(	struct lyd_node *	parent,
		const struct lys_module *	mod,
		const char *	name,
		const char *	value
	)

Insert attribute into the data node.

Parameters

[in]	parent	Data node where to place the attribute
[in]	mod	An alternative way to specify attribute's module (namespace) used in case the `name` does not include prefix. If neither prefix in the `name` nor mod is specified, the attribute's module is inherited from the `parent` node. It is not allowed to have attributes with no module (namespace).
[in]	name	Attribute name. The string can include the attribute's module (namespace) as the name's prefix (prefix:name). Prefix must be the name of one of the schema in the `parent's` context. If the prefix is not specified, the `mod` parameter is used. If neither of these parameters is usable, attribute inherits module (namespace) from the `parent` node. It is not allowed to have attributes with no module (namespace).
[in]	value	Attribute value

Returns: pointer to the created attribute (which is already connected in parent) or NULL on error.

void lyd_free_attr	(	struct ly_ctx *	ctx,
		struct lyd_node *	parent,
		struct lyd_attr *	attr,
		int	recursive
	)

Destroy data attribute.

If the attribute to destroy is a member of a node attribute list, it is necessary to provide the node itself as parent to keep the list consistent.

Parameters

[in]	ctx	Context where the attribute was created (usually it is the context of the `parent`)
[in]	parent	Parent node where the attribute is placed
[in]	attr	Attribute to destroy
[in]	recursive	Zero to destroy only the attribute, non-zero to destroy also all the subsequent attributes in the list.

struct lys_module* lyd_node_module ( const struct lyd_node * node )

Return main module of the data tree node.

In case of regular YANG module, it returns lys_node::module pointer, but in case of submodule, it returns pointer to the main module.

Parameters

[in] node Data tree node to be examined

Returns: pointer to the main module (schema structure), NULL in case of error.

struct lys_type* lyd_leaf_type ( const struct lyd_node_leaf_list * leaf )

Get the type structure of a leaf.

In case of a union, the correct specific type is found. In case of a leafref, the final (if there is a chain of leafrefs) target's type is found.

Parameters

[in] leaf Leaf to examine.

Returns: Found type, NULL on error.

int lyd_print_mem	(	char **	strp,
		const struct lyd_node *	root,
		LYD_FORMAT	format,
		int	options
	)

Print data tree in the specified format.

Parameters

[out]	strp	Pointer to store the resulting dump.
[in]	root	Root node of the data tree to print. It can be actually any (not only real root) node of the data tree to print the specific subtree.
[in]	format	Data output format.
[in]	options	printer flags. `format` LYD_LYB accepts only #LYP_WITHSIBLINGS option.

Returns: 0 on success, 1 on failure (#ly_errno is set).

int lyd_print_fd	(	int	fd,
		const struct lyd_node *	root,
		LYD_FORMAT	format,
		int	options
	)

Print data tree in the specified format.

Parameters

[in]	fd	File descriptor where to print the data.
[in]	root	Root node of the data tree to print. It can be actually any (not only real root) node of the data tree to print the specific subtree.
[in]	format	Data output format.
[in]	options	printer flags. `format` LYD_LYB accepts only #LYP_WITHSIBLINGS option.

Returns: 0 on success, 1 on failure (#ly_errno is set).

int lyd_print_file	(	FILE *	f,
		const struct lyd_node *	root,
		LYD_FORMAT	format,
		int	options
	)

Print data tree in the specified format.

Parameters

[in]	f	File stream where to print the data.
[in]	root	Root node of the data tree to print. It can be actually any (not only real root) node of the data tree to print the specific subtree.
[in]	format	Data output format.
[in]	options	printer flags. `format` LYD_LYB accepts only #LYP_WITHSIBLINGS option.

Returns: 0 on success, 1 on failure (#ly_errno is set).

int lyd_print_path	(	const char *	path,
		const struct lyd_node *	root,
		LYD_FORMAT	format,
		int	options
	)

Print data tree in the specified format.

Parameters

[in]	path	File path where to print the data.
[in]	root	Root node of the data tree to print. It can be actually any (not only real root) node of the data tree to print the specific subtree.
[in]	format	Data output format.
[in]	options	printer flags. `format` LYD_LYB accepts only #LYP_WITHSIBLINGS option.

Returns: 0 on success, 1 on failure (#ly_errno is set).

int lyd_print_clb	(	ssize_t()(void arg, const void *buf, size_t count)	writeclb,
		void *	arg,
		const struct lyd_node *	root,
		LYD_FORMAT	format,
		int	options
	)

Print data tree in the specified format.

Parameters

[in]	writeclb	Callback function to write the data (see write(1)).
[in]	root	Root node of the data tree to print. It can be actually any (not only real root) node of the data tree to print the specific subtree.
[in]	arg	Optional caller-specific argument to be passed to the `writeclb` callback.
[in]	format	Data output format.
[in]	options	printer flags. `format` LYD_LYB accepts only #LYP_WITHSIBLINGS option.

Returns: 0 on success, 1 on failure (#ly_errno is set).

double lyd_dec64_to_double ( const struct lyd_node * node )

Get the double value of a decimal64 leaf/leaf-list.

YANG decimal64 type enables higher precision numbers than IEEE 754 double-precision format, so this conversion does not have to be lossless.

Parameters

[in] node Leaf/leaf-list of type decimal64.

Returns: Closest double equivalent to the decimal64 value.

int lyd_lyb_data_length ( const char * data )

Get the length of a printed LYB data tree.

Parameters

[in] data LYB data.

Returns: data length or -1 on error.

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation