PPATH_OBJECT(3) | Library Functions Manual | PPATH_OBJECT(3)

# NAME

`ppath_object`, `ppath_copydel_object`, `ppath_copyset_object`, `ppath_set_object`, `ppath_get_object`, `ppath_delete_object`, `ppath_copydel_data`, `ppath_copyset_data`, `ppath_set_data`, `ppath_get_data`, `ppath_dup_data`, `ppath_delete_data`, `ppath_copydel_string`, `ppath_copyset_string`, `ppath_set_string`, `ppath_get_string`, `ppath_dup_string`, `ppath_delete_string` —
property object path operations

# LIBRARY

Property-List Paths Library (libppath, -lppath)

# SYNOPSIS

`#include <ppath/ppath.h>`

int
`ppath_copydel_object`(prop_object_t, prop_object_t *, const ppath_t *);

int
`ppath_copyset_object`(prop_object_t, prop_object_t *, const ppath_t *, prop_object_t);

int
`ppath_set_object`(prop_object_t, const ppath_t *, prop_object_t);

int
`ppath_get_object`(prop_object_t, const ppath_t *, prop_object_t *);

int
`ppath_delete_object`(prop_object_t, const ppath_t *);

int
`ppath_copydel_data`(prop_object_t, prop_object_t *, const ppath_t *);

int
`ppath_copyset_data`(prop_object_t, prop_object_t *, const ppath_t *, const void *, size_t);

int
`ppath_set_data`(prop_object_t, const ppath_t *, const void *, size_t);

int
`ppath_get_data`(prop_object_t, const ppath_t *, const void **, size_t *);

int
`ppath_dup_data`(prop_object_t, const ppath_t *, void **, size_t *);

int
`ppath_delete_data`(prop_object_t, const ppath_t *);

int
`ppath_copydel_string`(prop_object_t, prop_object_t *, const ppath_t *);

int
`ppath_copyset_string`(prop_object_t, prop_object_t *, const ppath_t *, const char *);

int
`ppath_set_string`(prop_object_t, const ppath_t *, const char *);

int
`ppath_get_string`(prop_object_t, const ppath_t *, const char **);

int
`ppath_dup_string`(prop_object_t, const ppath_t *, char **);

int
`ppath_delete_string`(prop_object_t, const ppath_t *);

# DESCRIPTION

The `ppath_object` routines read, write, or delete objects in a property list by path.

# FUNCTIONS

`ppath_object` provides these functions for manipulating objects in a property list by the objects' paths:

`ppath_copydel_object`(prop_object_t o, prop_object_t *op, const ppath_t *p)
  Create a copy of the property list o at *op. Delete from the copy the property named by p.

  If *op is `NULL`, `ppath_copydel_object`() creates a shallow copy of o at *op. If *op is not `NULL`, `ppath_copydel_object`() expects for *op to be an existing shallow copy of o.

  For the purposes of `ppath_copydel_object`(), *op is a shallow copy of property list o if equal properties at equal paths are shared between the two. Before `ppath_copydel_object`() modifies a property shared by *op and o, it creates a private copy of the property for *op.

`ppath_copyset_object`(prop_object_t o, prop_object_t *op, const ppath_t *p, prop_object_t v)
  Create a copy of the property list o at *op. In the copy, replace with v the property named by p.

  If *op is `NULL`, `ppath_copyset_object`() creates a shallow copy of o at *op. If *op is not `NULL`, `ppath_copyset_object`() expects for *op to be an existing shallow copy of o.

  For the purposes of `ppath_copyset_object`(), *op is a shallow copy of property list o if equal properties at equal paths are shared between the two. Before `ppath_copydel_object`() modifies a property shared by *op and o, it creates a private copy of the property for *op.

`ppath_set_object`(prop_object_t o, const ppath_t *p, prop_object_t v)
  Replace with v the prop_object_t in o named by p.
`ppath_get_object`(prop_object_t o, const ppath_t *p, prop_object_t *vp)
  Retrieve the prop_object_t named by p from o, and write it to *vp. `ppath_get_object`() does not increase the reference count of the retrieved object.
`ppath_delete_object`(prop_object_t o, const ppath_t *p)
  Delete the prop_object_t named by p from o. `ppath_delete_object`() decreases by one the deleted object's reference count.

# RETURN VALUES

`ppath_object` routines return 0 on success, and non-zero on error.

# ERRORS

[`EFTYPE`]
  The `ppath_object` call requested a
[`ENOENT`]
  `ppath_copyset_object`(), `ppath_delete_object`(), `ppath_get_object`(), and `ppath_set_object`() return `ENOENT` if the path p does not exist in o.
[`ENOMEM`]
  `ppath_set_object`() and `ppath_copyset_object`() will return `ENOMEM` if there was insufficient memory to complete the operation.

# SEE ALSO

ppath(3), ppath_number(3), proplib(3)

# HISTORY

The `ppath_object` property container path library first appeared in NetBSD 6.0.

# AUTHORS

David Young ⟨dyoung@pobox.com⟩

August 24, 2011 | NetBSD 9.2