copyout(D3) copyout(D3)
NAME
copyout - copy data from a driver buffer to a user buffer
SYNOPSIS
#include <sys/types.h>
#include <sys/ddi.h>
int copyout(caddr_t driverbuf, caddr_t userbuf, size_t count);
Arguments
driverbuf Driver source address from which copy is made.
userbuf User destination address to which copy is made.
count Number of bytes to copy.
DESCRIPTION
copyout copies count bytes of data from the kernel virtual
address specified by driverbuf to the user virtual address
specified by userbuf.
Return Values
On success, copyout returns 0. On failure, it returns -1 to
indicate that the specified user address range is not valid.
USAGE
copyout chooses the best algorithm based on address alignment
and number of bytes to copy. Although the source and
destination addresses are not required to be word aligned,
word aligned addresses may result in a more efficient copy.
Drivers usually convert a return value of -1 into an EFAULT
error.
Level
Base only.
Synchronization Constraints
Can sleep.
Driver-defined basic locks and read/write locks may not be
held across calls to this function.
Driver-defined sleep locks may be held across calls to this
function.
Copyright 1994 Novell, Inc. Page 1
copyout(D3) copyout(D3)
Warnings
The driver source buffer must be completely within the kernel
address space, or the system can panic.
When holding sleep locks across calls to this function,
drivers must be careful to avoid creating a deadlock. During
the data transfer, page fault resolution might result in
another I/O to the same device. For example, this could occur
if the driver controls the disk drive used as the swap device.
Examples
A driver ioctl(D2) routine (line 5) can be used to get or set
device attributes or registers. If the specified command is
XX_GETREGS (line 9), the driver copies the current device
register values to a user data area (line 11). If the user
address is invalid, an error code is returned.
1 struct device { /* device registers layout */
...
2 int status; /* device status word */
3 };
4 extern struct device xx_dev[]; /* physical device registers */
...
5 xxioctl(dev_t dev, int cmd, void *arg, int mode, cred_t *crp, int *rvp)
6 {
7 struct device *dp;
8 switch (cmd) {
9 case XX_GETREGS: /* copy device registers to user program */
10 dp = &xx_dev[getminor(dev)];
11 if (copyout((caddr_t)dp, arg, sizeof(struct device)))
12 return (EFAULT);
13 break;
REFERENCES
bcopy(D3), copyin(D3), uiomove(D3), ureadc(D3), uwritec(D3)
NOTICES
Portability
All processors
Applicability
ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp
Copyright 1994 Novell, Inc. Page 2