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