ppath_length man page on NetBSD

Man page or keyword search:  
man Server   9087 pages
apropos Keyword Search (all sections)
Output format
NetBSD logo
[printable version]

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 container 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() evaluates a property-list path against a
     prop_object_t, o, to yield a prop_object_t result according to the fol‐
     lowing 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 system, where property arrays and dictionaries correspond
     to directories, and all other property 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 references 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 references to a ppath_t and reclaims its
		      storage when there are no more references.

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 reference 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 represent 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 insuffi‐
	    cient 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 opera‐
	    tion, 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 dictio‐
	    nary 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 insuffi‐
	    cient memory to complete 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
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server NetBSD

List of man pages available for NetBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net