Return to filebuf.3 CVS log

Up to [Research Unix] / researchv10dc / man / mana

Annotation of researchv10dc/man/mana/filebuf.3, revision 1.1

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.