VND_PROP_ITER(3VND) VND_PROP_ITER(3VND)

NAME

vnd_prop_iter - iterate vnd properties

SYNOPSIS

cc [ flag... ] file... -lvnd [ library... ]
#include <libvnd.h>

typedef int (vnd_prop_iter_f)(vnd_handle_t *vhp, vnd_prop_t prop,
void *cbarg);

int vnd_prop_iter(vnd_handle_t *vhp, vnd_prop_iter_f cb,
void *arg);

DESCRIPTION

The vnd_prop_iter function iterates over all the available properties for
the vnd handle vhp and calls the user supplied callback function cb. The
argument arg is passed directly to the callback function.


The function specified by cb receives three arguments. The first, vhp, is
the same vnd library handle that was passed to vnd_prop_iter. During the
callback, the consumer should not call vnd_close(3VND). Doing so will
lead to undefined and undocumented behavior. The second argument, prop,
is the current property. While vnd_prop_iter guarantees that all
properties will be recieved, it does not guarantee the order of them.
The final argument, cbarg, is the same argument that the caller passed in
during arg.


The return value of the callback function cb indicates whether or not
property iteration should continue. To continue iteration, the function
cb should return zero. Otherwise, to stop property iteration it should
return non-zero.

RETURN VALUES

On success, the function vnd_prop_iter returns zero. If the callback
function returned non-zero to terminate iteration, vnd_prop_iter will
instead return one. In the case of library failure, vnd_prop_iter will
return -1. In such cases, the vnd and system errors will be updated and
available via vnd_errno(3VND) and vnd_syserrno(3VND).

EXAMPLES

Example 1 Print writeable properties


The following sample C program walks over every vnd property and prints
out whether the property is read-only or read-write for the vnd device
"vnd1" in the current zone.


#include <libvnd.h>
#include <stdlib.h>
#include <stdio.h>

static int
print_prop(vnd_handle_t *vhp, vnd_prop_t prop, void *unused)
{
boolean_t canwrite;

if (vnd_prop_writeable(vhp, &canwrite) != 0)
abort();

(void) printf("prop %d is %s", prop, canwrite == B_TRUE ? "rw" : "r-");
return (0);
}

int
main(void)
{
vnd_handle_t *vhp;
vnd_errno_t vnderr;
int syserr;

vhp = vnd_open(NULL, "vnd1", &vnderr, &syserr);
if (vhp != NULL) {
if (vnderr == VND_E_SYS)
(void) fprintf(stderr, "failed to open device: %s",
vnd_strsyserror(syserr));
else
(void) fprintf(stderr, "failed to open device: %s",
vnd_strerror(vnderr));
return (1);
}

if (vnd_prop_iter(vhp, print_prop, NULL) != 0) {
vnderr = vnd_errno(vhp);
syserr = vnd_syserrno(vhp);
if (vnderr == VND_E_SYS)
(void) fprintf(stderr, "failed to open device: %s",
vnd_strsyserror(syserr));
else
(void) fprintf(stderr, "failed to open device: %s",
vnd_strerror(vnderr));
return (1);
}

vnd_close(vnd);
return (0);
}

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:


+---------------+---------------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+---------------------------------+
|Stability | Committed |
+---------------+---------------------------------+
|MT-Level | See "THREADING" in libvnd(3LIB) |
+---------------+---------------------------------+
libvnd(3LIB), vnd_close(3VND), vnd_errno(3VND), vnd_syserrno(3VND)

February 21, 2014 VND_PROP_ITER(3VND)