SVR5

copyout(D3)

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

Synopsis

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

Description

copyout copies count bytes of data from the kernel virtual address specified by driverbuf to the user virtual address specified by userbuf.

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.

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.

Context and synchronization

User context.

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  struct idata  {     /* instance data */
    5	...
    6	struct device *devregs;
   	...
    7  }
       ...
    8  xxioctl(void *idata, ulong_t channel, int cmd, void *arg, int mode, cred_t *crp, int *rvp)
    9  {
   10	struct device *dp;
   

   11	switch (cmd) {
   12	case XX_GETREGS:	/* copy device registers to user program */
   13		dp = ((struct idata *)idata)->devregs;
   14		if (copyout(dp, arg, sizeof(struct device)))
   15			return (EFAULT);
   16		break;

Hardware applicability

All

Version applicability

ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp

SCO OpenServer ODDI compatibility

copyout(D3oddi) is the ODDI equivalent of this function. ODDI also supports other functions for moving data between user and kernel space; see ``Data, copying'' in HDK Technical Reference for more information.

References

bcopy(D3), copyin(D3), uiomove(D3), ureadc(D3), uwritec(D3)

M_COPYOUT(D7str)

``Data, copying'' in HDK Technical Reference