![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to read.2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys|
Return to read.2 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys |
1.1 root 1: .\" Copyright (c) 1980 Regents of the University of California.
2: .\" All rights reserved. The Berkeley software License Agreement
3: .\" specifies the terms and conditions for redistribution.
4: .\"
5: .\" @(#)read.2 6.6 (Berkeley) 5/23/86
6: .\"
7: .TH READ 2 "May 23, 1986"
8: .UC 4
9: .SH NAME
10: read, readv \- read input
11: .SH SYNOPSIS
12: .nf
13: .ft B
14: cc = read(d, buf, nbytes)
15: int cc, d;
16: char *buf;
17: int nbytes;
18: .PP
19: .ft B
20: #include <sys/types.h>
21: #include <sys/uio.h>
22: .PP
23: .ft B
24: cc = readv(d, iov, iovcnt)
25: int cc, d;
26: struct iovec *iov;
27: int iovcnt;
28: .fi
29: .SH DESCRIPTION
30: .I Read
31: attempts to read
32: .I nbytes
33: of data from the object referenced by the descriptor
34: .I d
35: into the buffer pointed to by
36: .IR buf .
37: .I Readv
38: performs the same action, but scatters the input data
39: into the
40: .I iovcnt
41: buffers specified by the members of the
42: .I iov
43: array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1].
44: .PP
45: For
46: .IR readv ,
47: the
48: .I iovec
49: structure is defined as
50: .PP
51: .nf
52: .RS
53: .DT
54: struct iovec {
55: caddr_t iov_base;
56: int iov_len;
57: };
58: .RE
59: .fi
60: .PP
61: Each
62: .I iovec
63: entry specifies the base address and length of an area
64: in memory where data should be placed.
65: .I Readv
66: will always fill an area completely before proceeding
67: to the next.
68: .PP
69: On objects capable of seeking, the
70: .I read
71: starts at a position
72: given by the pointer associated with
73: .IR d
74: (see
75: .IR lseek (2)).
76: Upon return from
77: .IR read ,
78: the pointer is incremented by the number of bytes actually read.
79: .PP
80: Objects that are not capable of seeking always read from the current
81: position. The value of the pointer associated with such an
82: object is undefined.
83: .PP
84: Upon successful completion,
85: .I read
86: and
87: .I readv
88: return the number of bytes actually read and placed in the buffer.
89: The system guarantees to read the number of bytes requested if
90: the descriptor references a normal file that has that many bytes left
91: before the end-of-file, but in no other case.
92: .PP
93: If the returned value is 0, then
94: end-of-file has been reached.
95: .SH "RETURN VALUE
96: If successful, the
97: number of bytes actually read is returned.
98: Otherwise, a \-1 is returned and the global variable
99: .I errno
100: is set to indicate the error.
101: .SH "ERRORS
102: .I Read
103: and
104: .I readv
105: will fail if one or more of the following are true:
106: .TP 15
107: [EBADF]
108: \fID\fP is not a valid file or socket descriptor open for reading.
109: .TP 15
110: [EFAULT]
111: \fIBuf\fP points outside the allocated address space.
112: .TP 15
113: [EIO]
114: An I/O error occurred while reading from the file system.
115: .TP 15
116: [EINTR]
117: A read from a slow device was interrupted before
118: any data arrived by the delivery of a signal.
119: .TP 15
120: [EINVAL]
121: The pointer associated with
122: .I d
123: was negative.
124: .TP 15
125: [EWOULDBLOCK]
126: The file was marked for non-blocking I/O,
127: and no data were ready to be read.
128: .PP
129: In addition,
130: .I readv
131: may return one of the following errors:
132: .TP 15
133: [EINVAL]
134: .I Iovcnt
135: was less than or equal to 0, or greater than 16.
136: .TP 15
137: [EINVAL]
138: One of the
139: .I iov_len
140: values in the
141: .I iov
142: array was negative.
143: .TP 15
144: [EINVAL]
145: The sum of the
146: .I iov_len
147: values in the
148: .I iov
149: array overflowed a 32-bit integer.
150: .TP 15
151: [EFAULT]
152: Part of the \fIiov\fP points outside the process's allocated address space.
153: .SH "SEE ALSO"
154: dup(2), fcntl(2), open(2), pipe(2), select(2), socket(2), socketpair(2)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.