prop_array_copy_mutable man page on DragonFly

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

PROP_ARRAY(3)		 BSD Library Functions Manual		 PROP_ARRAY(3)

NAME
     prop_array, prop_array_create, prop_array_create_with_capacity,
     prop_array_copy, prop_array_copy_mutable, prop_array_capacity,
     prop_array_count, prop_array_ensure_capacity, prop_array_iterator,
     prop_array_make_immutable, prop_array_mutable, prop_array_get,
     prop_array_set, prop_array_add, prop_array_remove,
     prop_array_externalize, prop_array_internalize,
     prop_array_externalize_to_file, prop_array_internalize_from_file,
     prop_array_externalize_to_pref, prop_array_equals — array property col‐
     lection object

LIBRARY
     library “libprop”

SYNOPSIS
     #include <libprop/proplib.h>

     prop_array_t
     prop_array_create(void);

     prop_array_t
     prop_array_create_with_capacity(unsigned int capacity);

     prop_array_t
     prop_array_copy(prop_array_t array);

     prop_array_t
     prop_array_copy_mutable(prop_array_t array);

     unsigned int
     prop_array_capacity(prop_array_t array);

     unsigned int
     prop_array_count(prop_array_t array);

     bool
     prop_array_ensure_capacity(prop_array_t array, unsigned int capacity);

     prop_object_iterator_t
     prop_array_iterator(prop_array_t array);

     void
     prop_array_make_immutable(prop_array_t array);

     bool
     prop_array_mutable(prop_array_t array);

     prop_object_t
     prop_array_get(prop_array_t array, unsigned int index);

     bool
     prop_array_set(prop_array_t array, unsigned int index,
	 prop_object_t obj);

     bool
     prop_array_add(prop_array_t array, prop_object_t obj);

     void
     prop_array_remove(prop_array_t array, unsigned int index);

     char *
     prop_array_externalize(prop_array_t array);

     prop_array_t
     prop_array_internalize(const char *xml);

     bool
     prop_array_externalize_to_file(prop_array_t array, const char *path);

     prop_array_t
     prop_array_internalize_from_file(const char *path);

     bool
     prop_array_externalize_to_pref(prop_array_t array,
	 struct plistref *pref);

     bool
     prop_array_equals(prop_array_t array1, prop_array_t array2);

DESCRIPTION
     The prop_array family of functions operate on the array property collec‐
     tion object type.	An array is an ordered set; an iterated array will
     return objects in the same order with which they were stored.

     prop_array_create(void)
	    Create an empty array.  The array initially has no capacity.
	    Returns NULL on failure.

     prop_array_create_with_capacity(unsigned int capacity)
	    Create an array with the capacity to store capacity objects.
	    Returns NULL on failure.

     prop_array_copy(prop_array_t array)
	    Copy an array.  The new array has an initial capacity equal to the
	    number of objects stored in the array being copied.	 The new array
	    contains references to the original array's objects, not copies of
	    those objects (i.e. a shallow copy is made).  If the original
	    array is immutable, the resulting array is also immutable.
	    Returns NULL on failure.

     prop_array_copy_mutable(prop_array_t array)
	    Like prop_array_copy(), except the resulting array is always muta‐
	    ble.

     prop_array_capacity(prop_array_t array)
	    Returns the total capacity of the array, including objects already
	    stored in the array.  If the supplied object isn't an array, zero
	    is returned.

     prop_array_count(prop_array_t array)
	    Returns the number of objects stored in the array.	If the sup‐
	    plied object isn't an array, zero is returned.

     prop_array_ensure_capacity(prop_array_t array, unsigned int capacity)
	    Ensure that the array has a total capacity of capacity, including
	    objects already stored in the array.  Returns true if the capacity
	    of the array is greater or equal to capacity or if expansion of
	    the array's capacity was successful and false otherwise.

     prop_array_iterator(prop_array_t array)
	    Create an iterator for the array.  The array is retained by the
	    iterator.  An array iterator returns the object references stored
	    in the array.  Storing to or removing from the array invalidates
	    any active iterators for the array.	 Returns NULL on failure.

     prop_array_make_immutable(prop_array_t array)
	    Make array immutable.

     prop_array_mutable(prop_array_t array)
	    Returns true if the array is mutable.

     prop_array_get(prop_array_t array, unsigned int index)
	    Return the object stored at the array index index.	Returns NULL
	    on failure.

     prop_array_set(prop_array_t array, unsigned int index, prop_object_t obj)
	    Store a reference to the object obj at the array index index.
	    This function is not allowed to create holes in the array; the
	    caller must either be setting the object just beyond the existing
	    count or replacing an already existing object reference.  The
	    object will be retained by the array.  If an existing object ref‐
	    erence is being replaced, that object will be released.  Returns
	    true if storing the object was successful and false otherwise.

     prop_array_add(prop_array_t array, prop_object_t obj)
	    Add a reference to the object obj to the array, appending to the
	    end and growing the array's capacity if necessary.	The object
	    will be retained by the array.  Returns true if storing the object
	    was successful and false otherwise.

	    During expansion, array's capacity is augmented by the EXPAND_STEP
	    constant, as defined in libprop/prop_array.c file, e.g.

		  #define   EXPAND_STEP		16

     prop_array_remove(prop_array_t array, unsigned int index)
	    Remove the reference to the object stored at array index index.
	    The object will be released and the array compacted following the
	    removal.

     prop_array_externalize(prop_array_t array)
	    Externalizes an array, returning a NUL-terminated buffer contain‐
	    ing the XML representation of the array.  The caller is responsi‐
	    ble for freeing the returned buffer.  If converting to the exter‐
	    nal representation fails for any reason, NULL is returned.

	    In user space, the buffer is allocated using malloc(3).  In the
	    kernel, the buffer is allocated using malloc(9) using the malloc
	    type M_TEMP.

     prop_array_internalize(const char *xml)
	    Parse the XML representation of a property list in the NUL-termi‐
	    nated buffer xml and return the corresponding array.  Returns NULL
	    if parsing fails for any reason.

     prop_array_externalize_to_file(prop_array_t array, const char *path)
	    Externalizes an array and writes it to the file specified by path.
	    The file is saved with the mode 0666 as modified by the process's
	    file creation mask (see umask(2)) and is written atomically.
	    Returns false if externalizing or writing the array fails for any
	    reason.

     prop_array_internalize_from_file(const char *path)
	    Reads the XML property list contained in the file specified by
	    path, internalizes it, and returns the corresponding array.
	    Returns NULL on failure.

     prop_array_externalize_to_pref(prop_array_t array, struct plistref *pref)
	    Externalizes an array and packs it into the plistref specified by
	    pref.  Returns false if externalizing the array fails for any rea‐
	    son.

     prop_array_equals(prop_array_t array1, prop_array_t array2)
	    Returns true if the two arrays are equivalent.  If at least one of
	    the supplied objects isn't an array, false is returned.  Note:
	    Objects contained in the array are compared by value, not by ref‐
	    erence.

SEE ALSO
     prop_bool(3), prop_data(3), prop_dictionary(3), prop_number(3),
     prop_object(3), prop_string(3), proplib(3)

HISTORY
     The proplib property container object library first appeared in
     NetBSD 4.0.

BSD			       October 10, 2009				   BSD
[top]

List of man pages available for DragonFly

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