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.

   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)