Sun Jan 29 01:38:02 2017 UTC ()
Update for the new *_size() functions recently added.  Mention the
implicit size limit (128KB) for the functions which do not take an
explicit limit argument.


(pgoyette)
diff -r1.11 -r1.12 src/common/lib/libprop/prop_copyin_ioctl.9
cvs diff -r1.11 -r1.12 src/common/lib/libprop/prop_copyin_ioctl.9 (expand / switch to unified diff)

--- src/common/lib/libprop/prop_copyin_ioctl.9 2017/01/15 22:14:22 1.11
+++ src/common/lib/libprop/prop_copyin_ioctl.9 2017/01/29 01:38:02 1.12
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: prop_copyin_ioctl.9,v 1.11 2017/01/15 22:14:22 wiz Exp $ 1.\" $NetBSD: prop_copyin_ioctl.9,v 1.12 2017/01/29 01:38:02 pgoyette Exp $
2.\" 2.\"
3.\" Copyright (c) 2006, 2009 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2006, 2009 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Jason R. Thorpe. 7.\" by Jason R. Thorpe.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
@@ -17,89 +17,125 @@ @@ -17,89 +17,125 @@
17.\" 17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 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 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 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 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 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 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 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd January 17, 2011 30.Dd January 29, 2017
31.Dt PROP_COPYIN_IOCTL 9 31.Dt PROP_COPYIN_IOCTL 9
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm prop_array_copyin_ioctl , 34.Nm prop_array_copyin_ioctl ,
35.Nm prop_array_copyout_ioctl , 35.Nm prop_array_copyout_ioctl ,
36.Nm prop_array_copyin , 36.Nm prop_array_copyin ,
37.Nm prop_array_copyout , 37.Nm prop_array_copyout ,
38.Nm prop_dictionary_copyin_ioctl , 38.Nm prop_dictionary_copyin_ioctl ,
39.Nm prop_dictionary_copyout_ioctl , 39.Nm prop_dictionary_copyout_ioctl ,
40.Nm prop_dictionary_copyin , 40.Nm prop_dictionary_copyin ,
41.Nm prop_dictionary_copyout 41.Nm prop_dictionary_copyout
42.Nd Copy property lists to and from kernel space 42.Nd Copy property lists to and from kernel space
43.Sh SYNOPSIS 43.Sh SYNOPSIS
44.In prop/proplib.h 44.In prop/proplib.h
45.Ft int 45.Ft int
46.Fn prop_array_copyin_ioctl "const struct plistref *pref" \ 46.Fn prop_array_copyin_ioctl "const struct plistref *pref" \
47 "const u_long cmd" "prop_array_t *arrayp" 47 "const u_long cmd" "prop_array_t *arrayp"
48.Ft int 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
49.Fn prop_array_copyin "const struct plistref *pref" \ 52.Fn prop_array_copyin "const struct plistref *pref" \
50 "prop_array_t *arrayp" 53 "prop_array_t *arrayp"
51.Ft int 54.Ft int
 55.Fn prop_array_copyin_size "const struct plistref *pref" \
 56 "prop_array_t *arrayp" "size_t lim"
 57.Ft int
52.Fn prop_array_copyout_ioctl "struct plistref *pref" \ 58.Fn prop_array_copyout_ioctl "struct plistref *pref" \
53 "const u_long cmd" "prop_array_t array" 59 "const u_long cmd" "prop_array_t array"
54.Ft int 60.Ft int
55.Fn prop_array_copyout "struct plistref *pref" \ 61.Fn prop_array_copyout "struct plistref *pref" \
56 "prop_array_t array" 62 "prop_array_t array"
57.Ft int 63.Ft int
58.Fn prop_dictionary_copyin_ioctl "const struct plistref *pref" \ 64.Fn prop_dictionary_copyin_ioctl "const struct plistref *pref" \
59 "const u_long cmd" "prop_dictionary_t *dictp" 65 "const u_long cmd" "prop_dictionary_t *dictp"
60.Ft int 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
61.Fn prop_dictionary_copyin "const struct plistref *pref" \ 70.Fn prop_dictionary_copyin "const struct plistref *pref" \
62 "prop_dictionary_t *dictp" 71 "prop_dictionary_t *dictp"
63.Ft int 72.Ft int
 73.Fn prop_dictionary_copyin_size "const struct plistref *pref" \
 74 "prop_dictionary_t *dictp" "size_t lim"
 75.Ft int
64.Fn prop_dictionary_copyout_ioctl "struct plistref *pref" \ 76.Fn prop_dictionary_copyout_ioctl "struct plistref *pref" \
65 "const u_long cmd" "prop_dictionary_t dict" 77 "const u_long cmd" "prop_dictionary_t dict"
66.Ft int 78.Ft int
67.Fn prop_dictionary_copyout "struct plistref *pref" \ 79.Fn prop_dictionary_copyout "struct plistref *pref" \
68 "prop_dictionary_t dict" 80 "prop_dictionary_t dict"
69.Sh DESCRIPTION 81.Sh DESCRIPTION
70The 82The
 83.Nm prop_array_ioctl ,
71.Nm prop_array_copyin_ioctl , 84.Nm prop_array_copyin_ioctl ,
 85.Nm prop_array_copyin_ioctl_size ,
72.Nm prop_array_copyout_ioctl , 86.Nm prop_array_copyout_ioctl ,
73.Nm prop_dictionary_copyin_ioctl , 87.Nm prop_dictionary_copyin_ioctl ,
 88.Nm prop_dictionary_copyin_ioctl_size ,
74and 89and
75.Nm prop_dictionary_copyout_ioctl 90.Nm prop_dictionary_copyout_ioctl
76functions implement the kernel side of a protocol for copying property lists 91functions implement the kernel side of a protocol for copying property lists
77to and from the kernel using 92to and from the kernel using
78.Xr ioctl 2 . 93.Xr ioctl 2 .
79The functions 94The functions
80.Nm prop_array_copyin , 95.Nm prop_array_copyin ,
 96.Nm prop_array_copyin_size ,
81.Nm prop_array_copyout , 97.Nm prop_array_copyout ,
82.Nm prop_dictionary_copyin , 98.Nm prop_dictionary_copyin ,
 99.Nm prop_dictionary_copyin_size ,
83and 100and
84.Nm prop_dictionary_copyout 101.Nm prop_dictionary_copyout
85implement the kernel side of a protocol for copying property lists to the 102implement the kernel side of a protocol for copying property lists to the
86kernel as arguments of normal system calls. 103kernel as arguments of normal system calls.
87.Pp 104.Pp
88A kernel routine receiving or returning a property list will be passed a 105A kernel routine receiving or returning a property list will be passed a
89pointer to a 106pointer to a
90.Vt struct plistref . 107.Vt struct plistref .
91This structure encapsulates the reference to the property list in externalized 108This structure encapsulates the reference to the property list in externalized
92form. 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.
93.Sh RETURN VALUES 129.Sh RETURN VALUES
94If successful, functions return zero. 130If successful, functions return zero.
95Otherwise, an error number will be returned to indicate the error. 131Otherwise, an error number will be returned to indicate the error.
96.Sh EXAMPLES 132.Sh EXAMPLES
97The following 133The following
98.Pq simplified 134.Pq simplified
99example demonstrates using 135example demonstrates using
100.Fn prop_dictionary_copyin_ioctl 136.Fn prop_dictionary_copyin_ioctl
101and 137and
102.Fn prop_dictionary_copyout_ioctl 138.Fn prop_dictionary_copyout_ioctl
103in an ioctl routine: 139in an ioctl routine:
104.Bd -literal 140.Bd -literal
105extern prop_dictionary_t fooprops; 141extern prop_dictionary_t fooprops;