git.saurik.com Git - apple/xnu.git/blob

1 .\"

3 .\"

4 .\" @APPLE_LICENSE_HEADER_START@

5 .\"

6 .\" This file contains Original Code and/or Modifications of Original Code

7 .\" as defined in and that are subject to the Apple Public Source License

8 .\" Version 2.0 (the 'License'). You may not use this file except in

9 .\" compliance with the License. Please obtain a copy of the License at

10 .\" http://www.opensource.apple.com/apsl/ and read it before using this

11 .\" file.

12 .\"

13 .\" The Original Code and all software distributed under the License are

14 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER

15 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,

16 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,

17 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.

18 .\" Please see the License for the specific language governing rights and

19 .\" limitations under the License.

20 .\"

21 .\" @APPLE_LICENSE_HEADER_END@

22 .\"

23 .\"

24 .\" $NetBSD: copy.9,v 1.2 1996/01/09 03:23:04 thorpej Exp $

25 .\"

28 .\"

29 .\" This code is derived from software contributed by Kenneth Stailey.

30 .\"

31 .\" Redistribution and use in source and binary forms, with or without

32 .\" modification, are permitted provided that the following conditions

33 .\" are met:

34 .\" 1. Redistributions of source code must retain the above copyright

35 .\" notice, this list of conditions and the following disclaimer.

36 .\" 2. Redistributions in binary form must reproduce the above copyright

37 .\" notice, this list of conditions and the following disclaimer in the

38 .\" documentation and/or other materials provided with the distribution.

39 .\" 3. All advertising materials mentioning features or use of this software

40 .\" must display the following acknowledgement:

41 .\" This product includes software developed for the NetBSD Project

42 .\" by Jason R. Thorpe.

43 .\" 4. The name of the author may not be used to endorse or promote products

44 .\" derived from this software without specific prior written permission.

45 .\"

46 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR

47 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES

48 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.

49 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,

50 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,

51 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;

52 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED

53 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

54 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

55 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

56 .\" SUCH DAMAGE.

57 .\"

58 .\" $FreeBSD: src/share/man/man9/copy.9,v 1.6.2.5 2001/12/17 11:30:18 ru Exp $

59 .\"

60 .Dd October 2, 2008

61 .Dt COPY 9

62 .Os

63 .Sh NAME

64 .Nm copy ,

65 .Nm copyin ,

66 .Nm copyinstr ,

67 .Nm copyout ,

68 .Nm copystr

69 .Nd kernel copy functions

70 .Sh SYNOPSIS

71 .In sys/types.h

72 .In sys/systm.h

73 .Ft int

74 .Fo copyin

75 .Fa "const void *uaddr"

76 .Fa "void *kaddr"

77 .Fa "size_t len"

78 .Fc

79 .Ft int

80 .Fo copyinstr

81 .Fa "const void *uaddr"

82 .Fa "void *kaddr"

83 .Fa "size_t len"

84 .Fa "size_t *done"

85 .Fc

86 .Ft int

87 .Fo copyout

88 .Fa "const void *kaddr"

89 .Fa "void *uaddr"

90 .Fa "size_t len"

91 .Fc

92 .\" .Ft int

93 .\" .Fn copyoutstr

94 .\" .Fa "const void *kaddr"

95 .\" .Fa "void *uaddr"

96 .\" .Fa "size_t len"

97 .\" .Fa "size_t *done"

98 .\" .Fc

99 .Ft int

100 .Fo copystr

101 .Fa "const void *kfaddr"

102 .Fa "void *kdaddr"

103 .Fa "size_t len"

104 .Fa "size_t *done"

105 .Fc

106 .Sh DESCRIPTION

107 The

108 .Nm

109 functions are designed to copy contiguous data from one address

110 to another. All but

111 .Fn copystr

112 copy data from user-space to kernel-space or vice-versa.

113 .Pp

114 The

115 .Nm

116 routines provide the following functionality:

117 .Bl -tag -width "copyoutstr()"

118 .\" ========

119 .It Fn copyin

120 Copies

121 .Pa len

122 bytes of data from the user-space address

123 .Pa uaddr

124 to the kernel-space address

125 .Pa kaddr .

126 .\" ========

127 .It Fn copyinstr

128 Copies a NUL-terminated string, at most

129 .Pa len

130 bytes long, from user-space address

131 .Pa uaddr

132 to kernel-space address

133 .Pa kaddr .

134 The number of bytes actually copied, including the terminating

135 NUL, is returned in

136 .Pa *done .

137 .\" ========

138 .It Fn copyout

139 Copies

140 .Pa len

141 bytes of data from the kernel-space address

142 .Pa kaddr

143 to the user-space address

144 .Pa uaddr .

145 .\" ========

146 .\" .It Fn copyoutstr

147 .\" Copies a NUL-terminated string, at most

148 .\" bytes long, from kernel-space address

149 .\" .Pa kaddr

150 .\" to user-space address

151 .\" .Pa uaddr .

152 .\" The number of bytes actually copied, including the terminating

153 .\" NUL, is returned in

154 .\" .Pa *done .

155 .\" ========

156 .It Fn copystr

157 Copies a NUL-terminated string, at most

158 .Pa len

159 bytes long, from kernel-space address

160 .Pa kfaddr

161 to kernel-space address

162 .Pa kdaddr .

163 The number of bytes actually copied, including the terminating

164 NUL, is returned in

165 .Pa *done .

166 .El

167 .Sh RETURN VALUES

168 The

169 .Nm

170 functions return 0 on success or the following error on failure:

171 .\" ========

172 .Bl -tag -width Er

173 .It Bq EFAULT

174 If a bad address is encountered. When this error is returned, the contents of the destination buffer (

175 .Fa *kaddr

176 for

177 .Fn copyin ,

178 .Fn copyinstr ,

179 and

180 .Fn copystr ;

181 .Fa *uaddr

182 for

183 .Fn copyout )

184 are undefined. For

185 .Fn copyinstr

186 and

187 .Fn copystr ,

188 the contents of the

189 .Fa *done

190 parameter are also undefined on a return of EFAULT.

191 .El

192 .Pp

193 In addition to EFAULT,

194 .\" .Fn copystr ,

195 .\" .Fn copyinstr ,

196 .\" and

197 .\" .Fn copyoutstr

198 .Fn copystr

199 and

200 .Fn copyinstr

201 on failure will return:

202 .\" ========

203 .Bl -tag -width Er

204 .It Bq ENAMETOLONG

205 When the string is longer than

206 .Pa len

207 bytes. On this error return, the destination buffer is not null-terminated, but the

208 .Fa *done

209 parameter is maintained.

210 .EL

211 .Sh SEE ALSO

212 .Xr fetch 9 ,

213 .Xr store 9