👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

NetBSD 6.1.5 - man page for ppath_copy (netbsd section 3)

PPATH(3)			   BSD Library Functions Manual 			 PPATH(3)

NAME
     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, -- property con-
     tainer path library

LIBRARY
     library ``libppath''

SYNOPSIS
     #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 *);

DESCRIPTION
     The 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() evalu-
     ates 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)      Evaluates to o.

     E(o, p | index)  If 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)    If 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 sys-
     tem, where property arrays and dictionaries correspond to directories, and all other prop-
     erty types correspond to files.

DATA TYPES
     ppath provides two opaque types:

     ppath_component_t
		      A property-list path component: a single key or index.  ppath counts refer-
		      ences to a ppath_component_t and reclaims its storage when there are no
		      more references.

     ppath_t	      An array of zero or more property-list path components.  ppath counts ref-
		      erences to a ppath_t and reclaims its storage when there are no more refer-
		      ences.

FUNCTIONS
     ppath provides these functions for manipulating property-list paths and their components:

     ppath_idx(unsigned int index)
	    Allocate a new ppath_component_t for the given array index and return it.  Its refer-
	    ence count is initially one.

	    If there is not sufficient memory to complete the request, return NULL.

     ppath_key(const char *key)
	    Allocate a new ppath_component_t for the given dictionary key and return it.  Its
	    reference count is initially one.

	    If there is not sufficient memory to complete the request, return NULL.

     ppath_component_retain(ppath_component_t *pc)
	    Increase the reference count on pc by one.

     ppath_component_release(ppath_component_t *pc)
	    Decrease the reference count on pc by one.	If the reference count reaches zero,
	    reclaim the storage for pc.

     ppath_create(void)
	    Create a new property-list path and return it.  Its reference count is initially one.
	    The path's length is initially zero.

	    If there is not sufficient memory to complete the request, return NULL.

     ppath_length(const ppath_t *p)
	    Return the number of components in path p.

     ppath_component_idx(const ppath_component_t *pc)
	    Return the array index represented by the component pc, or -1 if pc does not repre-
	    sent an array index.

     ppath_component_key(const ppath_component_t *pc)
	    Return the dictionary key represented by the component pc, or NULL if pc does not
	    represent a dictionary key.

     ppath_pop(ppath_t *p, ppath_component_t **pcp)
	    If p is the empty path or 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)
	    If either p is 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)
	    If either p is 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)
	    Create a new ppath_t and fill it with components first to exclast (exclusive) of p.
	    If there are no such components as those in p, 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)
	    Append an array index, idx, to the end of path p.  If p is NULL, or if there is
	    insufficient memory to complete the operation, return NULL.  Otherwise, return p.

     ppath_push_key(ppath_t *, const char *key)
	    Append a dictionary key, key, to the end of path p.  If p is 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)
	    Replace the array index at the end of path p with the array index idx.  If p is 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)
	    Replace the dictionary key at the end of path p with the dictionary key idx.  If p is
	    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)
	    Create a copy of path p.  If p is NULL, or if there is insufficient memory to com-
	    plete the operation, return NULL.  Otherwise, return the copy, whose reference count
	    will be one.

     ppath_retain(ppath_t *p)
	    Increase the reference count on p and return p.

     ppath_release(ppath_t *p)
	    Decrease the reference count on p.	Reclaim the storage for p if the reference count
	    reaches zero.

     ppath_lookup(prop_object_t o, const ppath_t *p)
	    Return the prop_object_t under o named by p, or return NULL if no such prop_object_t
	    is under o.

SEE ALSO
     ppath_bool(3), ppath_data(3), ppath_number(3), ppath_object(3), ppath_string(3), proplib(3)

HISTORY
     The ppath property container path library first appeared in NetBSD 6.0.

AUTHORS
     David Young <dyoung@pobox.com>

BSD					 August 24, 2011				      BSD


All times are GMT -4. The time now is 05:18 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password