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