1.\" $NetBSD: prop_copyin_ioctl.9,v 1.4 2008/04/30 13:10:46 martin Exp $ 2.\" 3.\" Copyright (c) 2006 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 25, 2006 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_dictionary_copyin_ioctl , 37.Nm prop_dictionary_copyout_ioctl 38.Nd Copy property lists to and from kernel space 39.Sh SYNOPSIS 40.In prop/proplib.h 41.Ft int 42.Fn prop_array_copyin_ioctl "const struct plistref *pref" \ 43 "const u_long cmd" "prop_array_t *arrayp" 44.Ft int 45.Fn prop_array_copyout_ioctl "struct plistref *pref" \ 46 "const u_long cmd" "prop_array_t array" 47.Ft int 48.Fn prop_dictionary_copyin_ioctl "const struct plistref *pref" \ 49 "const u_long cmd" "prop_dictionary_t *dictp" 50.Ft int 51.Fn prop_dictionary_copyout_ioctl "struct plistref *pref" \ 52 "const u_long cmd" "prop_dictionary_t dict" 53.Sh DESCRIPTION 54The 55.Nm prop_array_copyin_ioctl , 56.Nm prop_array_copyout_ioctl , 57.Nm prop_dictionary_copyin_ioctl , 58and 59.Nm prop_dictionary_copyout_ioctl 60functions implement the kernel side of a protocol for sending property lists 61to and from the kernel using 62.Xr ioctl 2 . 63.Pp 64A kernel ioctl routine receiving or returning a property list will be passed a 65pointer to a 66.Vt struct plistref . 67This structure encapsulates the reference to the property list in externalized 68form. 69.Sh RETURN VALUES 70If successful, functions return zero. Otherwise, an error number will be returned to indicate the error. 71.Sh ERRORS 72.Fn prop_array_copyin_ioctl 73and 74.Fn prop_dictionary_copyin_ioctl 75will fail if: 76.Bl -tag -width Er 77.It Bq Er EFAULT 78Bad address 79.It Bq Er EIO 80Input/output error 81.It Bq Er ENOMEM 82Cannot allocate memory 83.It Bq Er ENOTSUP 84Not supported 85.El 86.Pp 87.Fn prop_array_copyout_ioctl 88and 89.Fn prop_dictionary_copyout_ioctl 90will fail if: 91.Bl -tag -width Er 92.It Bq Er EFAULT 93Bad address 94.It Bq Er ENOMEM 95Cannot allocate memory 96.It Bq Er ENOTSUP 97Not supported 98.El 99.Sh EXAMPLES 100The following 101.Pq simplified 102example demonstrates using 103.Fn prop_dictionary_copyin_ioctl 104and 105.Fn prop_dictionary_copyout_ioctl 106in an ioctl routine: 107.Bd -literal 108extern prop_dictionary_t fooprops; 109 110int 111fooioctl(dev_t dev, u_long cmd, caddr_t data, int flag, struct lwp *l) 112{ 113 prop_dictionary_t dict, odict; 114 int error; 115 116 switch (cmd) { 117 case FOOSETPROPS: { 118 const struct plistref *pref = (const struct plistref *) data; 119 error = prop_dictionary_copyin_ioctl(pref, cmd, \*[Am]dict); 120 if (error) 121 return (error); 122 odict = fooprops; 123 fooprops = dict; 124 prop_object_release(odict); 125 break; 126 } 127 128 case FOOGETPROPS: { 129 struct plistref *pref = (struct plistref *) data; 130 error = prop_dictionary_copyout_ioctl(pref, cmd, fooprops); 131 break; 132 } 133 134 default: 135 return (EPASSTHROUGH); 136 } 137 return (error); 138} 139.Ed 140.Sh SEE ALSO 141.Xr prop_array 3 , 142.Xr prop_dictionary 3 , 143.Xr prop_send_ioctl 3 , 144.Xr proplib 3 145.Sh HISTORY 146The 147.Nm proplib 148property container object library first appeared in 149.Nx 4.0 . 150