PROP_COPYIN_IOCTL(9)

PROP_COPYIN_IOCTL(9) | Kernel Developer's Manual | PROP_COPYIN_IOCTL(9)

# NAME

`prop_array_copyin`, `prop_array_copyin_size`, `prop_array_copyin_ioctl`, `prop_array_copyin_ioctl_size`, `prop_array_copyout`, `prop_array_copyout_ioctl`, `prop_dictionary_copyin`, `prop_dictionary_copyin_size`, `prop_dictionary_copyin_ioctl`, `prop_dictionary_copyin_ioctl_size`, `prop_dictionary_copyout`, `prop_dictionary_copyout_ioctl` —
Copy property lists to and from kernel space

# SYNOPSIS

`#include <prop/proplib.h>`

int
`prop_array_copyin`(const struct plistref *pref, prop_array_t *arrayp);

int
`prop_array_copyin_size`(const struct plistref *pref, prop_array_t *arrayp, size_t lim);

int
`prop_array_copyin_ioctl`(const struct plistref *pref, const u_long cmd, prop_array_t *arrayp);

int
`prop_array_copyin_ioctl_size`(const struct plistref *pref, const u_long cmd, prop_array_t *arrayp, size_t lim);

int
`prop_array_copyout`(struct plistref *pref, prop_array_t array);

int
`prop_array_copyout_ioctl`(struct plistref *pref, const u_long cmd, prop_array_t array);

int
`prop_dictionary_copyin`(const struct plistref *pref, prop_dictionary_t *dictp);

int
`prop_dictionary_copyin_size`(const struct plistref *pref, prop_dictionary_t *dictp, size_t lim);

int
`prop_dictionary_copyin_ioctl`(const struct plistref *pref, const u_long cmd, prop_dictionary_t *dictp);

int
`prop_dictionary_copyin_ioctl_size`(const struct plistref *pref, const u_long cmd, prop_dictionary_t *dictp, size_t lim);

int
`prop_dictionary_copyout`(struct plistref *pref, prop_dictionary_t dict);

int
`prop_dictionary_copyout_ioctl`(struct plistref *pref, const u_long cmd, prop_dictionary_t dict);

# DESCRIPTION

The `prop_array_copyin_ioctl`, `prop_array_copyin_ioctl_size`, `prop_array_copyout_ioctl`, `prop_dictionary_copyin_ioctl`, `prop_dictionary_copyin_ioctl_size`, and `prop_dictionary_copyout_ioctl` functions implement the kernel side of a protocol for copying property lists to and from the kernel using ioctl(2). The functions `prop_array_copyin`, `prop_array_copyin_size`, `prop_array_copyout`, `prop_dictionary_copyin`, `prop_dictionary_copyin_size`, and `prop_dictionary_copyout` implement the kernel side of a protocol for copying property lists to the kernel as arguments of normal system calls.

A kernel routine receiving or returning a property list will be passed a pointer to a struct plistref. This structure encapsulates the reference to the property list in externalized form.

The functions `prop_array_copyin_size`, `prop_array_copyin_ioctl_size`, `prop_dictionary_copyin_size`, and `prop_dictionary_copyin_ioctl_size` take an explicit limit argument lim while `prop_array_copyin`, `prop_array_copyin_ioctl`, `prop_dictionary_copyin`, and `prop_dictionary_copyin_ioctl` have an implicit size limit of 128KB. Attempts to transfer objects larger than the limit result in an `E2BIG` return value.

# RETURN VALUES

If successful, functions return zero. Otherwise, an error number will be returned to indicate the error.

# EXAMPLES

The following (simplified) example demonstrates using `prop_dictionary_copyin_ioctl`() and `prop_dictionary_copyout_ioctl`() in an ioctl routine:

    extern prop_dictionary_t fooprops;

    int
    fooioctl(dev_t dev, u_long cmd, caddr_t data, int flag, struct lwp *l)
    {
        prop_dictionary_t dict, odict;
        int error;

        switch (cmd) {
        case FOOSETPROPS: {
    	const struct plistref *pref = (const struct plistref *) data;
    	error = prop_dictionary_copyin_ioctl(pref, cmd, &dict);
    	if (error)
    		return (error);
    	odict = fooprops;
    	fooprops = dict;
    	prop_object_release(odict);
    	break;
          }

        case FOOGETPROPS: {
    	struct plistref *pref = (struct plistref *) data;
    	error = prop_dictionary_copyout_ioctl(pref, cmd, fooprops);
    	break;
          }

        default:
    	return (EPASSTHROUGH);
        }
        return (error);
    }

The following (simplified) example demonstrates using `prop_array_copyin`() in a routine:

    int
    foocopyin(const struct plistref *pref))
    {
        prop_array_t array;
        int error;

        error = prop_array_copyin(pref, &array);
        if (error)
    	    return (error);
        ...
    }

# ERRORS

`prop_array_copyin_ioctl`() and `prop_dictionary_copyin_ioctl`() will fail if:

[`E2BIG`]
  The object being copied is larger than an arbitrarily established limit (currently set to 128Kbytes).
[`EFAULT`]
  Bad address
[`EIO`]
  Input/output error
[`ENOMEM`]
  Cannot allocate memory
[`ENOTSUP`]
  Not supported

`prop_array_copyout_ioctl`() and `prop_dictionary_copyout_ioctl`() will fail if:

[`EFAULT`]
  Bad address
[`ENOMEM`]
  Cannot allocate memory
[`ENOTSUP`]
  Not supported

# SEE ALSO

prop_array(3), prop_dictionary(3), prop_send_ioctl(3), prop_send_syscall(3), proplib(3)

# HISTORY

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

January 29, 2017 | NetBSD 9.3