share/man/man9f/copyin.9f

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