1.\" $NetBSD: prop_copyin_ioctl.9,v 1.12 2017/01/29 01:38:02 pgoyette 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 29, 2017 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 prop/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_ioctl_size "const struct plistref *pref" \ 50 "const u_long cmd" "prop_array_t *arrayp" "size_t lim" 51.Ft int 52.Fn prop_array_copyin "const struct plistref *pref" \ 53 "prop_array_t *arrayp" 54.Ft int 55.Fn prop_array_copyin_size "const struct plistref *pref" \ 56 "prop_array_t *arrayp" "size_t lim" 57.Ft int 58.Fn prop_array_copyout_ioctl "struct plistref *pref" \ 59 "const u_long cmd" "prop_array_t array" 60.Ft int 61.Fn prop_array_copyout "struct plistref *pref" \ 62 "prop_array_t array" 63.Ft int 64.Fn prop_dictionary_copyin_ioctl "const struct plistref *pref" \ 65 "const u_long cmd" "prop_dictionary_t *dictp" 66.Ft int 67.Fn prop_dictionary_copyin_ioctl_size "const struct plistref *pref" \ 68 "const u_long cmd" "prop_dictionary_t *dictp" "size_t lim" 69.Ft int 70.Fn prop_dictionary_copyin "const struct plistref *pref" \ 71 "prop_dictionary_t *dictp" 72.Ft int 73.Fn prop_dictionary_copyin_size "const struct plistref *pref" \ 74 "prop_dictionary_t *dictp" "size_t lim" 75.Ft int 76.Fn prop_dictionary_copyout_ioctl "struct plistref *pref" \ 77 "const u_long cmd" "prop_dictionary_t dict" 78.Ft int 79.Fn prop_dictionary_copyout "struct plistref *pref" \ 80 "prop_dictionary_t dict" 81.Sh DESCRIPTION 82The 83.Nm prop_array_ioctl , 84.Nm prop_array_copyin_ioctl , 85.Nm prop_array_copyin_ioctl_size , 86.Nm prop_array_copyout_ioctl , 87.Nm prop_dictionary_copyin_ioctl , 88.Nm prop_dictionary_copyin_ioctl_size , 89and 90.Nm prop_dictionary_copyout_ioctl 91functions implement the kernel side of a protocol for copying property lists 92to and from the kernel using 93.Xr ioctl 2 . 94The functions 95.Nm prop_array_copyin , 96.Nm prop_array_copyin_size , 97.Nm prop_array_copyout , 98.Nm prop_dictionary_copyin , 99.Nm prop_dictionary_copyin_size , 100and 101.Nm prop_dictionary_copyout 102implement the kernel side of a protocol for copying property lists to the 103kernel as arguments of normal system calls. 104.Pp 105A kernel routine receiving or returning a property list will be passed a 106pointer to a 107.Vt struct plistref . 108This structure encapsulates the reference to the property list in externalized 109form. 110.Pp 111The functions 112.Nm prop_array_copyin_ioctl_size , 113.Nm prop_dictionary_copyin_ioctl_size , 114.Nm prop_array_copyin_size , 115and 116.Nm prop_dictionary_copyin_size , 117take an explicit limit argument 118.Ar lim 119while 120.Nm prop_array_copyin_ioctl , 121.Nm prop_dictionary_copyin_ioctl , 122.Nm prop_array_copyin , 123and 124.Nm prop_dictionary_copyin , 125have an implicit size limit of 128KB. 126Attempts to transfer objects larger than the limit result in an 127.Er E2BIG 128return value. 129.Sh RETURN VALUES 130If successful, functions return zero. 131Otherwise, an error number will be returned to indicate the error. 132.Sh EXAMPLES 133The following 134.Pq simplified 135example demonstrates using 136.Fn prop_dictionary_copyin_ioctl 137and 138.Fn prop_dictionary_copyout_ioctl 139in an ioctl routine: 140.Bd -literal 141extern prop_dictionary_t fooprops; 142 143int 144fooioctl(dev_t dev, u_long cmd, caddr_t data, int flag, struct lwp *l) 145{ 146 prop_dictionary_t dict, odict; 147 int error; 148 149 switch (cmd) { 150 case FOOSETPROPS: { 151 const struct plistref *pref = (const struct plistref *) data; 152 error = prop_dictionary_copyin_ioctl(pref, cmd, \*[Am]dict); 153 if (error) 154 return (error); 155 odict = fooprops; 156 fooprops = dict; 157 prop_object_release(odict); 158 break; 159 } 160 161 case FOOGETPROPS: { 162 struct plistref *pref = (struct plistref *) data; 163 error = prop_dictionary_copyout_ioctl(pref, cmd, fooprops); 164 break; 165 } 166 167 default: 168 return (EPASSTHROUGH); 169 } 170 return (error); 171} 172.Ed 173.Pp 174The following 175.Pq simplified 176example demonstrates using 177.Fn prop_array_copyin 178in a routine: 179.Bd -literal 180int 181foocopyin(const struct plistref *pref)) 182{ 183 prop_array_t array; 184 int error; 185 186 error = prop_array_copyin(pref, \*[Am]array); 187 if (error) 188 return (error); 189 ... 190} 191.Ed 192.Sh ERRORS 193.Fn prop_array_copyin_ioctl 194and 195.Fn prop_dictionary_copyin_ioctl 196will fail if: 197.Bl -tag -width Er 198.It Bq Er E2BIG 199The object being copied is larger than an arbitrarily established limit 200(currently set to 128Kbytes). 201.It Bq Er EFAULT 202Bad address 203.It Bq Er EIO 204Input/output error 205.It Bq Er ENOMEM 206Cannot allocate memory 207.It Bq Er ENOTSUP 208Not supported 209.El 210.Pp 211.Fn prop_array_copyout_ioctl 212and 213.Fn prop_dictionary_copyout_ioctl 214will fail if: 215.Bl -tag -width Er 216.It Bq Er EFAULT 217Bad address 218.It Bq Er ENOMEM 219Cannot allocate memory 220.It Bq Er ENOTSUP 221Not supported 222.El 223.Sh SEE ALSO 224.Xr prop_array 3 , 225.Xr prop_dictionary 3 , 226.Xr prop_send_ioctl 3 , 227.Xr prop_send_syscall 3 , 228.Xr proplib 3 229.Sh HISTORY 230The 231.Nm proplib 232property container object library first appeared in 233.Nx 4.0 . 234