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)
| 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)
| Helper macro used by PLIST_IS_* macros that will evaluate the type of a plist node.
#define | PLIST_IS_BOOLEAN(__plist)
| Evaluates to true if the given plist node is of type PLIST_BOOLEAN.
#define | PLIST_IS_INT(__plist)
| Evaluates to true if the given plist node is of type PLIST_INT.
#define | PLIST_IS_REAL(__plist)
| Evaluates to true if the given plist node is of type PLIST_REAL.
#define | PLIST_IS_STRING(__plist)
| Evaluates to true if the given plist node is of type PLIST_STRING.
#define | PLIST_IS_ARRAY(__plist)
| Evaluates to true if the given plist node is of type PLIST_ARRAY.
#define | PLIST_IS_DICT(__plist)
| Evaluates to true if the given plist node is of type PLIST_DICT.
#define | PLIST_IS_DATE(__plist)
| Evaluates to true if the given plist node is of type PLIST_DATE.
#define | PLIST_IS_DATA(__plist)
| Evaluates to true if the given plist node is of type PLIST_DATA.
#define | PLIST_IS_KEY(__plist)
| Evaluates to true if the given plist node is of type PLIST_KEY.
#define | PLIST_IS_UID(__plist)
| 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_unix_date (int64_t sec)
| 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_unix_date_val (plist_t node, int64_t *sec)
| 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_unix_date_val (plist_t node, int64_t sec)
| 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_unix_date_val_compare (plist_t datenode, int64_t cmpval)
| Helper function to compare the value of a PLIST_DATE node against a given number of seconds since epoch (UNIX timestamp).
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.
plist_t | plist_new_date (int32_t sec, int32_t usec)
| Create a new plist_t type PLIST_DATE.
void | plist_get_date_val (plist_t node, int32_t *sec, int32_t *usec)
| Get the value of a PLIST_DATE node.
void | plist_set_date_val (plist_t node, int32_t sec, int32_t usec)
| Set the value of a node.
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.

## Detailed Description

Main include of libplist.

## Macro Definition Documentation

## _PLIST_IS_TYPE

#define _PLIST_IS_TYPE | ( |  | __plist,
|  |  | __plist_type )

Value:
(__plist && (plist_get_node_type(__plist) == PLIST_##__plist_type))
plist_get_node_type
plist_type plist_get_node_type(plist_t node)
Get the plist_type of a node.

Helper macro used by PLIST_IS_* macros that will evaluate the type of a plist node.

## PLIST_IS_ARRAY

#define PLIST_IS_ARRAY | ( |  | __plist | ) |

Value:
_PLIST_IS_TYPE(__plist, ARRAY)
_PLIST_IS_TYPE
#define _PLIST_IS_TYPE(__plist, __plist_type)
Helper macro used by PLIST_IS_* macros that will evaluate the type of a plist node.
Definition plist.h:1116

Evaluates to true if the given plist node is of type PLIST_ARRAY.

## PLIST_IS_BOOLEAN

#define PLIST_IS_BOOLEAN | ( |  | __plist | ) |

Value:
_PLIST_IS_TYPE(__plist, BOOLEAN)

Evaluates to true if the given plist node is of type PLIST_BOOLEAN.

## PLIST_IS_DATA

#define PLIST_IS_DATA | ( |  | __plist | ) |

Value:
_PLIST_IS_TYPE(__plist, DATA)

Evaluates to true if the given plist node is of type PLIST_DATA.

## PLIST_IS_DATE

#define PLIST_IS_DATE | ( |  | __plist | ) |

Value:
_PLIST_IS_TYPE(__plist, DATE)

Evaluates to true if the given plist node is of type PLIST_DATE.

## PLIST_IS_DICT

#define PLIST_IS_DICT | ( |  | __plist | ) |

Value:
_PLIST_IS_TYPE(__plist, DICT)

Evaluates to true if the given plist node is of type PLIST_DICT.

## PLIST_IS_INT

#define PLIST_IS_INT | ( |  | __plist | ) |

Value:
_PLIST_IS_TYPE(__plist, INT)

Evaluates to true if the given plist node is of type PLIST_INT.

## PLIST_IS_KEY

#define PLIST_IS_KEY | ( |  | __plist | ) |

Value:
_PLIST_IS_TYPE(__plist, KEY)

Evaluates to true if the given plist node is of type PLIST_KEY.

## PLIST_IS_REAL

#define PLIST_IS_REAL | ( |  | __plist | ) |

Value:
_PLIST_IS_TYPE(__plist, REAL)

Evaluates to true if the given plist node is of type PLIST_REAL.

## PLIST_IS_STRING

#define PLIST_IS_STRING | ( |  | __plist | ) |

Value:
_PLIST_IS_TYPE(__plist, STRING)

Evaluates to true if the given plist node is of type PLIST_STRING.

## PLIST_IS_UID

#define PLIST_IS_UID | ( |  | __plist | ) |

Value:
_PLIST_IS_TYPE(__plist, UID)

Evaluates to true if the given plist node is of type PLIST_UID.

## PLIST_OPT_INDENT_BY

#define PLIST_OPT_INDENT_BY | ( |  | x | ) |

Value:
((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.

## Enumeration Type Documentation

## plist_err_t

enum 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

enum 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

enum 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

  plist | the node to access result from.
  length | length 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

  plist | the node to access result from.
  length | length of the path to access
  v | list 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

  node | the node of type PLIST_ARRAY
  item | the 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

  node | the node of type PLIST_ARRAY
  n | the 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

  node | the 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

  node | the 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

  node | the node of type PLIST_ARRAY
  item | the new item to insert. The array is responsible for freeing item when it is no longer needed.
  n | The 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

  node | The 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

  node | The node of type PLIST_ARRAY
  iter | Location 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

  node | The node of type PLIST_ARRAY.
  iter | Iterator of the array
  item | Location 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

  node | the node of type PLIST_ARRAY
  n | The 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

  node | the node of type PLIST_ARRAY
  item | the new item at index n. The array is responsible for freeing item when it is no longer needed.
  n | the 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

  boolnode | node 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_l | left node to compare
  node_r | rigth 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

  node | the 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

  datanode | node of type PLIST_DATA
  cmpval | data blob to compare against
  n | size 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

  datanode | node of type PLIST_DATA
  cmpval | data blob to compare against
  n | size 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

  datanode | node of type PLIST_KEY
  cmpval | data blob to match
  n | size 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.

Deprecated
  Deprecated. Use plist_unix_date_val_compare instead.

Parameters

  datenode | node of type PLIST_DATE
  cmpsec | number of seconds since epoch to compare against
  cmpusec | fraction 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.

References plist_date_val_compare().

Referenced by plist_date_val_compare().

## 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_dict | The target dictionary to copy to.
  source_dict | The source dictionary to copy from.
  key | The key for the node to copy.
  alt_source_key | The 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_dict | The target dictionary to copy to.
  source_dict | The source dictionary to copy from.
  key | The key for the node value to copy.
  alt_source_key | The 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_dict | The target dictionary to copy to.
  source_dict | The source dictionary to copy from.
  key | The key for the node value to copy.
  alt_source_key | The 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_dict | The target dictionary to copy to.
  source_dict | The source dictionary to copy from.
  key | The key for the node to copy.
  alt_source_key | The 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_dict | The target dictionary to copy to.
  source_dict | The source dictionary to copy from.
  key | The key for the node value to copy.
  alt_source_key | The 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_dict | The target dictionary to copy to.
  source_dict | The source dictionary to copy from.
  key | The key for the node value to copy.
  alt_source_key | The 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

  dict | A node of type PLIST_DICT
  key | The 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

  dict | A node of type PLIST_DICT
  key | The 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

  node | the node of type PLIST_DICT
  key | the 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

  node | the item
  key | a 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

  node | the 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

  dict | A node of type PLIST_DICT
  key | The 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

  node | the 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

  target | pointer to an existing node of type PLIST_DICT
  source | node 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

  node | The node of type PLIST_DICT.
  iter | Location 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

  node | The node of type PLIST_DICT
  iter | Iterator of the dictionary
  key | Location to store the key, or NULL. The caller is responsible for freeing the the returned string.
  val | Location 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

  node | the node of type PLIST_DICT
  key | The 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

  node | the node of type PLIST_DICT
  item | the new item associated to key
  key | the 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

  plist | the 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_bin | a pointer to the xml buffer.
  length | length of the buffer to read.
  plist | a 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

  json | a pointer to the JSON buffer.
  length | length of the buffer to read.
  plist | a 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_data | A pointer to the memory buffer containing plist data.
  length | Length of the buffer to read.
  plist | A pointer to the imported plist.
  format | If 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

  openstep | a pointer to the OpenStep plist buffer.
  length | length of the buffer to read.
  plist | a 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_xml | a pointer to the xml buffer.
  length | length of the buffer to read.
  plist | a 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

  node | the node
  val | a 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

  node | The node
  length | Pointer 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

  node | the node
  val | a pointer to an unallocated char buffer. This function allocates the memory, caller is responsible for freeing it.
  length | the 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

Deprecated
  Deprecated. Use plist_get_unix_date_val instead.

Parameters

  node | the node
  sec | a pointer to an int32_t variable. Represents the number of seconds since 01/01/2001.
  usec | a pointer to an int32_t variable. Represents the number of microseconds

References plist_get_date_val().

Referenced by plist_get_date_val().

## 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

  node | the node
  val | a 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

  node | the node
  val | a 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

  node | the 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

  node | the 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

  node | the node
  val | a 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

  node | The node
  length | If 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

  node | the node
  val | a 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

  node | the node
  val | a 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

  node | the node
  val | a pointer to a uint64_t variable.

## plist_get_unix_date_val()

void plist_get_unix_date_val | ( | plist_t | node,
|  | int64_t * | sec )

Get the value of a PLIST_DATE node.

This function does nothing if node is not of type PLIST_DATE

Parameters

  node | the node
  sec | a pointer to an int64_t variable. Represents the number of seconds since 01/01/1970 (UNIX timestamp).

## 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

  uintnode | node of type PLIST_INT
  cmpval | value 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

  intnode | node 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_data | a pointer to the memory buffer containing plist data.
  length | length 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

  keynode | node of type PLIST_KEY
  cmpval | value 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

  keynode | node of type PLIST_KEY
  cmpval | value to compare against
  n | maximum 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

  keynode | node of type PLIST_KEY
  substr | value 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:

- plist_to_xml()
- plist_to_bin()
- plist_get_key_val()
- plist_get_string_val()
- plist_get_data_val()

Parameters

  ptr | pointer 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

  val | the 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

  val | the binary buffer
  length | the 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.

Deprecated
  Deprecated. Use plist_new_unix_date instead.

Parameters

  sec | the number of seconds since 01/01/2001
  usec | the number of microseconds

Returns
  the created item

See also
  plist_type

References plist_new_date().

Referenced by plist_new_date().

## 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

  val | the 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

  val | the 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

  val | the 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

  val | the 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

  val | the 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_new_unix_date()

plist_t plist_new_unix_date | ( | int64_t | sec | ) |

Create a new plist_t type PLIST_DATE.

Parameters

  sec | The number of seconds since 01/01/1970 (UNIX timestamp)

Returns
  the created item

See also
  plist_type

## 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

  plist | The 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

  filename | The name of the file to parse.
  plist | A pointer to the imported plist.
  format | If 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

  realnode | node of type PLIST_REAL
  cmpval | value 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

  node | the node
  val | the 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

  node | the node
  val | the binary buffer. The buffer is copied when set and will be freed by the node.
  length | the 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

Deprecated
  Deprecated. Use plist_set_unix_date_val instead.

Parameters

  node | the node
  sec | the number of seconds since 01/01/2001
  usec | the number of microseconds

References plist_set_date_val().

Referenced by plist_set_date_val().

## 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

  debug | Debug 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

  node | the node
  val | the 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

  node | the node
  val | the 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

  node | the node
  val | the 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

  node | the node
  val | the 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

  node | the node
  val | the 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

  node | the node
  val | the unsigned integer value

## plist_set_unix_date_val()

void plist_set_unix_date_val | ( | plist_t | node,
|  | int64_t | sec )

Set the value of a node.

Forces type of node to PLIST_DATE

Parameters

  node | the node
  sec | the number of seconds since 01/01/1970 (UNIX timestamp)

## 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

  plist | The 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

  strnode | node of type PLIST_STRING
  cmpval | value 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

  strnode | node of type PLIST_STRING
  cmpval | value to compare against
  n | maximum 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

  strnode | node of type PLIST_STRING
  substr | value 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

  plist | the root node to export
  plist_bin | a pointer to a char* buffer. This function allocates the memory, caller is responsible for freeing it.
  length | a 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

  plist | the root node to export
  plist_json | a pointer to a char* buffer. This function allocates the memory, caller is responsible for freeing it.
  length | a pointer to an uint32_t variable. Represents the length of the allocated buffer.
  prettify | pretty 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

  plist | the root node to export
  plist_openstep | a pointer to a char* buffer. This function allocates the memory, caller is responsible for freeing it.
  length | a pointer to an uint32_t variable. Represents the length of the allocated buffer.
  prettify | pretty 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

  plist | the root node to export
  plist_xml | a pointer to a C-string. This function allocates the memory, caller is responsible for freeing it. Data is UTF-8 encoded.
  length | a 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

  uidnode | node of type PLIST_UID
  cmpval | value 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

  uintnode | node of type PLIST_INT
  cmpval | value 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_unix_date_val_compare()

int plist_unix_date_val_compare | ( | plist_t | datenode,
|  | int64_t | cmpval )

Helper function to compare the value of a PLIST_DATE node against a given number of seconds since epoch (UNIX timestamp).

Parameters

  datenode | node of type PLIST_DATE
  cmpval | Number of seconds to compare against (UNIX timestamp)

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_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

  plist | The input plist structure
  filename | The file name of the file to write to. Existing files will be overwritten.
  format | A plist_format_t value that specifies the output format to use.
  options | One 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

  plist | The input plist structure
  stream | A writeable FILE* stream that the data will be written to.
  format | A plist_format_t value that specifies the output format to use.
  options | One 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

  plist | The input plist structure
  output | Pointer to a char* buffer. This function allocates the memory, caller is responsible for freeing it.
  length | A pointer to a uint32_t value that will receive the lenght of the allocated buffer.
  format | A plist_format_t value that specifies the output format to use.
  options | One 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.