PPATH(3) | Library Functions Manual | PPATH(3) |
ppath
, ppath_idx
,
ppath_key
,
ppath_component_retain
,
ppath_component_release
,
ppath_create
, ppath_length
,
ppath_component_idx
,
ppath_component_key
,
ppath_pop
, ppath_push
,
ppath_component_at
,
ppath_subpath
, ppath_push_idx
,
ppath_push_key
,
ppath_replace_idx
,
ppath_replace_key
, ppath_copy
,
ppath_retain
, ppath_release
,
ppath_lookup
—
#include <ppath/ppath.h>
ppath_component_t *
ppath_idx
(unsigned
int index);
ppath_component_t *
ppath_key
(const
char *key);
ppath_component_t *
ppath_component_retain
(ppath_component_t
*pc);
void
ppath_component_release
(ppath_component_t
*pc);
ppath_t *
ppath_create
(void);
unsigned int
ppath_length
(const
ppath_t *p);
int
ppath_component_idx
(const
ppath_component_t *);
const char *
ppath_component_key
(const
ppath_component_t *);
ppath_t *
ppath_pop
(ppath_t
*, ppath_component_t
**);
ppath_t *
ppath_push
(ppath_t
*, ppath_component_t
*);
ppath_component_t *
ppath_component_at
(const
ppath_t *, unsigned
int);
ppath_t *
ppath_subpath
(const
ppath_t *, unsigned
int, unsigned
int);
ppath_t *
ppath_push_idx
(ppath_t
*, unsigned
int);
ppath_t *
ppath_push_key
(ppath_t
*, const char
*);
ppath_t *
ppath_replace_idx
(ppath_t
*, unsigned
int);
ppath_t *
ppath_replace_key
(ppath_t
*, const char
*);
ppath_t *
ppath_copy
(const
ppath_t *);
ppath_t *
ppath_retain
(ppath_t
*);
void
ppath_release
(ppath_t
*);
prop_object_t
ppath_lookup
(prop_object_t,
const ppath_t *);
ppath
library provides functions to read, write, or
delete objects in a property list. A property-list “path” names
the object in a property list to read, write, or delete.
A property-list path is an ordered array of zero or more array
indices and dictionary keys that names at most one
prop_object_t in a property list. The abstract
function E
() evaluates a property-list path against
a prop_object_t, o, to yield a
prop_object_t result according to the following
recursive definition, where empty indicates the empty
(zero-length) path and the operator “|” indicates the
concatenation of the path on the left-hand side with the key or index on the
right-hand side:
E
(o,
empty)E
(o, p |
index)E
(o,
p) evaluates to a
prop_array_t, then
E
(o, p |
index) evaluates to the index 'th element of
that array. Otherwise, an error occurs.E
(o, p |
key)E
(o,
p) evaluates to a
prop_dictionary_t, then
E
(o, p |
key) evaluates to the dictionary value stored under
key. Otherwise, an error occurs.The programmer may think of property-list paths as working similarly to paths in a file system, where property arrays and dictionaries correspond to directories, and all other property types correspond to files.
ppath
provides two opaque types:
ppath
counts references to a
ppath_component_t and reclaims its storage when
there are no more references.ppath
counts references to a
ppath_t and reclaims its storage when there are no
more references.ppath
provides these functions for manipulating
property-list paths and their components:
ppath_idx
(unsigned int
index)If there is not sufficient memory to complete the request,
return NULL
.
ppath_key
(const char
*key)If there is not sufficient memory to complete the request,
return NULL
.
ppath_component_retain
(ppath_component_t
*pc)ppath_component_release
(ppath_component_t
*pc)ppath_create
(void)If there is not sufficient memory to complete the request,
return NULL
.
ppath_length
(const ppath_t
*p)ppath_component_idx
(const
ppath_component_t *pc)ppath_component_key
(const
ppath_component_t *pc)NULL
if
pc does not represent a dictionary key.ppath_pop
(ppath_t *p,
ppath_component_t **pcp)NULL
, return NULL
.
Otherwise, remove the last component from p and
return p, and if pcp is not
NULL
, write the removed component to
*pcp.ppath_push
(ppath_t *p,
ppath_component_t *pc)NULL
or no
more components can be added to p, return
NULL
. Otherwise, append pc
to the end of the component array p and return
p.ppath_component_at
(const ppath_t
*p, unsigned int i)NULL
or there
is no ith component to p,
return NULL
. Otherwise, return the
ith component of p. Before
returning a component, ppath_component_at
()
increases its reference count. (The first component is 0.)ppath_subpath
(const ppath_t
*p, unsigned int first, unsigned
int exclast)ppath_subpath
() returns
an empty ppath_t. If there is insufficient memory to
create the new path, or if p is
NULL
, return NULL
.
Otherwise, return the new path.ppath_push_idx
(ppath_t *p,
unsigned int idx)NULL
, or if there is insufficient memory to
complete the operation, return NULL
. Otherwise,
return p.ppath_push_key
(ppath_t *,
const char *key)NULL
, or if there is insufficient memory to
complete the operation, return NULL
. Otherwise,
return p.ppath_replace_idx
(ppath_t
*p, unsigned int idx)NULL
, if the last component of
p is not an array index, or if there is insufficient
memory to complete the operation, return NULL
.
Otherwise, return p.ppath_replace_key
(ppath_t
*p, const char *key)NULL
, if the last component of
p is not a dictionary key, or if there is
insufficient memory to complete the operation, return
NULL
. Otherwise, return
p.ppath_copy
(const ppath_t
*p)NULL
, or if there is insufficient memory to
complete the operation, return NULL
. Otherwise,
return the copy, whose reference count will be one.ppath_retain
(ppath_t
*p)ppath_release
(ppath_t
*p)ppath_lookup
(prop_object_t
o, const ppath_t *p)NULL
if no such
prop_object_t is under o.ppath
property container path library first appeared
in NetBSD 6.0.
August 24, 2011 | NetBSD 9.2 |