.\" '\" tep .\" to invoke 'tbl', 'eqn', 'pic' in the proper order .\" .\" @(#)filebuf.3 1.3 92/12/01 SMI; .\" .TH FILEBUF 3CC4 "18 June 1998" .\" .SH NAME filebuf \- buffer class for file I/O .SH SYNOPSIS .LP .nf .ft B #include .sp .5v typedef long streampos; typedef long streamoff; .sp .5v class ios : virtual public unsafe_ios, public stream_MT { public: enum open_mode { in = 0x01, // open for reading out = 0x02, // open for writing ate = 0x04, // seek to eof upon original open app = 0x08, // append mode: all additions at eof trunc = 0x10, // truncate file if already exists nocreate = 0x20, // open fails if file doesn't exist noreplace= 0x40 // open fails if file already exists }; enum seek_dir { beg=0, cur=1, end=2 }; // \fIsee \fBios\fR(3CC4)\fI for remainder ...\fB }; .sp .5v class filebuf : public streambuf { public: static const int openprot ; /* default protection for open */ filebuf() ; ~filebuf() ; filebuf(int f); filebuf(int f, char* p, int len) ; filebuf* attach(int f) ; filebuf* attach_unlocked(int); filebuf* close(); filebuf* close_unlocked(); int detach() ; int detach_unlocked(); int fd(); int is_open(); int is_open_unlocked(); filebuf* open(char *name, int omode, int prot=openprot) ; filebuf* open_unlocked(const char*, int, int=filebuf::openprot); streampos seekoff(streamoff, seek_dir, int omode) ; streampos seekpos(streampos, int omode) ; streambuf* setbuf(char* p, int len) ; int sync() ; }; .ft R .fi .\" .SH DESCRIPTION .LP The \fBfilebuf\fR class is a specialization of \fBstreambuf\fRs using a file as the source or destination of characters. Characters are fetched (input) from a file and consumed by (written to) a file. When the \fBfilebuf\fR is connected (\fIattached\fR) to an open file, the \fBfilebuf\fR is said to be \fIopen\fR; otherwise it is \fIclosed\fR. A file is opened by default with protection mode \fBfilebuf::openprot\fR, which is 0666. .LP If the attached file is seekable, the \fBfilebuf\fR allows seeks; for example, an ordinary disk file is seekable, the terminal is not. If the attached file allows reading (writing), the \fBfilebuf\fR allows fetching (storing); for example, standard input allows only reading, standard output allows only writing. Unlike C \fBstdio\fR, no seek is required between gets and puts to the same \fBfilebuf\fR. At least four characters of putback are initially allowed. .LP The basic \fBstreambuf\fR operations are as described in .BR sbufprot "(3CC4) and" .BR sbufpub (3CC4). The reserve area is allocated automatically if one is not supplied to a constructor or with a call to \fBsetbuf\fR (calls to \fBsetbuf\fR are usually honored). If the \fBfilebuf\fR is made unbuffered, each input and output character requires a system call. The get and put pointers act like a single pointer; conceptually, they are tied together. .LP A \fBfilebuf\fR operates on files via a Unix \fIfile descriptor\fR, a small integer passed in system calls. C stdio is not used. Note: Supplied file descriptors are not checked for validity. .\" .PP Several of the member functions are defined in two versions: an ``unsafe'' version (with suffix \fB_unlocked\fR) that is not protected against multi-threaded access; and a ``safe'' version (the default), that uses mutex locks to protect against simultaneous access by multiple threads. .PP .B "filebuf()" Creates a closed \fBfilebuf\fR. .TP .B "filebuf(f)" Creates an open \fBfilebuf\fR attached to file descriptor \fBf\fR, which is assumed to be open. .TP .B "filebuf(f, p, len)" Creates an open \fBfilebuf\fR attached to file descriptor \fBf\fR, which is assumed to be open. Uses the array of \fBlen\fR \fBchar\fRs beginning at \fBp\fR as the initial reserve area. If \fBp\fR is zero or \fBlen\fR is not greater than zero, the \fBfilebuf\fR is unbuffered. .\" .SS "Member Functions" .TP .B "filebuf* fb = fbuf.attach(f)" If \fBfbuf\fR is closed, connects it to file descriptor \fBf\fR, assumed to be open, and returns the address of \fBfbuf\fR. If \fBfbuf\fR is already open, ignores \fBf\fR and returns zero. This member is mt-safe. .TP .B "filebuf *fb = fbuf.attach_unlocked(f)" Functionally identical to .BR attach , except that it does not perform any mutex locks, and is thus not mt-safe. .TP .B "int i = fbuf.detach()" Flushes any waiting output to the file associated with the file descriptor, and disconnects the file descriptor from \fIf\fR. The file descriptor is returned. Applications which do not want the attached file descriptor to be closed by \fBclose()\fR should call this function before \fBclose()\fR. This member is mt-safe. .TP .B "int i = fbuf.detach_unlocked()" Functionally identical to .BR detach , except that it does not perform any mutex locks, and is thus not mt-safe. .TP .B "filebuf* fb = fbuf.close()" Flushes any pending output, unconditionally closes the file descriptor and closes \fBfbuf\fR. Returns zero on error, the address of \fBfbuf\fR otherwise. This member is mt-safe. .TP .B "filebuf* fb = fbuf.close_unlocked()" Functionally identical to .BR close , except that it does not perform any mutex locks, and is thus not mt-safe. .TP .B "int f = fbuf.fd()" Returns the file descriptor attached to \fBfbuf\fR, or \fBEOF\fR if \fBfbuf\fR is not open. .TP .B "int i = fbuf.is_open()" Returns non-zero if \fBfbuf\fR is open (connected to a file descriptor), zero otherwise. This member is mt-safe. .TP .B "int i = fbuf.is_open_unlocked()" Functionally identical to .BR is_open , except that it does not perform any mutex locks, and is thus not mt-safe. .TP .B "filebuf* fb = fbuf.open(name, mode, prot)" If \fBfbuf\fR is not already open, this function opens file \fBname\fR and connects its file descriptor to \fBfbuf\fR; otherwise it is an error. If the file does not exist, and \fBios::nocreate\fR is not set in \fBmode\fR, \fBopen\fR attempts to create the file with the protection bits specified in \fBprot\fR (with default value 0666). The \fBmode\fR parameter is a collection of bits from \fBios::open_mode\fR, described in .BR fstream (3CC4), which may be or'd together. This function returns the address of \fBfbuf\fR on success, zero on any failure. This member is mt-safe. .TP .B "filebuf* fb = fbuf.open_unlocked(name, mode, prot)" Functionally identical to .BR open , except that it does not perform any mutex locks, and is thus not mt-safe. .TP .B "streampos pos2 = fbuf.seekoff(off, dir, mode)" Moves the combined get/put pointer as described in .BR sbufpub (3CC4) by \fBoff\fR and \fBdir\fR, except that the \fBmode\fR parameter is ignored. If \fBfbuf\fR is not open, if the attached file does not support seeking, or if the seek cannot otherwise be performed (such as off either end of the file), the operation fails. \fBoff\fR is the relative offset to the place in the file specified by \fBdir\fR. Returns the new file position on success, \fBEOF\fR on failure. The position of the file in the event of an error is undefined. .TP .B "streampos pos2 = fbuf.seekpos(pos, mode)" Equivalent to the call \fBfbuf.seekoff((streamoff)pos, ios::beg, mode)\fR. The value of \fBpos\fR should be one obtained from a previous call to \fBseekoff\fR or \fBseekpos\fR, or the value zero representing the beginning of the file. See also .BR sbufpub (3CC4). .TP .B "streambuf* sb = fbuf.setbuf(p, len)" If \fBfbuf\fR is open and a reserve area has been allocated, no change is made and \fBsetbuf\fR returns zero. Otherwise, the new reserve area becomes the \fBlen\fR \fBchar\fRs beginning at the location pointed to by \fBp\fR, and the function returns the address of \fBfbuf\fR. If \fBp\fR is zero or \fBlen\fR is not greater than zero, there will be no reserve area and \fBfbuf\fR is unbuffered. .TP .B "int i = fbuf.sync()" Attempts to make the get/put pointer to agree (be synchronized) with the actual position of the attached file. This might involve flushing unwritten characters or backing up the file over characters already input. Returns zero on success, .B EOF on error. If it is necessary to ensure that a group of characters is written at the same time to a file, allocate a reserve area larger than the largest such group, .B sync just before storing the characters, then .Bsync again just afterward. .PD .5 .\" .SH "SEE ALSO" .LP .na .BR ios.intro (3CC4), .BR fstream (3CC4), .BR ios (3CC4), .BR sbufprot (3CC4), .BR sbufpub (3CC4), .BR stream_locker (3CC4), .BR stream_MT (3CC4), .TP .I C++ Library Reference .TP Chapter 3, "The Classic \fIiostream\fR Library", .TP Chapter 4, "Using Classic \fIiostreams\fR in a Multithreaded Environment." .\" .TZ ???? .\" .ad .SH "WARNINGS" .LP Unix does not usually report seek failures, so neither will \fBfilebuf\fR.