SVR5

copyin(D3)

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

Synopsis

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

Description

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

Arguments

userbuf: User source address from which copy is made.
driverbuf: Driver destination address to which copy is made.
count: Number of bytes to copy.

Return values

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

Usage

The driver must ensure that adequate space is allocated for the destination address.

copyin 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 a disk drive used as a 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_SETREGS (line 9), the driver copies user data to the device registers (line 11). If the user address is invalid, an error code is returned.

    1  struct device {	/* device registers layout */
   	...
    2	int command;	/* device command 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_SETREGS:	/* copy user program data to device registers */
   13		dp = ((struct idata *)idata)->devregs;
   14		if (copyin(arg, dp, 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

copyin(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), copyout(D3), uiomove(D3), ureadc(D3), uwritec(D3)

M_COPYIN(D7str)

``Data, copying'' in HDK Technical Reference