copyout(D3DK) —

.IX \f4copyout\fP(D3DK)

NAME

copyout − copy data from a driver buffer to a user buffer

SYNOPSIS

#include <sys/types.h>
int copyout(caddr_t driverbuf, caddr_t userbuf, size_t count);

ARGUMENTS

driverbufDriver source address from which copy is made.

userbufUser destination address to which copy is made.

countNumber of bytes to copy.

DESCRIPTION

.IX \f4read\fP(D2DK)
.IX \f4write\fP(D2DK)
copyout copies count bytes of data from the kernel virtual address specified by driverbuf to the user virtual address specified by userbuf.

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.

RETURN VALUE

If the copy is successful, 0 is returned. Otherwise, −1 is returned to indicate that the specified user address range is not valid.

LEVEL

Base Only.

NOTES

May sleep.

Drivers usually convert a return value of −1 into an EFAULT error.

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.

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.

The driver source buffer must be completely within the kernel address space, or the system can panic.

EXAMPLE

.IX \f4copyout\fP(D3DK), example
.IX \f4ioctl\fP(D2DK), example
A driver ioctl(D2DK) 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 {
7register struct device ∗dp;
  8switch (cmd) {
9case XX_GETREGS:/∗ copy device registers to user program ∗/
10dp = &xx_dev[getminor(dev)];
11if (copyout((caddr_t)dp, arg, sizeof(struct device)))
12return (EFAULT);
13break;

DDI/DKI

Museum