![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to filebuf.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / man / mana|
Return to filebuf.3 CVS log | Up to [Research Unix] / researchv10dc / man / mana |
1.1 root 1: . \"ident "%W%"
2: . \"Copyright (c) 1984 AT&T
3: . \"All Rights Reserved
4: . \"THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF AT&T
5: . \"The copyright notice above does not evidence any
6: . \"actual or intended publication of such source code.
7: .TH FILEBUF 3I+ "C++ Stream Library" " "
8: .SH NAME
9: filebuf \- buffer for file input/output
10: .SH SYNOPSIS
11: .ft B
12: .nf
13: .ta1i 2i
14: #include <iostream.h>
15:
16: typedef long streamoff, streampos;
17: class ios {
18: public:
19: enum seek_dir { beg, cur, end };
20: enum open_mode { in, out, ate, app } ;
21: // \fIand lots of other stuff ... \fP
22: } ;
23:
24: #include <fstream.h>
25:
26: class filebuf : streambuf {
27: public:
28: filebuf() ;
29: filebuf(int d);
30: filebuf(int d, char* p, int len) ;
31:
32: filebuf* attach(int d) ;
33: int close();
34: int fd();
35: int is_open();
36: filebuf* open(char *name, open_mode om, int prot=0664) ;
37: streampos seekoff(streamoff o, seek_dir d, open_mode m) ;
38: streampos seekpos(strempos p, open_mode m ) ;
39: streambuf* setbuf(char* p, int len) ;
40: int sync() ;
41: };
42: .fi
43: .ft R
44: .SH DESCRIPTION
45: \f(CWfilebuf\fRs
46: specialize
47: \f(CWstreambuf\fRs
48: to use a file as source or sink of characters.
49: Characters are consumed by doing
50: writes to the
51: file, and are produced by doing
52: reads.
53: When the file is seekable,
54: a \f(CWfilebuf\fR allows seeks.
55: At least 4 characters of putback are guaranteed.
56: When the file permits reading and writing the buffer permits
57: both storing and fetching. No special action is required between
58: gets and puts.
59: A
60: \f(CWfilebuf\fRs that is connected to a file descriptor is said
61: to be \fIopen\fR.
62: .PP
63: Assume:
64: .br
65: \(em \fBf\fR is a \f(CWfilebuf\fR.
66: .br
67: \(em \fBpfb\fR is a \f(CWfilebuf*\fR.
68: .br
69: \(em \fBpsb\fR is a \f(CWstreambuf*\fR.
70: .br
71: \(em \fBi\fR, \fBd\fR, \fBlen\fR, and \fBprot\fR are \f(CWint\fR
72: .br
73: \(em \fBname\fR and \fBptr\fR are \f(CWchar*\fR.
74: .br
75: \(em \fBm\fR is \f(CWopen_mode\fR.
76: .br
77: \(em \fBoff\fR is \f(CWstreamoff\fR.
78: .br
79: \(em \fBp\fR and \fBpos\fR are \f(CWstreampos\fR.
80: .br
81: \(em \fBdir\fR is \f(CWseek_dir\fR.
82: .PP
83: Constructors:
84: .TP
85: \fBfilebuf()\fR
86: Constructs an initially closed \f(CWfilebuf\fR.
87: .TP
88: \fBfilebuf(d)\fR
89: Constructs a \f(CWfilebuf\fR connected to \fBd\fR.
90: .TP
91: \fBfilebuf(d,p,len)\fR
92: Constructs a \f(CWfilebuf\fR connected to \fBd\fR
93: and initialized to use the reserve area starting at \fBp\fR and containing
94: \fBlen\fR bytes.
95: If \fBp\fR is null or \fBlen\fR is zero or less,
96: the \f(CWfilebuf\fR will be unbuffered.
97: .PP
98: Members:
99: .TP
100: \fBpfb=f.attach(d)
101: Connects \fBf\fR
102: to an open file descriptor, \fBd\fR.
103: \fBpfb\fR is normally \fB&f\fR
104: but is 0 if \fBf\fR is already open.
105: .TP
106: \fBi=f.close()
107: Flushes any waiting output, closes the file descriptor, and disconnects
108: \fBf\fR. Unless an error occurs, \fBf\fR's error state will be cleared.
109: \fBi\fR is 0 unless errors occur in which case it is \f(CWEOF\fR .
110: Even if errors occur
111: \fBattach\fR leaves the file descriptor and \fBf\fR
112: closed.
113: .TP
114: \fBi=f.fd()\fR
115: Returns \fBi\fR, the file descriptor \fBf\fR is connected to.
116: If \fBf\fR is closed \fBi\fR is \f(CWEOF\fR.
117: .TP
118: \fBi=f.is_open()\fR
119: Returns non-zero when \fBf\fR is connected to a file descriptor,
120: and zero otherwise.
121: .TP
122: \fBpfb=f.open(name,m,prot)\fR
123: Opens a file with the specified pathname, mode, and protection,
124: and connects \fBf\fR to it.
125: \f(CWopen_mode\fRs may be or'ed together to form \fBm\fR.
126: \f(CWin\fR and \f(CWout\fR translate to corresponding UNIX modes.
127: \f(CWate\fR and
128: \f(CWapp\fR
129: both cause the file to be positioned
130: at its end during the open. \f(CWapp\fR implies \f(CWoutput\fR.
131: In addition,
132: \f(CWapp\fR causes all subsequent
133: writes to occur at the end of a file.
134: (In some systems this is supported directly by the kernel, in other
135: instances the desired effect is approximated by seeking to the
136: end of the file before each write.)
137: \f(CWout\fR may be specified even if \fBprot\fR does not permit
138: output.
139: Normally \fBpfb\fR is \fB&f\fR
140: but if an error occurs it is 0.
141: .TP
142: \fBp=f.seekoff(off,dir,m)\fR
143: Moves the get/put pointer as designated by \fBoff\fR and \fBdir\fR.
144: It fails if the file that \fBf\fR is attached to
145: does not support seeking, or if the attempted motion
146: is otherwise invalid (such as attempting to seek to a position
147: before the beginning of file).
148: \fBoff\fR is interpreted as a count
149: relative to the place in the file specified by \fBdir\fR
150: as described in \fIsbuf.pub\fR(3C++).
151: \f(CWm\fR is ignored.
152: \fBp\fR is the position after movement, or \f(CWEOF\fR if
153: a failure occurs.
154: The position of the file after a failure is undefined.
155: .TP
156: \fBp=f.seekpos(pos,m)\fR
157: Moves the file to a position \fBpos\fR
158: as described in \fIsbuf.pub\fR(3C++).
159: \f(CWm\fR is ignored.
160: Normally \fBp\fR is \fBpos\fR, but on failure it is \f(CWEOF\fR.
161: .TP
162: \fBpsb=f.setbuf(ptr,len)\fR
163: Sets up the reserve area as \fBlen\fR bytes beginning at \fBp\fR.
164: If \fBptr\fR is null or \fBlen\fR is less than or equal to 0, the
165: \fBf\fR will be unbuffered.
166: Normally \fBpsb\fR is \fB&f\fR, but
167: it is 0 if \fBf\fR is open, and in the latter case no changes
168: are made to the reserve area or buffering status.
169: .TP
170: \fBi=f.sync()\fR
171: Attempts to force the state of get/put pointers of \fBf\fR to agree
172: (be synchronized) with
173: the state of the file \fBf.fd()\fR. This means it
174: may write characters to the file if some have been buffered for
175: output or attempt to reposition (seek) the file if characters have
176: been read and buffered for input. Normally \fBi\fR is 0, but it
177: is \f(CWEOF\fR if synchronization is not possible.
178: Sometimes it is neccessary to guarantee that certain
179: characters are written together.
180: To do this, the program should use
181: \fBsetbuf\fR
182: (or a constructor)
183: to guarantee that the reserve area is at least as large as
184: the number of characters that must be written together.
185: It can then do a \fBsync\fR,
186: followed by storing the characters,
187: followed by another \fBsync\fR.
188: .SH CAVEATS
189: \fBattach\fR
190: and the constructors should test if the file descriptor they
191: are given is open, but I can't figure out a portable way to do that.
192: .PP
193: There is no way to force atomic reads.
194: .PP
195: Unix does usually report failures of seek (e.g. on a tty) and
196: so a filebuf does not either.
197: .SH SEE ALSO
198: sbuf.pub(3C++)
199: sbuf.prot(3C++)
200: fstream(3C++)
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.