1.\" $NetBSD: prop_copyin_ioctl.9,v 1.8 2011/01/19 20:34:23 bouyer 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 January 17, 2011 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_array_copyout , 38.Nm prop_dictionary_copyin_ioctl , 39.Nm prop_dictionary_copyout_ioctl , 40.Nm prop_dictionary_copyin , 41.Nm prop_dictionary_copyout 42.Nd Copy property lists to and from kernel space 43.Sh SYNOPSIS 44.In libprop/proplib.h 45.Ft int 46.Fn prop_array_copyin_ioctl "const struct plistref *pref" \ 47 "const u_long cmd" "prop_array_t *arrayp" 48.Ft int 49.Fn prop_array_copyin "const struct plistref *pref" \ 50 "prop_array_t *arrayp" 51.Ft int 52.Fn prop_array_copyout_ioctl "struct plistref *pref" \ 53 "const u_long cmd" "prop_array_t array" 54.Ft int 55.Fn prop_array_copyout "struct plistref *pref" \ 56 "prop_array_t array" 57.Ft int 58.Fn prop_dictionary_copyin_ioctl "const struct plistref *pref" \ 59 "const u_long cmd" "prop_dictionary_t *dictp" 60.Ft int 61.Fn prop_dictionary_copyin "const struct plistref *pref" \ 62 "prop_dictionary_t *dictp" 63.Ft int 64.Fn prop_dictionary_copyout_ioctl "struct plistref *pref" \ 65 "const u_long cmd" "prop_dictionary_t dict" 66.Ft int 67.Fn prop_dictionary_copyout "struct plistref *pref" \ 68 "prop_dictionary_t dict" 69.Sh DESCRIPTION 70The 71.Nm prop_array_copyin_ioctl , 72.Nm prop_array_copyout_ioctl , 73.Nm prop_dictionary_copyin_ioctl , 74and 75.Nm prop_dictionary_copyout_ioctl 76functions implement the kernel side of a protocol for copying property lists 77to and from the kernel using 78.Xr ioctl 2 . 79The functions 80.Nm prop_array_copyin , 81.Nm prop_array_copyout , 82.Nm prop_dictionary_copyin , 83and 84.Nm prop_dictionary_copyout 85implement the kernel side of a protocol for copying property lists to the 86kernel as arguments of normal system calls. 87.Pp 88A kernel routine receiving or returning a property list will be passed a 89pointer to a 90.Vt struct plistref . 91This structure encapsulates the reference to the property list in externalized 92form. 93.Sh RETURN VALUES 94If successful, functions return zero. 95Otherwise, an error number will be returned to indicate the error. 96.Sh EXAMPLES 97The following 98.Pq simplified 99example demonstrates using 100.Fn prop_dictionary_copyin_ioctl 101and 102.Fn prop_dictionary_copyout_ioctl 103in an ioctl routine: 104.Bd -literal 105extern prop_dictionary_t fooprops; 106 107int 108fooioctl(dev_t dev, u_long cmd, caddr_t data, int flag, struct lwp *l) 109{ 110 prop_dictionary_t dict, odict; 111 int error; 112 113 switch (cmd) { 114 case FOOSETPROPS: { 115 const struct plistref *pref = (const struct plistref *) data; 116 error = prop_dictionary_copyin_ioctl(pref, cmd, \*[Am]dict); 117 if (error) 118 return (error); 119 odict = fooprops; 120 fooprops = dict; 121 prop_object_release(odict); 122 break; 123 } 124 125 case FOOGETPROPS: { 126 struct plistref *pref = (struct plistref *) data; 127 error = prop_dictionary_copyout_ioctl(pref, cmd, fooprops); 128 break; 129 } 130 131 default: 132 return (EPASSTHROUGH); 133 } 134 return (error); 135} 136.Ed 137.Pp 138The following 139.Pq simplified 140example demonstrates using 141.Fn prop_array_copyin 142in a routine: 143.Bd -literal 144int 145foocopyin(const struct plistref *pref)) 146{ 147 prop_array_t array; 148 int error; 149 150 error = prop_array_copyin(pref, \*[Am]array); 151 if (error) 152 return (error); 153 ... 154} 155.Ed 156.Sh ERRORS 157.Fn prop_array_copyin_ioctl 158and 159.Fn prop_dictionary_copyin_ioctl 160will fail if: 161.Bl -tag -width Er 162.It Bq Er EFAULT 163Bad address 164.It Bq Er EIO 165Input/output error 166.It Bq Er ENOMEM 167Cannot allocate memory 168.It Bq Er ENOTSUP 169Not supported 170.El 171.Pp 172.Fn prop_array_copyout_ioctl 173and 174.Fn prop_dictionary_copyout_ioctl 175will fail if: 176.Bl -tag -width Er 177.It Bq Er EFAULT 178Bad address 179.It Bq Er ENOMEM 180Cannot allocate memory 181.It Bq Er ENOTSUP 182Not supported 183.El 184.Sh SEE ALSO 185.Xr prop_array 3 , 186.Xr prop_dictionary 3 , 187.Xr prop_send_ioctl 3 , 188.Xr prop_send_syscall 3 , 189.Xr proplib 3 190.Sh HISTORY 191The 192.Nm proplib 193property container object library first appeared in 194.Nx 4.0 . 195