294b75a880
Unlike the other copy*() functions, it does not serve to copy from one address space to another or protect against potential faults. It's just an older incarnation of the now-more-common strlcpy(). Reviewed by: jhb MFC after: i² days Differential Revision: yes (see 2/2)
167 lines
4.3 KiB
Groff
167 lines
4.3 KiB
Groff
.\" $NetBSD: copy.9,v 1.2 1996/01/09 03:23:04 thorpej Exp $
|
|
.\"
|
|
.\" Copyright (c) 1996 Jason R. Thorpe.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed by Kenneth Stailey.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed for the NetBSD Project
|
|
.\" by Jason R. Thorpe.
|
|
.\" 4. The name of the author may not be used to endorse or promote products
|
|
.\" derived from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
|
|
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
|
|
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd May 11, 2020
|
|
.Dt COPY 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm copy ,
|
|
.Nm copyin ,
|
|
.Nm copyin_nofault ,
|
|
.Nm copyout ,
|
|
.Nm copyout_nofault ,
|
|
.Nm copystr ,
|
|
.Nm copyinstr
|
|
.Nd heterogenous address space copy functions
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In sys/systm.h
|
|
.Ft int
|
|
.Fn copyin "const void *uaddr" "void *kaddr" "size_t len"
|
|
.Ft int
|
|
.Fn copyin_nofault "const void *uaddr" "void *kaddr" "size_t len"
|
|
.Ft int
|
|
.Fn copyout "const void *kaddr" "void *uaddr" "size_t len"
|
|
.Ft int
|
|
.Fn copyout_nofault "const void *kaddr" "void *uaddr" "size_t len"
|
|
.Ft int __deprecated
|
|
.Fn copystr "const void *kfaddr" "void *kdaddr" "size_t len" "size_t *done"
|
|
.Ft int
|
|
.Fn copyinstr "const void *uaddr" "void *kaddr" "size_t len" "size_t *done"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
functions are designed to copy contiguous data from one address space
|
|
to another.
|
|
.Pp
|
|
.Fn copystr
|
|
is deprecated and should be replaced with
|
|
.Xr strlcpy 9 .
|
|
It will be removed from
|
|
.Fx 13 .
|
|
.Pp
|
|
The
|
|
.Fn copyin
|
|
and
|
|
.Fn copyin_nofault
|
|
functions copy
|
|
.Fa len
|
|
bytes of data from the user-space address
|
|
.Fa uaddr
|
|
to the kernel-space address
|
|
.Fa kaddr .
|
|
.Pp
|
|
The
|
|
.Fn copyout
|
|
and
|
|
.Fn copyout_nofault
|
|
functions copy
|
|
.Fa len
|
|
bytes of data from the kernel-space address
|
|
.Fa kaddr
|
|
to the user-space address
|
|
.Fa uaddr .
|
|
.Pp
|
|
The
|
|
.Fn copyin_nofault
|
|
and
|
|
.Fn copyout_nofault
|
|
functions require that the kernel-space and user-space data be
|
|
accessible without incurring a page fault.
|
|
The source and destination addresses must be physically mapped for
|
|
read and write access, respectively, and neither the source nor
|
|
destination addresses may be pageable.
|
|
.Pp
|
|
The
|
|
.Fn copystr
|
|
function copies a NUL-terminated string, at most
|
|
.Fa len
|
|
bytes long, from kernel-space address
|
|
.Fa kfaddr
|
|
to kernel-space address
|
|
.Fa kdaddr .
|
|
The number of bytes actually copied, including the terminating
|
|
NUL, is returned in
|
|
.Fa *done
|
|
(if
|
|
.Fa done
|
|
is
|
|
.No non- Ns Dv NULL ) .
|
|
.Pp
|
|
The
|
|
.Fn copyinstr
|
|
function copies a NUL-terminated string, at most
|
|
.Fa len
|
|
bytes long, from user-space address
|
|
.Fa uaddr
|
|
to kernel-space address
|
|
.Fa kaddr .
|
|
The number of bytes actually copied, including the terminating
|
|
NUL, is returned in
|
|
.Fa *done
|
|
(if
|
|
.Fa done
|
|
is
|
|
.No non- Ns Dv NULL ) .
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Nm
|
|
functions return 0 on success.
|
|
All but
|
|
.Fn copystr
|
|
return
|
|
.Er EFAULT
|
|
if a bad address is encountered.
|
|
The
|
|
.Fn copyin_nofault
|
|
and
|
|
.Fn copyout_nofault
|
|
functions return
|
|
.Er EFAULT
|
|
if a page fault occurs.
|
|
The
|
|
.Fn copystr
|
|
and
|
|
.Fn copyinstr
|
|
functions return
|
|
.Er ENAMETOOLONG
|
|
if the string is longer than
|
|
.Fa len
|
|
bytes.
|
|
.Sh SEE ALSO
|
|
.Xr fetch 9 ,
|
|
.Xr store 9
|