libplist 2.6.0
Macros | Typedefs | Enumerations | Functions
plist.h File Reference

Main include of libplist. More...

#include <stdint.h>
#include <sys/types.h>
#include <stdarg.h>
#include <stdio.h>

Macros

#define PLIST_OPT_INDENT_BY(x)   ((x & 0xFF) << 24)
 To be used with PLIST_OPT_INDENT - encodes the level of indentation for OR'ing it into the plist_write_options_t bitfield.
 
#define _PLIST_IS_TYPE(__plist, __plist_type)   (__plist && (plist_get_node_type(__plist) == PLIST_##__plist_type))
 Helper macro used by PLIST_IS_* macros that will evaluate the type of a plist node.
 
#define PLIST_IS_BOOLEAN(__plist)   _PLIST_IS_TYPE(__plist, BOOLEAN)
 Evaluates to true if the given plist node is of type PLIST_BOOLEAN.
 
#define PLIST_IS_INT(__plist)   _PLIST_IS_TYPE(__plist, INT)
 Evaluates to true if the given plist node is of type PLIST_INT.
 
#define PLIST_IS_REAL(__plist)   _PLIST_IS_TYPE(__plist, REAL)
 Evaluates to true if the given plist node is of type PLIST_REAL.
 
#define PLIST_IS_STRING(__plist)   _PLIST_IS_TYPE(__plist, STRING)
 Evaluates to true if the given plist node is of type PLIST_STRING.
 
#define PLIST_IS_ARRAY(__plist)   _PLIST_IS_TYPE(__plist, ARRAY)
 Evaluates to true if the given plist node is of type PLIST_ARRAY.
 
#define PLIST_IS_DICT(__plist)   _PLIST_IS_TYPE(__plist, DICT)
 Evaluates to true if the given plist node is of type PLIST_DICT.
 
#define PLIST_IS_DATE(__plist)   _PLIST_IS_TYPE(__plist, DATE)
 Evaluates to true if the given plist node is of type PLIST_DATE.
 
#define PLIST_IS_DATA(__plist)   _PLIST_IS_TYPE(__plist, DATA)
 Evaluates to true if the given plist node is of type PLIST_DATA.
 
#define PLIST_IS_KEY(__plist)   _PLIST_IS_TYPE(__plist, KEY)
 Evaluates to true if the given plist node is of type PLIST_KEY.
 
#define PLIST_IS_UID(__plist)   _PLIST_IS_TYPE(__plist, UID)
 Evaluates to true if the given plist node is of type PLIST_UID.
 

Typedefs

typedef void * plist_t
 The basic plist abstract data type.
 
typedef void * plist_dict_iter
 The plist dictionary iterator.
 
typedef void * plist_array_iter
 The plist array iterator.
 

Enumerations

enum  plist_type {
  PLIST_NONE =-1 ,
  PLIST_BOOLEAN ,
  PLIST_INT ,
  PLIST_REAL ,
  PLIST_STRING ,
  PLIST_ARRAY ,
  PLIST_DICT ,
  PLIST_DATE ,
  PLIST_DATA ,
  PLIST_KEY ,
  PLIST_UID ,
  PLIST_NULL
}
 The enumeration of plist node types. More...
 
enum  plist_err_t {
  PLIST_ERR_SUCCESS = 0 ,
  PLIST_ERR_INVALID_ARG = -1 ,
  PLIST_ERR_FORMAT = -2 ,
  PLIST_ERR_PARSE = -3 ,
  PLIST_ERR_NO_MEM = -4 ,
  PLIST_ERR_IO = -5 ,
  PLIST_ERR_UNKNOWN = -255
}
 libplist error values More...
 
enum  plist_format_t {
  PLIST_FORMAT_NONE = 0 ,
  PLIST_FORMAT_XML = 1 ,
  PLIST_FORMAT_BINARY = 2 ,
  PLIST_FORMAT_JSON = 3 ,
  PLIST_FORMAT_OSTEP = 4 ,
  PLIST_FORMAT_PRINT = 10 ,
  PLIST_FORMAT_LIMD = 11 ,
  PLIST_FORMAT_PLUTIL = 12
}
 libplist format types More...
 
enum  plist_write_options_t {
  PLIST_OPT_NONE = 0 ,
  PLIST_OPT_COMPACT = 1 << 0 ,
  PLIST_OPT_PARTIAL_DATA = 1 << 1 ,
  PLIST_OPT_NO_NEWLINE = 1 << 2 ,
  PLIST_OPT_INDENT = 1 << 3
}
 libplist write options More...
 

Functions

plist_t plist_new_dict (void)
 Create a new root plist_t type PLIST_DICT.
 
plist_t plist_new_array (void)
 Create a new root plist_t type PLIST_ARRAY.
 
plist_t plist_new_string (const char *val)
 Create a new plist_t type PLIST_STRING.
 
plist_t plist_new_bool (uint8_t val)
 Create a new plist_t type PLIST_BOOLEAN.
 
plist_t plist_new_uint (uint64_t val)
 Create a new plist_t type PLIST_INT with an unsigned integer value.
 
plist_t plist_new_int (int64_t val)
 Create a new plist_t type PLIST_INT with a signed integer value.
 
plist_t plist_new_real (double val)
 Create a new plist_t type PLIST_REAL.
 
plist_t plist_new_data (const char *val, uint64_t length)
 Create a new plist_t type PLIST_DATA.
 
plist_t plist_new_date (int32_t sec, int32_t usec)
 Create a new plist_t type PLIST_DATE.
 
plist_t plist_new_uid (uint64_t val)
 Create a new plist_t type PLIST_UID.
 
plist_t plist_new_null (void)
 Create a new plist_t type PLIST_NULL.
 
void plist_free (plist_t plist)
 Destruct a plist_t node and all its children recursively.
 
plist_t plist_copy (plist_t node)
 Return a copy of passed node and it's children.
 
uint32_t plist_array_get_size (plist_t node)
 Get size of a PLIST_ARRAY node.
 
plist_t plist_array_get_item (plist_t node, uint32_t n)
 Get the nth item in a PLIST_ARRAY node.
 
uint32_t plist_array_get_item_index (plist_t node)
 Get the index of an item.
 
void plist_array_set_item (plist_t node, plist_t item, uint32_t n)
 Set the nth item in a PLIST_ARRAY node.
 
void plist_array_append_item (plist_t node, plist_t item)
 Append a new item at the end of a PLIST_ARRAY node.
 
void plist_array_insert_item (plist_t node, plist_t item, uint32_t n)
 Insert a new item at position n in a PLIST_ARRAY node.
 
void plist_array_remove_item (plist_t node, uint32_t n)
 Remove an existing position in a PLIST_ARRAY node.
 
void plist_array_item_remove (plist_t node)
 Remove a node that is a child node of a PLIST_ARRAY node.
 
void plist_array_new_iter (plist_t node, plist_array_iter *iter)
 Create an iterator of a PLIST_ARRAY node.
 
void plist_array_next_item (plist_t node, plist_array_iter iter, plist_t *item)
 Increment iterator of a PLIST_ARRAY node.
 
uint32_t plist_dict_get_size (plist_t node)
 Get size of a PLIST_DICT node.
 
void plist_dict_new_iter (plist_t node, plist_dict_iter *iter)
 Create an iterator of a PLIST_DICT node.
 
void plist_dict_next_item (plist_t node, plist_dict_iter iter, char **key, plist_t *val)
 Increment iterator of a PLIST_DICT node.
 
void plist_dict_get_item_key (plist_t node, char **key)
 Get key associated key to an item.
 
plist_t plist_dict_get_item (plist_t node, const char *key)
 Get the nth item in a PLIST_DICT node.
 
plist_t plist_dict_item_get_key (plist_t node)
 Get key node associated to an item.
 
void plist_dict_set_item (plist_t node, const char *key, plist_t item)
 Set item identified by key in a PLIST_DICT node.
 
void plist_dict_remove_item (plist_t node, const char *key)
 Remove an existing position in a PLIST_DICT node.
 
void plist_dict_merge (plist_t *target, plist_t source)
 Merge a dictionary into another.
 
uint8_t plist_dict_get_bool (plist_t dict, const char *key)
 Get a boolean value from a given PLIST_DICT entry.
 
int64_t plist_dict_get_int (plist_t dict, const char *key)
 Get a signed integer value from a given PLIST_DICT entry.
 
uint64_t plist_dict_get_uint (plist_t dict, const char *key)
 Get an unsigned integer value from a given PLIST_DICT entry.
 
plist_err_t plist_dict_copy_item (plist_t target_dict, plist_t source_dict, const char *key, const char *alt_source_key)
 Copy a node from source_dict to target_dict.
 
plist_err_t plist_dict_copy_bool (plist_t target_dict, plist_t source_dict, const char *key, const char *alt_source_key)
 Copy a boolean value from source_dict to target_dict.
 
plist_err_t plist_dict_copy_int (plist_t target_dict, plist_t source_dict, const char *key, const char *alt_source_key)
 Copy a signed integer value from source_dict to target_dict.
 
plist_err_t plist_dict_copy_uint (plist_t target_dict, plist_t source_dict, const char *key, const char *alt_source_key)
 Copy an unsigned integer value from source_dict to target_dict.
 
plist_err_t plist_dict_copy_data (plist_t target_dict, plist_t source_dict, const char *key, const char *alt_source_key)
 Copy a PLIST_DATA node from source_dict to target_dict.
 
plist_err_t plist_dict_copy_string (plist_t target_dict, plist_t source_dict, const char *key, const char *alt_source_key)
 Copy a PLIST_STRING node from source_dict to target_dict.
 
plist_t plist_get_parent (plist_t node)
 Get the parent of a node.
 
plist_type plist_get_node_type (plist_t node)
 Get the plist_type of a node.
 
void plist_get_key_val (plist_t node, char **val)
 Get the value of a PLIST_KEY node.
 
void plist_get_string_val (plist_t node, char **val)
 Get the value of a PLIST_STRING node.
 
const char * plist_get_string_ptr (plist_t node, uint64_t *length)
 Get a pointer to the buffer of a PLIST_STRING node.
 
void plist_get_bool_val (plist_t node, uint8_t *val)
 Get the value of a PLIST_BOOLEAN node.
 
void plist_get_uint_val (plist_t node, uint64_t *val)
 Get the unsigned integer value of a PLIST_INT node.
 
void plist_get_int_val (plist_t node, int64_t *val)
 Get the signed integer value of a PLIST_INT node.
 
void plist_get_real_val (plist_t node, double *val)
 Get the value of a PLIST_REAL node.
 
void plist_get_data_val (plist_t node, char **val, uint64_t *length)
 Get the value of a PLIST_DATA node.
 
const char * plist_get_data_ptr (plist_t node, uint64_t *length)
 Get a pointer to the data buffer of a PLIST_DATA node.
 
void plist_get_date_val (plist_t node, int32_t *sec, int32_t *usec)
 Get the value of a PLIST_DATE node.
 
void plist_get_uid_val (plist_t node, uint64_t *val)
 Get the value of a PLIST_UID node.
 
void plist_set_key_val (plist_t node, const char *val)
 Set the value of a node.
 
void plist_set_string_val (plist_t node, const char *val)
 Set the value of a node.
 
void plist_set_bool_val (plist_t node, uint8_t val)
 Set the value of a node.
 
void plist_set_uint_val (plist_t node, uint64_t val)
 Set the value of a node.
 
void plist_set_int_val (plist_t node, int64_t val)
 Set the value of a node.
 
void plist_set_real_val (plist_t node, double val)
 Set the value of a node.
 
void plist_set_data_val (plist_t node, const char *val, uint64_t length)
 Set the value of a node.
 
void plist_set_date_val (plist_t node, int32_t sec, int32_t usec)
 Set the value of a node.
 
void plist_set_uid_val (plist_t node, uint64_t val)
 Set the value of a node.
 
plist_err_t plist_to_xml (plist_t plist, char **plist_xml, uint32_t *length)
 Export the plist_t structure to XML format.
 
plist_err_t plist_to_bin (plist_t plist, char **plist_bin, uint32_t *length)
 Export the plist_t structure to binary format.
 
plist_err_t plist_to_json (plist_t plist, char **plist_json, uint32_t *length, int prettify)
 Export the plist_t structure to JSON format.
 
plist_err_t plist_to_openstep (plist_t plist, char **plist_openstep, uint32_t *length, int prettify)
 Export the plist_t structure to OpenStep format.
 
plist_err_t plist_from_xml (const char *plist_xml, uint32_t length, plist_t *plist)
 Import the plist_t structure from XML format.
 
plist_err_t plist_from_bin (const char *plist_bin, uint32_t length, plist_t *plist)
 Import the plist_t structure from binary format.
 
plist_err_t plist_from_json (const char *json, uint32_t length, plist_t *plist)
 Import the plist_t structure from JSON format.
 
plist_err_t plist_from_openstep (const char *openstep, uint32_t length, plist_t *plist)
 Import the plist_t structure from OpenStep plist format.
 
plist_err_t plist_from_memory (const char *plist_data, uint32_t length, plist_t *plist, plist_format_t *format)
 Import the plist_t structure from memory data.
 
plist_err_t plist_read_from_file (const char *filename, plist_t *plist, plist_format_t *format)
 Import the plist_t structure directly from file.
 
plist_err_t plist_write_to_string (plist_t plist, char **output, uint32_t *length, plist_format_t format, plist_write_options_t options)
 Write the plist_t structure to a NULL-terminated string using the given format and options.
 
plist_err_t plist_write_to_stream (plist_t plist, FILE *stream, plist_format_t format, plist_write_options_t options)
 Write the plist_t structure to a FILE* stream using the given format and options.
 
plist_err_t plist_write_to_file (plist_t plist, const char *filename, plist_format_t format, plist_write_options_t options)
 Write the plist_t structure to a file at given path using the given format and options.
 
void plist_print (plist_t plist)
 Print the given plist in human-readable format to standard output.
 
int plist_is_binary (const char *plist_data, uint32_t length)
 Test if in-memory plist data is in binary format.
 
plist_t plist_access_path (plist_t plist, uint32_t length,...)
 Get a node from its path.
 
plist_t plist_access_pathv (plist_t plist, uint32_t length, va_list v)
 Variadic version of plist_access_path.
 
char plist_compare_node_value (plist_t node_l, plist_t node_r)
 Compare two node values.
 
int plist_bool_val_is_true (plist_t boolnode)
 Helper function to check the value of a PLIST_BOOL node.
 
int plist_int_val_is_negative (plist_t intnode)
 Helper function to test if a given PLIST_INT node's value is negative.
 
int plist_int_val_compare (plist_t uintnode, int64_t cmpval)
 Helper function to compare the value of a PLIST_INT node against a given signed integer value.
 
int plist_uint_val_compare (plist_t uintnode, uint64_t cmpval)
 Helper function to compare the value of a PLIST_INT node against a given unsigned integer value.
 
int plist_uid_val_compare (plist_t uidnode, uint64_t cmpval)
 Helper function to compare the value of a PLIST_UID node against a given value.
 
int plist_real_val_compare (plist_t realnode, double cmpval)
 Helper function to compare the value of a PLIST_REAL node against a given value.
 
int plist_date_val_compare (plist_t datenode, int32_t cmpsec, int32_t cmpusec)
 Helper function to compare the value of a PLIST_DATE node against a given set of seconds and fraction of a second since epoch.
 
int plist_string_val_compare (plist_t strnode, const char *cmpval)
 Helper function to compare the value of a PLIST_STRING node against a given value.
 
int plist_string_val_compare_with_size (plist_t strnode, const char *cmpval, size_t n)
 Helper function to compare the value of a PLIST_STRING node against a given value, while not comparing more than n characters.
 
int plist_string_val_contains (plist_t strnode, const char *substr)
 Helper function to match a given substring in the value of a PLIST_STRING node.
 
int plist_key_val_compare (plist_t keynode, const char *cmpval)
 Helper function to compare the value of a PLIST_KEY node against a given value.
 
int plist_key_val_compare_with_size (plist_t keynode, const char *cmpval, size_t n)
 Helper function to compare the value of a PLIST_KEY node against a given value, while not comparing more than n characters.
 
int plist_key_val_contains (plist_t keynode, const char *substr)
 Helper function to match a given substring in the value of a PLIST_KEY node.
 
int plist_data_val_compare (plist_t datanode, const uint8_t *cmpval, size_t n)
 Helper function to compare the data of a PLIST_DATA node against a given blob and size.
 
int plist_data_val_compare_with_size (plist_t datanode, const uint8_t *cmpval, size_t n)
 Helper function to compare the data of a PLIST_DATA node against a given blob and size, while no more than n bytes are compared.
 
int plist_data_val_contains (plist_t datanode, const uint8_t *cmpval, size_t n)
 Helper function to match a given data blob within the value of a PLIST_DATA node.
 
void plist_sort (plist_t plist)
 Sort all PLIST_DICT key/value pairs in a property list lexicographically by key.
 
void plist_mem_free (void *ptr)
 Free memory allocated by relevant libplist API calls:
 
void plist_set_debug (int debug)
 Set debug level for the format parsers.
 
const char * libplist_version ()
 Returns a static string of the libplist version.
 

Detailed Description

Main include of libplist.

Enumeration Type Documentation

◆ plist_err_t

libplist error values

Enumerator
PLIST_ERR_SUCCESS 

operation successful

PLIST_ERR_INVALID_ARG 

one or more of the parameters are invalid

PLIST_ERR_FORMAT 

the plist contains nodes not compatible with the output format

PLIST_ERR_PARSE 

parsing of the input format failed

PLIST_ERR_NO_MEM 

not enough memory to handle the operation

PLIST_ERR_IO 

I/O error.

PLIST_ERR_UNKNOWN 

an unspecified error occurred

◆ plist_format_t

libplist format types

Enumerator
PLIST_FORMAT_NONE 

No format.

PLIST_FORMAT_XML 

XML format.

PLIST_FORMAT_BINARY 

bplist00 format

PLIST_FORMAT_JSON 

JSON format.

PLIST_FORMAT_OSTEP 

OpenStep "old-style" plist format.

PLIST_FORMAT_PRINT 

human-readable output-only format

PLIST_FORMAT_LIMD 

"libimobiledevice" output-only format (ideviceinfo)

PLIST_FORMAT_PLUTIL 

plutil-style output-only format

◆ plist_type

enum plist_type

The enumeration of plist node types.

Enumerator
PLIST_NONE 

No type.

PLIST_BOOLEAN 

Boolean, scalar type.

PLIST_INT 

Integer, scalar type.

PLIST_REAL 

Real, scalar type.

PLIST_STRING 

ASCII string, scalar type.

PLIST_ARRAY 

Ordered array, structured type.

PLIST_DICT 

Unordered dictionary (key/value pair), structured type.

PLIST_DATE 

Date, scalar type.

PLIST_DATA 

Binary data, scalar type.

PLIST_KEY 

Key in dictionaries (ASCII String), scalar type.

PLIST_UID 

Special type used for 'keyed encoding'.

PLIST_NULL 

NULL type.

◆ plist_write_options_t

libplist write options

Enumerator
PLIST_OPT_NONE 

Default value to use when none of the options is needed.

PLIST_OPT_COMPACT 

Use a compact representation (non-prettified).

Only valid for PLIST_FORMAT_JSON and PLIST_FORMAT_OSTEP.

PLIST_OPT_PARTIAL_DATA 

Print 24 bytes maximum of PLIST_DATA values.

If the data is longer than 24 bytes, the first 16 and last 8 bytes will be written. Only valid for PLIST_FORMAT_PRINT.

PLIST_OPT_NO_NEWLINE 

Do not print a final newline character.

Only valid for PLIST_FORMAT_PRINT, PLIST_FORMAT_LIMD, and PLIST_FORMAT_PLUTIL.

PLIST_OPT_INDENT 

Indent each line of output.

Currently only PLIST_FORMAT_PRINT and PLIST_FORMAT_LIMD are supported. Use PLIST_OPT_INDENT_BY() macro to specify the level of indentation.

Function Documentation

◆ libplist_version()

const char * libplist_version ( )

Returns a static string of the libplist version.

Returns
The libplist version as static ascii string

◆ plist_access_path()

plist_t plist_access_path ( plist_t  plist,
uint32_t  length,
  ... 
)

Get a node from its path.

Each path element depends on the associated father node type. For Dictionaries, var args are casted to const char*, for arrays, var args are caster to uint32_t Search is breath first order.

Parameters
plistthe node to access result from.
lengthlength of the path to access
Returns
the value to access.

◆ plist_access_pathv()

plist_t plist_access_pathv ( plist_t  plist,
uint32_t  length,
va_list  v 
)

Variadic version of plist_access_path.

Parameters
plistthe node to access result from.
lengthlength of the path to access
vlist of array's index and dic'st key
Returns
the value to access.

◆ plist_array_append_item()

void plist_array_append_item ( plist_t  node,
plist_t  item 
)

Append a new item at the end of a PLIST_ARRAY node.

Parameters
nodethe node of type PLIST_ARRAY
itemthe new item. The array is responsible for freeing item when it is no longer needed.

◆ plist_array_get_item()

plist_t plist_array_get_item ( plist_t  node,
uint32_t  n 
)

Get the nth item in a PLIST_ARRAY node.

Parameters
nodethe node of type PLIST_ARRAY
nthe index of the item to get. Range is [0, array_size[
Returns
the nth item or NULL if node is not of type PLIST_ARRAY

◆ plist_array_get_item_index()

uint32_t plist_array_get_item_index ( plist_t  node)

Get the index of an item.

item must be a member of a PLIST_ARRAY node.

Parameters
nodethe node
Returns
the node index or UINT_MAX if node index can't be determined

◆ plist_array_get_size()

uint32_t plist_array_get_size ( plist_t  node)

Get size of a PLIST_ARRAY node.

Parameters
nodethe node of type PLIST_ARRAY
Returns
size of the PLIST_ARRAY node

◆ plist_array_insert_item()

void plist_array_insert_item ( plist_t  node,
plist_t  item,
uint32_t  n 
)

Insert a new item at position n in a PLIST_ARRAY node.

Parameters
nodethe node of type PLIST_ARRAY
itemthe new item to insert. The array is responsible for freeing item when it is no longer needed.
nThe position at which the node will be stored. Range is [0, array_size[. Assert if n is not in range.

◆ plist_array_item_remove()

void plist_array_item_remove ( plist_t  node)

Remove a node that is a child node of a PLIST_ARRAY node.

node will be freed using plist_free.

Parameters
nodeThe node to be removed from its PLIST_ARRAY parent.

◆ plist_array_new_iter()

void plist_array_new_iter ( plist_t  node,
plist_array_iter iter 
)

Create an iterator of a PLIST_ARRAY node.

The allocated iterator should be freed with the standard free function.

Parameters
nodeThe node of type PLIST_ARRAY
iterLocation to store the iterator for the array.

◆ plist_array_next_item()

void plist_array_next_item ( plist_t  node,
plist_array_iter  iter,
plist_t item 
)

Increment iterator of a PLIST_ARRAY node.

Parameters
nodeThe node of type PLIST_ARRAY.
iterIterator of the array
itemLocation to store the item. The caller must not free the returned item. Will be set to NULL when no more items are left to iterate.

◆ plist_array_remove_item()

void plist_array_remove_item ( plist_t  node,
uint32_t  n 
)

Remove an existing position in a PLIST_ARRAY node.

Removed position will be freed using plist_free.

Parameters
nodethe node of type PLIST_ARRAY
nThe position to remove. Range is [0, array_size[. Assert if n is not in range.

◆ plist_array_set_item()

void plist_array_set_item ( plist_t  node,
plist_t  item,
uint32_t  n 
)

Set the nth item in a PLIST_ARRAY node.

The previous item at index n will be freed using plist_free

Parameters
nodethe node of type PLIST_ARRAY
itemthe new item at index n. The array is responsible for freeing item when it is no longer needed.
nthe index of the item to get. Range is [0, array_size[. Assert if n is not in range.

◆ plist_bool_val_is_true()

int plist_bool_val_is_true ( plist_t  boolnode)

Helper function to check the value of a PLIST_BOOL node.

Parameters
boolnodenode of type PLIST_BOOL
Returns
1 if the boolean node has a value of TRUE or 0 if FALSE.

◆ plist_compare_node_value()

char plist_compare_node_value ( plist_t  node_l,
plist_t  node_r 
)

Compare two node values.

Parameters
node_lleft node to compare
node_rrigth node to compare
Returns
TRUE is type and value match, FALSE otherwise.

◆ plist_copy()

plist_t plist_copy ( plist_t  node)

Return a copy of passed node and it's children.

Parameters
nodethe plist to copy
Returns
copied plist

◆ plist_data_val_compare()

int plist_data_val_compare ( plist_t  datanode,
const uint8_t *  cmpval,
size_t  n 
)

Helper function to compare the data of a PLIST_DATA node against a given blob and size.

This function basically behaves like memcmp after making sure the size of the node's data value is equal to the size of cmpval (n), making this a "full match" comparison.

Parameters
datanodenode of type PLIST_DATA
cmpvaldata blob to compare against
nsize of data blob passed in cmpval
Returns
0 if the node's data blob and cmpval are equal, > 0 if the node's value is lexicographically greater than cmpval, or < 0 if the node's value is lexicographically less than cmpval.

◆ plist_data_val_compare_with_size()

int plist_data_val_compare_with_size ( plist_t  datanode,
const uint8_t *  cmpval,
size_t  n 
)

Helper function to compare the data of a PLIST_DATA node against a given blob and size, while no more than n bytes are compared.

This function basically behaves like memcmp after making sure the size of the node's data value is at least n, making this a "starts with" comparison.

Parameters
datanodenode of type PLIST_DATA
cmpvaldata blob to compare against
nsize of data blob passed in cmpval
Returns
0 if the node's value and cmpval are equal, > 0 if the node's value is lexicographically greater than cmpval, or < 0 if the node's value is lexicographically less than cmpval.

◆ plist_data_val_contains()

int plist_data_val_contains ( plist_t  datanode,
const uint8_t *  cmpval,
size_t  n 
)

Helper function to match a given data blob within the value of a PLIST_DATA node.

Parameters
datanodenode of type PLIST_KEY
cmpvaldata blob to match
nsize of data blob passed in cmpval
Returns
1 if the node's value contains the given data blob or 0 if not.

◆ plist_date_val_compare()

int plist_date_val_compare ( plist_t  datenode,
int32_t  cmpsec,
int32_t  cmpusec 
)

Helper function to compare the value of a PLIST_DATE node against a given set of seconds and fraction of a second since epoch.

Parameters
datenodenode of type PLIST_DATE
cmpsecnumber of seconds since epoch to compare against
cmpusecfraction of a second in microseconds to compare against
Returns
0 if the node's date is equal to the supplied values, 1 if the node's date is greater than the supplied values, or -1 if the node's date is less than the supplied values.

◆ plist_dict_copy_bool()

plist_err_t plist_dict_copy_bool ( plist_t  target_dict,
plist_t  source_dict,
const char *  key,
const char *  alt_source_key 
)

Copy a boolean value from source_dict to target_dict.

The node is looked up in source_dict with given key, unless alt_source_key is non-NULL, in which case it is looked up with alt_source_key. The entry in target_dict is always created with key.

Note
The boolean value from source_dict is retrieved with plist_dict_get_bool, but is always created as PLIST_BOOLEAN in target_dict.
Parameters
target_dictThe target dictionary to copy to.
source_dictThe source dictionary to copy from.
keyThe key for the node to copy.
alt_source_keyThe alternative source key for lookup in source_dict or NULL.
Returns
PLIST_ERR_SUCCESS on success or PLIST_ERR_INVALID_ARG if the source dictionary does not contain any entry with given key or alt_source_key.

◆ plist_dict_copy_data()

plist_err_t plist_dict_copy_data ( plist_t  target_dict,
plist_t  source_dict,
const char *  key,
const char *  alt_source_key 
)

Copy a PLIST_DATA node from source_dict to target_dict.

The node is looked up in source_dict with given key, unless alt_source_key is non-NULL, in which case it is looked up with alt_source_key. The entry in target_dict is always created with key.

Note
This function is like plist_dict_copy_item, except that it fails if the source node is not of type PLIST_DATA.
Parameters
target_dictThe target dictionary to copy to.
source_dictThe source dictionary to copy from.
keyThe key for the node value to copy.
alt_source_keyThe alternative source key for lookup in source_dict or NULL.
Returns
PLIST_ERR_SUCCESS on success or PLIST_ERR_INVALID_ARG if the source dictionary does not contain any entry with given key or alt_source_key, or if it is not of type PLIST_DATA.

◆ plist_dict_copy_int()

plist_err_t plist_dict_copy_int ( plist_t  target_dict,
plist_t  source_dict,
const char *  key,
const char *  alt_source_key 
)

Copy a signed integer value from source_dict to target_dict.

The node is looked up in source_dict with given key, unless alt_source_key is non-NULL, in which case it is looked up with alt_source_key. The entry in target_dict is always created with key.

Note
The signed integer value from source_dict is retrieved with plist_dict_get_int, but is always created as PLIST_INT.
Parameters
target_dictThe target dictionary to copy to.
source_dictThe source dictionary to copy from.
keyThe key for the node value to copy.
alt_source_keyThe alternative source key for lookup in source_dict or NULL.
Returns
PLIST_ERR_SUCCESS on success or PLIST_ERR_INVALID_ARG if the source dictionary does not contain any entry with given key or alt_source_key.

◆ plist_dict_copy_item()

plist_err_t plist_dict_copy_item ( plist_t  target_dict,
plist_t  source_dict,
const char *  key,
const char *  alt_source_key 
)

Copy a node from source_dict to target_dict.

The node is looked up in source_dict with given key, unless alt_source_key is non-NULL, in which case it is looked up with alt_source_key. The entry in target_dict is always created with key.

Parameters
target_dictThe target dictionary to copy to.
source_dictThe source dictionary to copy from.
keyThe key for the node to copy.
alt_source_keyThe alternative source key for lookup in source_dict or NULL.
Returns
PLIST_ERR_SUCCESS on success or PLIST_ERR_INVALID_ARG if the source dictionary does not contain any entry with given key or alt_source_key.

◆ plist_dict_copy_string()

plist_err_t plist_dict_copy_string ( plist_t  target_dict,
plist_t  source_dict,
const char *  key,
const char *  alt_source_key 
)

Copy a PLIST_STRING node from source_dict to target_dict.

The node is looked up in source_dict with given key, unless alt_source_key is non-NULL, in which case it is looked up with alt_source_key. The entry in target_dict is always created with key.

Note
This function is like plist_dict_copy_item, except that it fails if the source node is not of type PLIST_STRING.
Parameters
target_dictThe target dictionary to copy to.
source_dictThe source dictionary to copy from.
keyThe key for the node value to copy.
alt_source_keyThe alternative source key for lookup in source_dict or NULL.
Returns
PLIST_ERR_SUCCESS on success or PLIST_ERR_INVALID_ARG if the source dictionary does not contain any entry with given key or alt_source_key, or if it is not of type PLIST_STRING.

◆ plist_dict_copy_uint()

plist_err_t plist_dict_copy_uint ( plist_t  target_dict,
plist_t  source_dict,
const char *  key,
const char *  alt_source_key 
)

Copy an unsigned integer value from source_dict to target_dict.

The node is looked up in source_dict with given key, unless alt_source_key is non-NULL, in which case it is looked up with alt_source_key. The entry in target_dict is always created with key.

Note
The unsigned integer value from source_dict is retrieved with plist_dict_get_uint, but is always created as PLIST_INT.
Parameters
target_dictThe target dictionary to copy to.
source_dictThe source dictionary to copy from.
keyThe key for the node value to copy.
alt_source_keyThe alternative source key for lookup in source_dict or NULL.
Returns
PLIST_ERR_SUCCESS on success or PLIST_ERR_INVALID_ARG if the source dictionary does not contain any entry with given key or alt_source_key.

◆ plist_dict_get_bool()

uint8_t plist_dict_get_bool ( plist_t  dict,
const char *  key 
)

Get a boolean value from a given PLIST_DICT entry.

The value node can be of type PLIST_BOOLEAN, but also PLIST_STRING (either 'true' or 'false'), PLIST_INT with a numerical value of 0 or >= 1, or PLIST_DATA with a single byte with a value of 0 or >= 1.

Note
This function returns 0 if the dictionary does not contain an entry for the given key, if the value node is of any other than the above mentioned type, or has any mismatching value.
Parameters
dictA node of type PLIST_DICT
keyThe key to look for in dict
Returns
0 or 1 depending on the value of the node.

◆ plist_dict_get_int()

int64_t plist_dict_get_int ( plist_t  dict,
const char *  key 
)

Get a signed integer value from a given PLIST_DICT entry.

The value node can be of type PLIST_INT, but also PLIST_STRING with a numerical value as string (decimal or hexadecimal), or PLIST_DATA with a size of 1, 2, 4, or 8 bytes in little endian byte order.

Note
This function returns 0 if the dictionary does not contain an entry for the given key, if the value node is of any other than the above mentioned type, or has any mismatching value.
Parameters
dictA node of type PLIST_DICT
keyThe key to look for in dict
Returns
Signed integer value depending on the value of the node.

◆ plist_dict_get_item()

plist_t plist_dict_get_item ( plist_t  node,
const char *  key 
)

Get the nth item in a PLIST_DICT node.

Parameters
nodethe node of type PLIST_DICT
keythe identifier of the item to get.
Returns
the item or NULL if node is not of type PLIST_DICT. The caller should not free the returned node.

◆ plist_dict_get_item_key()

void plist_dict_get_item_key ( plist_t  node,
char **  key 
)

Get key associated key to an item.

Item must be member of a dictionary.

Parameters
nodethe item
keya location to store the key. The caller is responsible for freeing the returned string.

◆ plist_dict_get_size()

uint32_t plist_dict_get_size ( plist_t  node)

Get size of a PLIST_DICT node.

Parameters
nodethe node of type PLIST_DICT
Returns
size of the PLIST_DICT node

◆ plist_dict_get_uint()

uint64_t plist_dict_get_uint ( plist_t  dict,
const char *  key 
)

Get an unsigned integer value from a given PLIST_DICT entry.

The value node can be of type PLIST_INT, but also PLIST_STRING with a numerical value as string (decimal or hexadecimal), or PLIST_DATA with a size of 1, 2, 4, or 8 bytes in little endian byte order.

Note
This function returns 0 if the dictionary does not contain an entry for the given key, if the value node is of any other than the above mentioned type, or has any mismatching value.
Parameters
dictA node of type PLIST_DICT
keyThe key to look for in dict
Returns
Signed integer value depending on the value of the node.

◆ plist_dict_item_get_key()

plist_t plist_dict_item_get_key ( plist_t  node)

Get key node associated to an item.

Item must be member of a dictionary.

Parameters
nodethe item
Returns
the key node of the given item, or NULL.

◆ plist_dict_merge()

void plist_dict_merge ( plist_t target,
plist_t  source 
)

Merge a dictionary into another.

This will add all key/value pairs from the source dictionary to the target dictionary, overwriting any existing key/value pairs that are already present in target.

Parameters
targetpointer to an existing node of type PLIST_DICT
sourcenode of type PLIST_DICT that should be merged into target

◆ plist_dict_new_iter()

void plist_dict_new_iter ( plist_t  node,
plist_dict_iter iter 
)

Create an iterator of a PLIST_DICT node.

The allocated iterator should be freed with the standard free function.

Parameters
nodeThe node of type PLIST_DICT.
iterLocation to store the iterator for the dictionary.

◆ plist_dict_next_item()

void plist_dict_next_item ( plist_t  node,
plist_dict_iter  iter,
char **  key,
plist_t val 
)

Increment iterator of a PLIST_DICT node.

Parameters
nodeThe node of type PLIST_DICT
iterIterator of the dictionary
keyLocation to store the key, or NULL. The caller is responsible for freeing the the returned string.
valLocation to store the value, or NULL. The caller must not free the returned value. Will be set to NULL when no more key/value pairs are left to iterate.

◆ plist_dict_remove_item()

void plist_dict_remove_item ( plist_t  node,
const char *  key 
)

Remove an existing position in a PLIST_DICT node.

Removed position will be freed using plist_free

Parameters
nodethe node of type PLIST_DICT
keyThe identifier of the item to remove. Assert if identifier is not present.

◆ plist_dict_set_item()

void plist_dict_set_item ( plist_t  node,
const char *  key,
plist_t  item 
)

Set item identified by key in a PLIST_DICT node.

The previous item identified by key will be freed using plist_free. If there is no item for the given key a new item will be inserted.

Parameters
nodethe node of type PLIST_DICT
itemthe new item associated to key
keythe identifier of the item to set.

◆ plist_free()

void plist_free ( plist_t  plist)

Destruct a plist_t node and all its children recursively.

Parameters
plistthe plist to free

◆ plist_from_bin()

plist_err_t plist_from_bin ( const char *  plist_bin,
uint32_t  length,
plist_t plist 
)

Import the plist_t structure from binary format.

Parameters
plist_bina pointer to the xml buffer.
lengthlength of the buffer to read.
plista pointer to the imported plist.
Returns
PLIST_ERR_SUCCESS on success or a plist_err_t on failure

◆ plist_from_json()

plist_err_t plist_from_json ( const char *  json,
uint32_t  length,
plist_t plist 
)

Import the plist_t structure from JSON format.

Parameters
jsona pointer to the JSON buffer.
lengthlength of the buffer to read.
plista pointer to the imported plist.
Returns
PLIST_ERR_SUCCESS on success or a plist_err_t on failure

◆ plist_from_memory()

plist_err_t plist_from_memory ( const char *  plist_data,
uint32_t  length,
plist_t plist,
plist_format_t format 
)

Import the plist_t structure from memory data.

This function will look at the first bytes of plist_data to determine if plist_data contains a binary, JSON, OpenStep, or XML plist and tries to parse the data in the appropriate format.

Note
This is just a convenience function and the format detection is very basic. It checks with plist_is_binary() if the data supposedly contains binary plist data, if not it checks if the first bytes have either '{' or '[' and assumes JSON format, and XML tags will result in parsing as XML, otherwise it will try to parse as OpenStep.
Parameters
plist_dataA pointer to the memory buffer containing plist data.
lengthLength of the buffer to read.
plistA pointer to the imported plist.
formatIf non-NULL, the plist_format_t value pointed to will be set to the parsed format.
Returns
PLIST_ERR_SUCCESS on success or a plist_err_t on failure

◆ plist_from_openstep()

plist_err_t plist_from_openstep ( const char *  openstep,
uint32_t  length,
plist_t plist 
)

Import the plist_t structure from OpenStep plist format.

Parameters
openstepa pointer to the OpenStep plist buffer.
lengthlength of the buffer to read.
plista pointer to the imported plist.
Returns
PLIST_ERR_SUCCESS on success or a plist_err_t on failure

◆ plist_from_xml()

plist_err_t plist_from_xml ( const char *  plist_xml,
uint32_t  length,
plist_t plist 
)

Import the plist_t structure from XML format.

Parameters
plist_xmla pointer to the xml buffer.
lengthlength of the buffer to read.
plista pointer to the imported plist.
Returns
PLIST_ERR_SUCCESS on success or a plist_err_t on failure

◆ plist_get_bool_val()

void plist_get_bool_val ( plist_t  node,
uint8_t *  val 
)

Get the value of a PLIST_BOOLEAN node.

This function does nothing if node is not of type PLIST_BOOLEAN

Parameters
nodethe node
vala pointer to a uint8_t variable.

◆ plist_get_data_ptr()

const char * plist_get_data_ptr ( plist_t  node,
uint64_t *  length 
)

Get a pointer to the data buffer of a PLIST_DATA node.

Note
DO NOT MODIFY the buffer. Mind that the buffer is only available until the plist node gets freed. Make a copy if needed.
Parameters
nodeThe node
lengthPointer to a uint64_t that will be set to the length of the buffer
Returns
Pointer to the buffer

◆ plist_get_data_val()

void plist_get_data_val ( plist_t  node,
char **  val,
uint64_t *  length 
)

Get the value of a PLIST_DATA node.

This function does nothing if node is not of type PLIST_DATA

Parameters
nodethe node
vala pointer to an unallocated char buffer. This function allocates the memory, caller is responsible for freeing it.
lengththe length of the buffer
Note
Use plist_mem_free() to free the allocated memory.

◆ plist_get_date_val()

void plist_get_date_val ( plist_t  node,
int32_t *  sec,
int32_t *  usec 
)

Get the value of a PLIST_DATE node.

This function does nothing if node is not of type PLIST_DATE

Parameters
nodethe node
seca pointer to an int32_t variable. Represents the number of seconds since 01/01/2001.
useca pointer to an int32_t variable. Represents the number of microseconds

◆ plist_get_int_val()

void plist_get_int_val ( plist_t  node,
int64_t *  val 
)

Get the signed integer value of a PLIST_INT node.

This function does nothing if node is not of type PLIST_INT

Parameters
nodethe node
vala pointer to a int64_t variable.

◆ plist_get_key_val()

void plist_get_key_val ( plist_t  node,
char **  val 
)

Get the value of a PLIST_KEY node.

This function does nothing if node is not of type PLIST_KEY

Parameters
nodethe node
vala pointer to a C-string. This function allocates the memory, caller is responsible for freeing it.
Note
Use plist_mem_free() to free the allocated memory.

◆ plist_get_node_type()

plist_type plist_get_node_type ( plist_t  node)

Get the plist_type of a node.

Parameters
nodethe node
Returns
the type of the node

◆ plist_get_parent()

plist_t plist_get_parent ( plist_t  node)

Get the parent of a node.

Parameters
nodethe parent (NULL if node is root)

◆ plist_get_real_val()

void plist_get_real_val ( plist_t  node,
double *  val 
)

Get the value of a PLIST_REAL node.

This function does nothing if node is not of type PLIST_REAL

Parameters
nodethe node
vala pointer to a double variable.

◆ plist_get_string_ptr()

const char * plist_get_string_ptr ( plist_t  node,
uint64_t *  length 
)

Get a pointer to the buffer of a PLIST_STRING node.

Note
DO NOT MODIFY the buffer. Mind that the buffer is only available until the plist node gets freed. Make a copy if needed.
Parameters
nodeThe node
lengthIf non-NULL, will be set to the length of the string
Returns
Pointer to the NULL-terminated buffer.

◆ plist_get_string_val()

void plist_get_string_val ( plist_t  node,
char **  val 
)

Get the value of a PLIST_STRING node.

This function does nothing if node is not of type PLIST_STRING

Parameters
nodethe node
vala pointer to a C-string. This function allocates the memory, caller is responsible for freeing it. Data is UTF-8 encoded.
Note
Use plist_mem_free() to free the allocated memory.

◆ plist_get_uid_val()

void plist_get_uid_val ( plist_t  node,
uint64_t *  val 
)

Get the value of a PLIST_UID node.

This function does nothing if node is not of type PLIST_UID

Parameters
nodethe node
vala pointer to a uint64_t variable.

◆ plist_get_uint_val()

void plist_get_uint_val ( plist_t  node,
uint64_t *  val 
)

Get the unsigned integer value of a PLIST_INT node.

This function does nothing if node is not of type PLIST_INT

Parameters
nodethe node
vala pointer to a uint64_t variable.

◆ plist_int_val_compare()

int plist_int_val_compare ( plist_t  uintnode,
int64_t  cmpval 
)

Helper function to compare the value of a PLIST_INT node against a given signed integer value.

Parameters
uintnodenode of type PLIST_INT
cmpvalvalue to compare against
Returns
0 if the node's value and cmpval are equal, 1 if the node's value is greater than cmpval, or -1 if the node's value is less than cmpval.

◆ plist_int_val_is_negative()

int plist_int_val_is_negative ( plist_t  intnode)

Helper function to test if a given PLIST_INT node's value is negative.

Parameters
intnodenode of type PLIST_INT
Returns
1 if the node's value is negative, or 0 if positive.

◆ plist_is_binary()

int plist_is_binary ( const char *  plist_data,
uint32_t  length 
)

Test if in-memory plist data is in binary format.

This function will look at the first bytes of plist_data to determine if it supposedly contains a binary plist.

Note
The function is not validating the whole memory buffer to check if the content is truly a plist, it is only using some heuristic on the first few bytes of plist_data.
Parameters
plist_dataa pointer to the memory buffer containing plist data.
lengthlength of the buffer to read.
Returns
1 if the buffer is a binary plist, 0 otherwise.

◆ plist_key_val_compare()

int plist_key_val_compare ( plist_t  keynode,
const char *  cmpval 
)

Helper function to compare the value of a PLIST_KEY node against a given value.

This function basically behaves like strcmp.

Parameters
keynodenode of type PLIST_KEY
cmpvalvalue to compare against
Returns
0 if the node's value and cmpval are equal, > 0 if the node's value is lexicographically greater than cmpval, or < 0 if the node's value is lexicographically less than cmpval.

◆ plist_key_val_compare_with_size()

int plist_key_val_compare_with_size ( plist_t  keynode,
const char *  cmpval,
size_t  n 
)

Helper function to compare the value of a PLIST_KEY node against a given value, while not comparing more than n characters.

This function basically behaves like strncmp.

Parameters
keynodenode of type PLIST_KEY
cmpvalvalue to compare against
nmaximum number of characters to compare
Returns
0 if the node's value and cmpval are equal, > 0 if the node's value is lexicographically greater than cmpval, or < 0 if the node's value is lexicographically less than cmpval.

◆ plist_key_val_contains()

int plist_key_val_contains ( plist_t  keynode,
const char *  substr 
)

Helper function to match a given substring in the value of a PLIST_KEY node.

Parameters
keynodenode of type PLIST_KEY
substrvalue to match
Returns
1 if the node's value contains the given substring, or 0 if not.

◆ plist_mem_free()

void plist_mem_free ( void *  ptr)

Free memory allocated by relevant libplist API calls:

Parameters
ptrpointer to the memory to free
Note
Do not use this function to free plist_t nodes, use plist_free() instead.

◆ plist_new_array()

plist_t plist_new_array ( void  )

Create a new root plist_t type PLIST_ARRAY.

Returns
the created plist
See also
plist_type

◆ plist_new_bool()

plist_t plist_new_bool ( uint8_t  val)

Create a new plist_t type PLIST_BOOLEAN.

Parameters
valthe boolean value, 0 is false, other values are true.
Returns
the created item
See also
plist_type

◆ plist_new_data()

plist_t plist_new_data ( const char *  val,
uint64_t  length 
)

Create a new plist_t type PLIST_DATA.

Parameters
valthe binary buffer
lengththe length of the buffer
Returns
the created item
See also
plist_type

◆ plist_new_date()

plist_t plist_new_date ( int32_t  sec,
int32_t  usec 
)

Create a new plist_t type PLIST_DATE.

Parameters
secthe number of seconds since 01/01/2001
usecthe number of microseconds
Returns
the created item
See also
plist_type

◆ plist_new_dict()

plist_t plist_new_dict ( void  )

Create a new root plist_t type PLIST_DICT.

Returns
the created plist
See also
plist_type

◆ plist_new_int()

plist_t plist_new_int ( int64_t  val)

Create a new plist_t type PLIST_INT with a signed integer value.

Parameters
valthe signed integer value
Returns
the created item
See also
plist_type
Note
The value is always stored as uint64_t internally. Use plist_get_uint_val or plist_get_int_val to get the unsigned or signed value.

◆ plist_new_null()

plist_t plist_new_null ( void  )

Create a new plist_t type PLIST_NULL.

Returns
the created item
See also
plist_type
Note
This type is not valid for all formats, e.g. the XML format does not support it.

◆ plist_new_real()

plist_t plist_new_real ( double  val)

Create a new plist_t type PLIST_REAL.

Parameters
valthe real value
Returns
the created item
See also
plist_type

◆ plist_new_string()

plist_t plist_new_string ( const char *  val)

Create a new plist_t type PLIST_STRING.

Parameters
valthe sting value, encoded in UTF8.
Returns
the created item
See also
plist_type

◆ plist_new_uid()

plist_t plist_new_uid ( uint64_t  val)

Create a new plist_t type PLIST_UID.

Parameters
valthe unsigned integer value
Returns
the created item
See also
plist_type

◆ plist_new_uint()

plist_t plist_new_uint ( uint64_t  val)

Create a new plist_t type PLIST_INT with an unsigned integer value.

Parameters
valthe unsigned integer value
Returns
the created item
See also
plist_type
Note
The value is always stored as uint64_t internally. Use plist_get_uint_val or plist_get_int_val to get the unsigned or signed value.

◆ plist_print()

void plist_print ( plist_t  plist)

Print the given plist in human-readable format to standard output.

This is equivalent to plist_write_to_stream(plist, stdout, PLIST_FORMAT_PRINT, PLIST_OPT_PARTIAL_DATA);

Parameters
plistThe plist_t structure to print
Note
For PLIST_DATA nodes, only a maximum of 24 bytes (first 16 and last 8) are written.

◆ plist_read_from_file()

plist_err_t plist_read_from_file ( const char *  filename,
plist_t plist,
plist_format_t format 
)

Import the plist_t structure directly from file.

This function will look at the first bytes of the file data to determine if it contains a binary, JSON, OpenStep, or XML plist and tries to parse the data in the appropriate format. Uses plist_from_memory() internally.

Parameters
filenameThe name of the file to parse.
plistA pointer to the imported plist.
formatIf non-NULL, the plist_format_t value pointed to will be set to the parsed format.
Returns
PLIST_ERR_SUCCESS on success or a plist_err_t on failure

◆ plist_real_val_compare()

int plist_real_val_compare ( plist_t  realnode,
double  cmpval 
)

Helper function to compare the value of a PLIST_REAL node against a given value.

Note
WARNING: Comparing floating point values can give inaccurate results because of the nature of floating point values on computer systems. While this function is designed to be as accurate as possible, please don't rely on it too much.
Parameters
realnodenode of type PLIST_REAL
cmpvalvalue to compare against
Returns
0 if the node's value and cmpval are (almost) equal, 1 if the node's value is greater than cmpval, or -1 if the node's value is less than cmpval.

◆ plist_set_bool_val()

void plist_set_bool_val ( plist_t  node,
uint8_t  val 
)

Set the value of a node.

Forces type of node to PLIST_BOOLEAN

Parameters
nodethe node
valthe boolean value

◆ plist_set_data_val()

void plist_set_data_val ( plist_t  node,
const char *  val,
uint64_t  length 
)

Set the value of a node.

Forces type of node to PLIST_DATA

Parameters
nodethe node
valthe binary buffer. The buffer is copied when set and will be freed by the node.
lengththe length of the buffer

◆ plist_set_date_val()

void plist_set_date_val ( plist_t  node,
int32_t  sec,
int32_t  usec 
)

Set the value of a node.

Forces type of node to PLIST_DATE

Parameters
nodethe node
secthe number of seconds since 01/01/2001
usecthe number of microseconds

◆ plist_set_debug()

void plist_set_debug ( int  debug)

Set debug level for the format parsers.

Note
This function does nothing if libplist was not configured with –enable-debug .
Parameters
debugDebug level. Currently, only 0 (off) and 1 (enabled) are supported.

◆ plist_set_int_val()

void plist_set_int_val ( plist_t  node,
int64_t  val 
)

Set the value of a node.

Forces type of node to PLIST_INT

Parameters
nodethe node
valthe signed integer value

◆ plist_set_key_val()

void plist_set_key_val ( plist_t  node,
const char *  val 
)

Set the value of a node.

Forces type of node to PLIST_KEY

Parameters
nodethe node
valthe key value

◆ plist_set_real_val()

void plist_set_real_val ( plist_t  node,
double  val 
)

Set the value of a node.

Forces type of node to PLIST_REAL

Parameters
nodethe node
valthe real value

◆ plist_set_string_val()

void plist_set_string_val ( plist_t  node,
const char *  val 
)

Set the value of a node.

Forces type of node to PLIST_STRING

Parameters
nodethe node
valthe string value. The string is copied when set and will be freed by the node.

◆ plist_set_uid_val()

void plist_set_uid_val ( plist_t  node,
uint64_t  val 
)

Set the value of a node.

Forces type of node to PLIST_UID

Parameters
nodethe node
valthe unsigned integer value

◆ plist_set_uint_val()

void plist_set_uint_val ( plist_t  node,
uint64_t  val 
)

Set the value of a node.

Forces type of node to PLIST_INT

Parameters
nodethe node
valthe unsigned integer value

◆ plist_sort()

void plist_sort ( plist_t  plist)

Sort all PLIST_DICT key/value pairs in a property list lexicographically by key.

Recurses into the child nodes if necessary.

Parameters
plistThe property list to perform the sorting operation on.

◆ plist_string_val_compare()

int plist_string_val_compare ( plist_t  strnode,
const char *  cmpval 
)

Helper function to compare the value of a PLIST_STRING node against a given value.

This function basically behaves like strcmp.

Parameters
strnodenode of type PLIST_STRING
cmpvalvalue to compare against
Returns
0 if the node's value and cmpval are equal, > 0 if the node's value is lexicographically greater than cmpval, or < 0 if the node's value is lexicographically less than cmpval.

◆ plist_string_val_compare_with_size()

int plist_string_val_compare_with_size ( plist_t  strnode,
const char *  cmpval,
size_t  n 
)

Helper function to compare the value of a PLIST_STRING node against a given value, while not comparing more than n characters.

This function basically behaves like strncmp.

Parameters
strnodenode of type PLIST_STRING
cmpvalvalue to compare against
nmaximum number of characters to compare
Returns
0 if the node's value and cmpval are equal, > 0 if the node's value is lexicographically greater than cmpval, or < 0 if the node's value is lexicographically less than cmpval.

◆ plist_string_val_contains()

int plist_string_val_contains ( plist_t  strnode,
const char *  substr 
)

Helper function to match a given substring in the value of a PLIST_STRING node.

Parameters
strnodenode of type PLIST_STRING
substrvalue to match
Returns
1 if the node's value contains the given substring, or 0 if not.

◆ plist_to_bin()

plist_err_t plist_to_bin ( plist_t  plist,
char **  plist_bin,
uint32_t *  length 
)

Export the plist_t structure to binary format.

Parameters
plistthe root node to export
plist_bina pointer to a char* buffer. This function allocates the memory, caller is responsible for freeing it.
lengtha pointer to an uint32_t variable. Represents the length of the allocated buffer.
Returns
PLIST_ERR_SUCCESS on success or a plist_err_t on failure
Note
Use plist_mem_free() to free the allocated memory.

◆ plist_to_json()

plist_err_t plist_to_json ( plist_t  plist,
char **  plist_json,
uint32_t *  length,
int  prettify 
)

Export the plist_t structure to JSON format.

Parameters
plistthe root node to export
plist_jsona pointer to a char* buffer. This function allocates the memory, caller is responsible for freeing it.
lengtha pointer to an uint32_t variable. Represents the length of the allocated buffer.
prettifypretty print the output if != 0
Returns
PLIST_ERR_SUCCESS on success or a plist_err_t on failure
Note
Use plist_mem_free() to free the allocated memory.

◆ plist_to_openstep()

plist_err_t plist_to_openstep ( plist_t  plist,
char **  plist_openstep,
uint32_t *  length,
int  prettify 
)

Export the plist_t structure to OpenStep format.

Parameters
plistthe root node to export
plist_openstepa pointer to a char* buffer. This function allocates the memory, caller is responsible for freeing it.
lengtha pointer to an uint32_t variable. Represents the length of the allocated buffer.
prettifypretty print the output if != 0
Returns
PLIST_ERR_SUCCESS on success or a plist_err_t on failure
Note
Use plist_mem_free() to free the allocated memory.

◆ plist_to_xml()

plist_err_t plist_to_xml ( plist_t  plist,
char **  plist_xml,
uint32_t *  length 
)

Export the plist_t structure to XML format.

Parameters
plistthe root node to export
plist_xmla pointer to a C-string. This function allocates the memory, caller is responsible for freeing it. Data is UTF-8 encoded.
lengtha pointer to an uint32_t variable. Represents the length of the allocated buffer.
Returns
PLIST_ERR_SUCCESS on success or a plist_err_t on failure
Note
Use plist_mem_free() to free the allocated memory.

◆ plist_uid_val_compare()

int plist_uid_val_compare ( plist_t  uidnode,
uint64_t  cmpval 
)

Helper function to compare the value of a PLIST_UID node against a given value.

Parameters
uidnodenode of type PLIST_UID
cmpvalvalue to compare against
Returns
0 if the node's value and cmpval are equal, 1 if the node's value is greater than cmpval, or -1 if the node's value is less than cmpval.

◆ plist_uint_val_compare()

int plist_uint_val_compare ( plist_t  uintnode,
uint64_t  cmpval 
)

Helper function to compare the value of a PLIST_INT node against a given unsigned integer value.

Parameters
uintnodenode of type PLIST_INT
cmpvalvalue to compare against
Returns
0 if the node's value and cmpval are equal, 1 if the node's value is greater than cmpval, or -1 if the node's value is less than cmpval.

◆ plist_write_to_file()

plist_err_t plist_write_to_file ( plist_t  plist,
const char *  filename,
plist_format_t  format,
plist_write_options_t  options 
)

Write the plist_t structure to a file at given path using the given format and options.

Parameters
plistThe input plist structure
filenameThe file name of the file to write to. Existing files will be overwritten.
formatA plist_format_t value that specifies the output format to use.
optionsOne or more bitwise ORed values of plist_write_options_t.
Returns
PLIST_ERR_SUCCESS on success or a plist_err_t on failure.
Note
Use plist_mem_free() to free the allocated memory.

◆ plist_write_to_stream()

plist_err_t plist_write_to_stream ( plist_t  plist,
FILE *  stream,
plist_format_t  format,
plist_write_options_t  options 
)

Write the plist_t structure to a FILE* stream using the given format and options.

Parameters
plistThe input plist structure
streamA writeable FILE* stream that the data will be written to.
formatA plist_format_t value that specifies the output format to use.
optionsOne or more bitwise ORed values of plist_write_options_t.
Returns
PLIST_ERR_SUCCESS on success or a plist_err_t on failure.
Note
While this function allows all formats to be written to the given stream, only the formats PLIST_FORMAT_PRINT, PLIST_FORMAT_LIMD, and PLIST_FORMAT_PLUTIL (basically all output-only formats) are directly and efficiently written to the stream; the other formats are written to a memory buffer first.

◆ plist_write_to_string()

plist_err_t plist_write_to_string ( plist_t  plist,
char **  output,
uint32_t *  length,
plist_format_t  format,
plist_write_options_t  options 
)

Write the plist_t structure to a NULL-terminated string using the given format and options.

Parameters
plistThe input plist structure
outputPointer to a char* buffer. This function allocates the memory, caller is responsible for freeing it.
lengthA pointer to a uint32_t value that will receive the lenght of the allocated buffer.
formatA plist_format_t value that specifies the output format to use.
optionsOne or more bitwise ORed values of plist_write_options_t.
Returns
PLIST_ERR_SUCCESS on success or a plist_err_t on failure.
Note
Use plist_mem_free() to free the allocated memory.
PLIST_FORMAT_BINARY is not supported by this function.