usr/src/man/man9f/copyout.9f

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH COPYOUT 9F "Sep 27, 2002"
   7 .SH NAME
   8 copyout \- copy data from a driver to a user program
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/types.h>
  13 #include <sys/ddi.h>
  14
  15
  16
  17 \fBint\fR \fBcopyout\fR(\fBconst void *\fR\fIdriverbuf\fR, \fBvoid *\fR\fIuserbuf\fR, \fBsize_t\fR \fIcn\fR);
  18 .fi
  19
  20 .SH INTERFACE LEVEL
  21 .sp
  22 .LP
  23 This interface is obsolete. \fBddi_copyout\fR(9F) should be used instead.
  24 .SH PARAMETERS
  25 .sp
  26 .ne 2
  27 .na
  28 \fB\fIdriverbuf\fR \fR
  29 .ad
  30 .RS 14n
  31 Source address in the driver from which the data is transferred.
  32 .RE
  33
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIuserbuf\fR \fR
  38 .ad
  39 .RS 14n
  40 Destination address in the user program to which the data is transferred.
  41 .RE
  42
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIcn\fR \fR
  47 .ad
  48 .RS 14n
  49 Number of bytes moved.
  50 .RE
  51
  52 .SH DESCRIPTION
  53 .sp
  54 .LP
  55 \fBcopyout()\fR copies data from driver buffers to user data space.
  56 .sp
  57 .LP
  58 Addresses that are word-aligned are moved most efficiently.  However, the
  59 driver developer is not obligated to ensure alignment.  This function
  60 automatically finds the most efficient move algorithm according to address
  61 alignment.
  62 .SH RETURN VALUES
  63 .sp
  64 .LP
  65 Under normal conditions, a \fB0\fR is returned to indicate a successful copy.
  66 Otherwise, a \(mi\fB1\fR is returned if one of the following occurs:
  67 .RS +4
  68 .TP
  69 .ie t \(bu
  70 .el o
  71 Paging fault; the driver tried to access a page of memory for which it did not
  72 have read or write access.
  73 .RE
  74 .RS +4
  75 .TP
  76 .ie t \(bu
  77 .el o
  78 Invalid user address, such as a user area or stack area.
  79 .RE
  80 .RS +4
  81 .TP
  82 .ie t \(bu
  83 .el o
  84 Invalid address that would have resulted in data being copied into the user
  85 block.
  86 .RE
  87 .RS +4
  88 .TP
  89 .ie t \(bu
  90 .el o
  91 Hardware fault; a hardware error prevented access to the specified user memory.
  92 For example, an uncorrectable parity or \fBECC\fR error occurred.
  93 .RE
  94 .sp
  95 .LP
  96 If a \(mi\fB1\fR is returned to the caller, driver entry point routines should
  97 return \fBEFAULT\fR.
  98 .SH CONTEXT
  99 .sp
 100 .LP
 101 \fBcopyout()\fR can be called from user context only.
 102 .SH EXAMPLES
 103 .LP
 104 \fBExample 1 \fRAn \fBioctl()\fR Routine
 105 .sp
 106 .LP
 107 A driver \fBioctl\fR(9E) routine (line 10) can be used to get or set device
 108 attributes or registers.  In the \fBXX_GETREGS\fR condition (line 17), the
 109 driver copies the current device register values to a user data area (line 18).
 110 If the specified argument contains an invalid address, an error code is
 111 returned.
 112
 113 .sp
 114 .in +2
 115 .nf
 116  1  struct device  {      /* layout of physical device registers  */
 117  2       int      control;     /* physical device control word  */
 118  3       int      status;      /* physical device status word   */
 119  4       short    recv_char;   /* receive character from device */
 120  5       short    xmit_char;   /* transmit character to device  */
 121  6  };
 122  7
 123  8  extern struct device xx_addr[]; /* phys. device regs. location */
 124  9    . . .
 125 10  xx_ioctl(dev_t dev, int cmd, int arg, int mode,
 126 11      cred_t *cred_p, int *rval_p)
 127 12               ...
 128 13  {
 129 14      register struct device *rp = &xx_addr[getminor(dev) >> 4];
 130 15      switch (cmd) {
 131 16
 132 17      case XX_GETREGS:     /* copy device regs. to user program */
 133 18            if (copyout(rp, arg, sizeof(struct device)))
 134 19                return(EFAULT);
 135 20            break;
 136 21               ...
 137 22      }
 138 23               ...
 139 24  }
 140 .fi
 141 .in -2
 142
 143 .SH ATTRIBUTES
 144 .sp
 145 .LP
 146 See \fBattributes\fR(5) for a description of the following attributes:
 147 .sp
 148
 149 .sp
 150 .TS
 151 box;
 152 c | c
 153 l | l .
 154 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 155 _
 156 Stability Level Obsolete
 157 .TE
 158
 159 .SH SEE ALSO
 160 .sp
 161 .LP
 162 \fBattributes\fR(5), \fBioctl\fR(9E), \fBbcopy\fR(9F), \fBcopyin\fR(9F),
 163 \fBddi_copyin\fR(9F), \fBddi_copyout\fR(9F), \fBuiomove\fR(9F)
 164 .sp
 165 .LP
 166 \fIWriting Device Drivers\fR
 167 .SH NOTES
 168 .sp
 169 .LP
 170 Driver writers who intend to support layered ioctls in their \fBioctl\fR(9E)
 171 routines should use \fBddi_copyout\fR(9F) instead.
 172 .sp
 173 .LP
 174 Driver defined locks should not be held across calls to this function.
 175 .sp
 176 .LP
 177 \fBcopyout()\fR should not be used from a streams driver. See \fBM_COPYIN\fR
 178 and \fBM_COPYOUT\fR in \fISTREAMS Programming Guide\fR.