plist.h File Reference

Description

Main include of libplist.

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_CIRCULAR_REF = -6 ,   PLIST_ERR_MAX_NESTING = -7 ,   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 ,   PLIST_OPT_COERCE = 1 << 4 }
	libplist write options More...

Functions
PLIST_API plist_t	plist_new_dict (void)
	Create a new root plist_t type PLIST_DICT.
PLIST_API plist_t	plist_new_array (void)
	Create a new root plist_t type PLIST_ARRAY.
PLIST_API plist_t	plist_new_string (const char *val)
	Create a new plist_t type PLIST_STRING.
PLIST_API plist_t	plist_new_bool (uint8_t val)
	Create a new plist_t type PLIST_BOOLEAN.
PLIST_API plist_t	plist_new_uint (uint64_t val)
	Create a new plist_t type PLIST_INT with an unsigned integer value.
PLIST_API plist_t	plist_new_int (int64_t val)
	Create a new plist_t type PLIST_INT with a signed integer value.
PLIST_API plist_t	plist_new_real (double val)
	Create a new plist_t type PLIST_REAL.
PLIST_API plist_t	plist_new_data (const char *val, uint64_t length)
	Create a new plist_t type PLIST_DATA.
PLIST_API plist_t	plist_new_unix_date (int64_t sec)
	Create a new plist_t type PLIST_DATE.
PLIST_API plist_t	plist_new_uid (uint64_t val)
	Create a new plist_t type PLIST_UID.
PLIST_API plist_t	plist_new_null (void)
	Create a new plist_t type PLIST_NULL.
PLIST_API void	plist_free (plist_t plist)
	Destruct a plist_t node and all its children recursively.
PLIST_API plist_t	plist_copy (plist_t node)
	Return a copy of passed node and it's children.
PLIST_API uint32_t	plist_array_get_size (plist_t node)
	Get size of a PLIST_ARRAY node.
PLIST_API plist_t	plist_array_get_item (plist_t node, uint32_t n)
	Get the nth item in a PLIST_ARRAY node.
PLIST_API uint32_t	plist_array_get_item_index (plist_t node)
	Get the index of an item.
PLIST_API plist_err_t	plist_array_set_item (plist_t node, plist_t item, uint32_t n)
	Set the nth item in a PLIST_ARRAY node.
PLIST_API plist_err_t	plist_array_append_item (plist_t node, plist_t item)
	Append a new item at the end of a PLIST_ARRAY node.
PLIST_API plist_err_t	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.
PLIST_API plist_err_t	plist_array_remove_item (plist_t node, uint32_t n)
	Remove an existing position in a PLIST_ARRAY node.
PLIST_API plist_err_t	plist_array_item_remove (plist_t item)
	Remove a node that is a child node of a PLIST_ARRAY node.
PLIST_API void	plist_array_new_iter (plist_t node, plist_array_iter *iter)
	Create an iterator of a PLIST_ARRAY node.
PLIST_API void	plist_array_next_item (plist_t node, plist_array_iter iter, plist_t *item)
	Increment iterator of a PLIST_ARRAY node.
PLIST_API void	plist_array_free_iter (plist_array_iter iter)
	Free PLIST_ARRAY iterator.
PLIST_API uint32_t	plist_dict_get_size (plist_t node)
	Get size of a PLIST_DICT node.
PLIST_API void	plist_dict_new_iter (plist_t node, plist_dict_iter *iter)
	Create an iterator of a PLIST_DICT node.
PLIST_API void	plist_dict_next_item (plist_t node, plist_dict_iter iter, char **key, plist_t *val)
	Increment iterator of a PLIST_DICT node.
PLIST_API void	plist_dict_free_iter (plist_dict_iter iter)
	Free PLIST_DICT iterator.
PLIST_API void	plist_dict_get_item_key (plist_t node, char **key)
	Get key associated key to an item.
PLIST_API plist_t	plist_dict_get_item (plist_t node, const char *key)
	Get the nth item in a PLIST_DICT node.
PLIST_API plist_t	plist_dict_item_get_key (plist_t node)
	Get key node associated to an item.
PLIST_API plist_err_t	plist_dict_set_item (plist_t node, const char *key, plist_t item)
	Set item identified by key in a PLIST_DICT node.
PLIST_API plist_err_t	plist_dict_remove_item (plist_t node, const char *key)
	Remove an existing position in a PLIST_DICT node.
PLIST_API plist_err_t	plist_dict_merge (plist_t *target, plist_t source)
	Merge a dictionary into another.
PLIST_API uint8_t	plist_dict_get_bool (plist_t dict, const char *key)
	Get a boolean value from a given PLIST_DICT entry.
PLIST_API int64_t	plist_dict_get_int (plist_t dict, const char *key)
	Get a signed integer value from a given PLIST_DICT entry.
PLIST_API uint64_t	plist_dict_get_uint (plist_t dict, const char *key)
	Get an unsigned integer value from a given PLIST_DICT entry.
PLIST_API 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_API 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_API 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_API 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_API 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_API 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_API plist_t	plist_get_parent (plist_t node)
	Get the parent of a node.
PLIST_API plist_type	plist_get_node_type (plist_t node)
	Get the plist_type of a node.
PLIST_API void	plist_get_key_val (plist_t node, char **val)
	Get the value of a PLIST_KEY node.
PLIST_API void	plist_get_string_val (plist_t node, char **val)
	Get the value of a PLIST_STRING node.
PLIST_API const char *	plist_get_string_ptr (plist_t node, uint64_t *length)
	Get a pointer to the buffer of a PLIST_STRING node.
PLIST_API void	plist_get_bool_val (plist_t node, uint8_t *val)
	Get the value of a PLIST_BOOLEAN node.
PLIST_API void	plist_get_uint_val (plist_t node, uint64_t *val)
	Get the unsigned integer value of a PLIST_INT node.
PLIST_API void	plist_get_int_val (plist_t node, int64_t *val)
	Get the signed integer value of a PLIST_INT node.
PLIST_API void	plist_get_real_val (plist_t node, double *val)
	Get the value of a PLIST_REAL node.
PLIST_API void	plist_get_data_val (plist_t node, char **val, uint64_t *length)
	Get the value of a PLIST_DATA node.
PLIST_API const char *	plist_get_data_ptr (plist_t node, uint64_t *length)
	Get a pointer to the data buffer of a PLIST_DATA node.
PLIST_API void	plist_get_unix_date_val (plist_t node, int64_t *sec)
	Get the value of a PLIST_DATE node.
PLIST_API void	plist_get_uid_val (plist_t node, uint64_t *val)
	Get the value of a PLIST_UID node.
PLIST_API void	plist_set_key_val (plist_t node, const char *val)
	Set the value of a node.
PLIST_API void	plist_set_string_val (plist_t node, const char *val)
	Set the value of a node.
PLIST_API void	plist_set_bool_val (plist_t node, uint8_t val)
	Set the value of a node.
PLIST_API void	plist_set_uint_val (plist_t node, uint64_t val)
	Set the value of a node.
PLIST_API void	plist_set_int_val (plist_t node, int64_t val)
	Set the value of a node.
PLIST_API void	plist_set_real_val (plist_t node, double val)
	Set the value of a node.
PLIST_API void	plist_set_data_val (plist_t node, const char *val, uint64_t length)
	Set the value of a node.
PLIST_API void	plist_set_unix_date_val (plist_t node, int64_t sec)
	Set the value of a node.
PLIST_API void	plist_set_uid_val (plist_t node, uint64_t val)
	Set the value of a node.
PLIST_API plist_err_t	plist_to_xml (plist_t plist, char **plist_xml, uint32_t *length)
	Export the plist_t structure to XML format.
PLIST_API plist_err_t	plist_to_bin (plist_t plist, char **plist_bin, uint32_t *length)
	Export the plist_t structure to binary format.
PLIST_API 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_API plist_err_t	plist_to_json_with_options (plist_t plist, char **plist_json, uint32_t *length, plist_write_options_t options)
	Export the plist_t structure to JSON format with extended options.
PLIST_API 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_API plist_err_t	plist_to_openstep_with_options (plist_t plist, char **plist_openstep, uint32_t *length, plist_write_options_t options)
	Export the plist_t structure to OpenStep format with extended options.
PLIST_API 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_API 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_API plist_err_t	plist_from_json (const char *json, uint32_t length, plist_t *plist)
	Import the plist_t structure from JSON format.
PLIST_API 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_API 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_API 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_API 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_API 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_API 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.
PLIST_API void	plist_print (plist_t plist)
	Print the given plist in human-readable format to standard output.
PLIST_API int	plist_is_binary (const char *plist_data, uint32_t length)
	Test if in-memory plist data is in binary format.
PLIST_API plist_t	plist_access_path (plist_t plist, uint32_t length,...)
	Get a node from its path.
PLIST_API plist_t	plist_access_pathv (plist_t plist, uint32_t length, va_list v)
	Variadic version of plist_access_path.
PLIST_API char	plist_compare_node_value (plist_t node_l, plist_t node_r)
	Compare two node values.
PLIST_API int	plist_bool_val_is_true (plist_t boolnode)
	Helper function to check the value of a PLIST_BOOL node.
PLIST_API int	plist_int_val_is_negative (plist_t intnode)
	Helper function to test if a given PLIST_INT node's value is negative.
PLIST_API 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.
PLIST_API 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.
PLIST_API 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.
PLIST_API 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.
PLIST_API 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).
PLIST_API 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.
PLIST_API 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.
PLIST_API 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.
PLIST_API 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.
PLIST_API 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.
PLIST_API 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.
PLIST_API 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.
PLIST_API 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.
PLIST_API 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.
PLIST_API void	plist_sort (plist_t plist)
	Sort all PLIST_DICT key/value pairs in a property list lexicographically by key.
PLIST_API void	plist_mem_free (void *ptr)
	Free memory allocated by relevant libplist API calls:
PLIST_API void	plist_set_debug (int debug)
	Set debug level for the format parsers.
PLIST_API const char *	libplist_version ()
	Returns a static string of the libplist version.
PLIST_API plist_t	plist_new_date (int32_t sec, int32_t usec)
	Create a new plist_t type PLIST_DATE.
PLIST_API void	plist_get_date_val (plist_t node, int32_t *sec, int32_t *usec)
	Get the value of a PLIST_DATE node.
PLIST_API void	plist_set_date_val (plist_t node, int32_t sec, int32_t usec)
	Set the value of a node.
PLIST_API 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.