1.\"	$NetBSD: prop_copyin_ioctl.9,v 1.7 2009/12/14 05:47:30 dholland Exp $
2.\"
3.\" Copyright (c) 2006, 2009 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Jason R. Thorpe.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in the
16.\" documentation and/or other materials provided with the distribution.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE.
29.\"
30.Dd October 10, 2009
31.Dt PROP_COPYIN_IOCTL 9
32.Os
33.Sh NAME
34.Nm prop_array_copyin_ioctl ,
35.Nm prop_array_copyout_ioctl ,
36.Nm prop_array_copyin ,
37.Nm prop_dictionary_copyin_ioctl ,
38.Nm prop_dictionary_copyout_ioctl ,
39.Nm prop_dictionary_copyin
40.Nd Copy property lists to and from kernel space
41.Sh SYNOPSIS
42.In libprop/proplib.h
43.Ft int
44.Fn prop_array_copyin_ioctl "const struct plistref *pref" \
45    "const u_long cmd" "prop_array_t *arrayp"
46.Ft int
47.Fn prop_array_copyin "const struct plistref *pref" \
48    "prop_array_t *arrayp"
49.Ft int
50.Fn prop_array_copyout_ioctl "struct plistref *pref" \
51    "const u_long cmd" "prop_array_t array"
52.Ft int
53.Fn prop_dictionary_copyin_ioctl "const struct plistref *pref" \
54    "const u_long cmd" "prop_dictionary_t *dictp"
55.Ft int
56.Fn prop_dictionary_copyin "const struct plistref *pref" \
57    "prop_dictionary_t *dictp"
58.Ft int
59.Fn prop_dictionary_copyout_ioctl "struct plistref *pref" \
60    "const u_long cmd" "prop_dictionary_t dict"
61.Sh DESCRIPTION
62The
63.Nm prop_array_copyin_ioctl ,
64.Nm prop_array_copyout_ioctl ,
65.Nm prop_dictionary_copyin_ioctl ,
66and
67.Nm prop_dictionary_copyout_ioctl
68functions implement the kernel side of a protocol for copying property lists
69to and from the kernel using
70.Xr ioctl 2 .
71The functions
72.Nm prop_array_copyin
73and
74.Nm prop_dictionary_copyin
75implement the kernel side of a protocol for copying property lists to the
76kernel as arguments of normal system calls.
77.Pp
78A kernel routine receiving or returning a property list will be passed a
79pointer to a
80.Vt struct plistref .
81This structure encapsulates the reference to the property list in externalized
82form.
83.Sh RETURN VALUES
84If successful, functions return zero.
85Otherwise, an error number will be returned to indicate the error.
86.Sh EXAMPLES
87The following
88.Pq simplified
89example demonstrates using
90.Fn prop_dictionary_copyin_ioctl
91and
92.Fn prop_dictionary_copyout_ioctl
93in an ioctl routine:
94.Bd -literal
95extern prop_dictionary_t fooprops;
96
97int
98fooioctl(dev_t dev, u_long cmd, caddr_t data, int flag, struct lwp *l)
99{
100    prop_dictionary_t dict, odict;
101    int error;
102
103    switch (cmd) {
104    case FOOSETPROPS: {
105	const struct plistref *pref = (const struct plistref *) data;
106	error = prop_dictionary_copyin_ioctl(pref, cmd, \*[Am]dict);
107	if (error)
108		return (error);
109	odict = fooprops;
110	fooprops = dict;
111	prop_object_release(odict);
112	break;
113      }
114
115    case FOOGETPROPS: {
116	struct plistref *pref = (struct plistref *) data;
117	error = prop_dictionary_copyout_ioctl(pref, cmd, fooprops);
118	break;
119      }
120
121    default:
122	return (EPASSTHROUGH);
123    }
124    return (error);
125}
126.Ed
127.Pp
128The following
129.Pq simplified
130example demonstrates using
131.Fn prop_array_copyin
132in a routine:
133.Bd -literal
134int
135foocopyin(const struct plistref *pref))
136{
137    prop_array_t array;
138    int error;
139
140    error = prop_array_copyin(pref, \*[Am]array);
141    if (error)
142	    return (error);
143    ...
144}
145.Ed
146.Sh ERRORS
147.Fn prop_array_copyin_ioctl
148and
149.Fn prop_dictionary_copyin_ioctl
150will fail if:
151.Bl -tag -width Er
152.It Bq Er EFAULT
153Bad address
154.It Bq Er EIO
155Input/output error
156.It Bq Er ENOMEM
157Cannot allocate memory
158.It Bq Er ENOTSUP
159Not supported
160.El
161.Pp
162.Fn prop_array_copyout_ioctl
163and
164.Fn prop_dictionary_copyout_ioctl
165will fail if:
166.Bl -tag -width Er
167.It Bq Er EFAULT
168Bad address
169.It Bq Er ENOMEM
170Cannot allocate memory
171.It Bq Er ENOTSUP
172Not supported
173.El
174.Sh SEE ALSO
175.Xr prop_array 3 ,
176.Xr prop_dictionary 3 ,
177.Xr prop_send_ioctl 3 ,
178.Xr proplib 3
179.Sh HISTORY
180The
181.Nm proplib
182property container object library first appeared in
183.Nx 4.0 .
184