Return to read.2 CVS log

Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man2

Annotation of cci/usr/src/man/man2/read.2, revision 1.1.1.2

1.1       root        1: .TH READ 2 "27 July 1983"
                      2: .UC 4
                      3: .SH NAME
                      4: read, readv \- read input
                      5: .SH SYNOPSIS
                      6: .nf
                      7: .ft B
                      8: cc = read(d, buf, nbytes)
                      9: int cc, d;
                     10: char *buf;
                     11: int nbytes;
                     12: .PP
                     13: .ft B
                     14: #include <sys/types.h>
                     15: #include <sys/uio.h>
                     16: .PP
                     17: .ft B
                     18: cc = readv(d, iov, iovcnt)
                     19: int cc, d;
                     20: struct iovec *iov;
                     21: int iovcnt;
                     22: .fi
                     23: .SH DESCRIPTION
                     24: .I Read
                     25: attempts to read
                     26: .I nbytes
                     27: of data from the object referenced by the descriptor
                     28: .I d
                     29: into the buffer pointed to by
                     30: .IR buf .
                     31: .I Readv
                     32: performs the same action, but scatters the input data
                     33: into the 
                     34: .I iovcnt
                     35: buffers specified by the members of the
                     36: .I iovec
                     37: array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1].
                     38: .PP
                     39: For 
                     40: .IR readv ,
                     41: the 
                     42: .I iovec
                     43: structure is defined as
                     44: .PP
                     45: .nf
                     46: .RS
                     47: .DT
                     48: struct iovec {
                     49:        caddr_t iov_base;
                     50:        int     iov_len;
                     51: };
                     52: .RE
                     53: .fi
                     54: .PP
                     55: Each 
                     56: .I iovec
                     57: entry specifies the base address and length of an area
                     58: in memory where data should be placed. 
                     59: .I Readv
1.1.1.2 ! root       60: always fills an area completely before proceeding
1.1       root       61: to the next.
                     62: .PP
                     63: On objects capable of seeking, the
                     64: .I read
                     65: starts at a position
                     66: given by the pointer associated with
                     67: .IR d ,
                     68: see
                     69: .IR lseek (2).
                     70: Upon return from
                     71: .IR read ,
                     72: the pointer is incremented by the number of bytes actually read.
                     73: .PP
                     74: Objects that are not capable of seeking always read from the current
                     75: position.  The value of the pointer associated with such a 
                     76: object is undefined.
                     77: .PP
                     78: Upon successful completion,
                     79: .I read
                     80: and
                     81: .I readv
                     82: return the number of bytes actually read and placed in the buffer.
                     83: The system guarantees to read the number of bytes requested if
                     84: the descriptor references a file which has that many bytes left
                     85: before the end-of-file, but in no other cases.
                     86: .PP
                     87: If the returned value is 0, then
                     88: end-of-file has been reached.
                     89: .SH "RETURN VALUE
                     90: If successful, the
                     91: number of bytes actually read is returned.
                     92: Otherwise, a \-1 is returned and the global variable
                     93: .I errno
                     94: is set to indicate the error.
                     95: .SH "ERRORS
                     96: .I Read
                     97: and
                     98: .I readv
1.1.1.2 ! root       99: fails if one or more of the following are true:
1.1       root      100: .TP 15
                    101: [EBADF]
                    102: \fIFildes\fP is not a valid file descriptor open for reading.
                    103: .TP 15
                    104: [EFAULT]
                    105: \fIBuf\fP points outside the allocated address space.
                    106: .TP 15
                    107: [EINTR]
                    108: A read from a slow device was interrupted before
                    109: any data arrived by the delivery of a signal.
                    110: .PP
                    111: In addition, 
                    112: .I readv
                    113: may return one of the following errors:
                    114: .TP 15
                    115: [EINVAL]
                    116: .I Iovcnt
                    117: was less than or equal to 0, or greater than 16.
                    118: .TP 15
                    119: [EINVAL]
                    120: One of the
                    121: .I iov_len
                    122: values in the
                    123: .I iov
                    124: array was negative.
                    125: .TP 15
                    126: [EINVAL]
                    127: The sum of the
                    128: .I iov_len
                    129: values in the
                    130: .I iov
                    131: array overflowed a 32-bit integer.
                    132: .SH "SEE ALSO"
                    133: dup(2), open(2), pipe(2), socket(2), socketpair(2)

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.