'\" te
.\"  Copyright 1989 AT&T 
.\"  Copyright (c) 1997, Sun Microsystems, Inc.  All Rights Reserved
.TH read 9E "19 Nov 1997" "SunOS 5.11" "Driver Entry Points"
.SH NAME
read \- read data from a device
.SH SYNOPSIS
.LP
.nf
#include <sys/types.h>
#include <sys/errno.h>
#include <sys/open.h>
#include <sys/uio.h>
#include <sys/cred.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>

\fBint prefix\fR\fBread\fR(\fBdev_t\fR \fIdev\fR, \fBstruct uio *\fR\fIuio_p\fR, \fBcred_t *\fR\fIcred_p\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Architecture independent level 1 (DDI/DKI). This entry point is \fIoptional\fR. 
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIdev\fR \fR
.ad
.RS 11n
.rt  
Device number.
.RE

.sp
.ne 2
.mk
.na
\fB\fIuio_p\fR \fR
.ad
.RS 11n
.rt  
Pointer to the  \fBuio\fR(9S) structure that describes where the data is to be stored in user space.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcred_p\fR \fR
.ad
.RS 11n
.rt  
Pointer to the  user credential structure for the \fBI/O \fRtransaction. 
.RE

.SH DESCRIPTION
.sp
.LP
The driver  \fBread()\fR routine is called indirectly through \fBcb_ops\fR(9S) by the  \fBread\fR(2) system call. The  \fBread()\fR routine should check the validity of the minor number component of \fIdev\fR and the user credential structure pointed to by  \fIcred_p\fR (if pertinent). The  \fBread()\fR routine should supervise the data transfer into the user space described by the  \fBuio\fR(9S) structure.
.SH RETURN VALUES
.sp
.LP
The  \fBread()\fR routine should return  \fB0\fR for success, or the appropriate error number.  
.SH EXAMPLES
.LP
\fBExample 1 \fR\fBread()\fR routine using \fBphysio()\fR
.sp
.LP
The following is an example of a \fBread()\fR routine using \fBphysio\fR(9F) to perform reads from a non-seekable device:

.sp
.in +2
.nf
      static int
      xxread(dev_t dev, struct uio *uiop, cred_t *credp)
      {
               int                 rval;
               offset_t            off;
               int                 instance;
               xx_t                xx;

               instance = getminor(dev);
               xx = ddi_get_soft_state(xxstate, instance);
               if (xx == NULL)
                         return (ENXIO);
               off = uiop->uio_loffset;
               rval = physio(xxstrategy, NULL, dev, B_READ,
                         xxmin, uiop);
               uiop->uio_loffset = off;
               return (rval);
      }							
.fi
.in -2

.SH SEE ALSO
.sp
.LP
\fBread\fR(2), \fBwrite\fR(9E), \fBphysio\fR(9F), \fBcb_ops\fR(9S), \fBuio\fR(9S) 
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR