filebuf - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of the filebuf class.

~filebuf
public:~filebuf()

This is supported on AIX OS/400 z/OS

The filebuf destructor calls filebuf.close().

filebuf
Overload 1
public:filebuf(int fd, char* p, long l)

This is supported on AIX z/OS

Constructs a filebuf object that is attached to the file descriptor fd. The object is initialized to use the stream buffer starting at the position pointed to by p with length equal to l.

This function is available for 64-bit applications. The third argument is a long value.

Overload 2
public:filebuf(int fd)

This is supported on AIX OS/400 z/OS

Constructs a filebuf object that is attached to the file descriptor fd.

Overload 3
public:filebuf(int fd, char* p, int l)

This is supported on AIX OS/400 z/OS

Constructs a filebuf object that is attached to the file descriptor fd. The object is initialized to use the stream buffer starting at the position pointed to by p with length equal to l.

AIX and z/OS Considerations

This function is available for 32-bit applications. The third argument is an int value.

Overload 4
public:filebuf()

This is supported on AIX OS/400 z/OS

Constructs an initially closed filebuf object.

Attach Functions

attach

Attaches the filebuf object to the file descriptor or the file pointer.

Overload 1
public:filebuf* attach(FILE* fp)

This is supported on z/OS

Attaches the filebuf object to the file pointer fp. If the filebuf object is already open, attach() returns 0. Otherwise, attach() returns a pointer to the filebuf object.

z/OS Considerations
If you have a file pointer already opened, use this function to do the attach instead of using the file descriptor.
Overload 2
public:filebuf* attach(int fd)

This is supported on AIX OS/400 z/OS

Attaches the filebuf object to the file descriptor fd. If the filebuf object is already open or if fd is not open, attach() returns NULL. Otherwise, attach() returns a pointer to the filebuf object.

is_open
public:int is_open()

This is supported on AIX OS/400 z/OS

Returns a nonzero value if the filebuf object is attached to a file descriptor. Otherwise, is_open() returns zero.

Data members

openprot
public:static const int openprot

This is supported on AIX OS/400 z/OS

The default protection mode used when opening files.

in_start
protected:char* in_start

This is supported on AIX OS/400 z/OS

Data member.

lahead
protected:char lahead [ 2 ]

This is supported on AIX OS/400 z/OS

A variable used to store look-ahead characters during underflow processing.

last_seek
protected:streampos last_seek

This is supported on AIX OS/400 z/OS

Stream position last seeked to.

mode
protected:int mode

This is supported on AIX OS/400 z/OS

Open mode of the filebuf object.

opened
protected:char opened

This is supported on AIX OS/400 z/OS

A flag used to track whether the file is open. If the file is open, the value of this variable is 1. Otherwise it is 0.

xfd
protected:int xfd

This is supported on AIX OS/400 z/OS

The file descriptor of the file attached to the filebuf object.

Detach Functions

close
public:filebuf* close()

This is supported on AIX OS/400 z/OS

close() does the following:

  1. Flushes any output that is waiting in the filebuf object to be sent to the file
  2. Disconnects the filebuf object from the file
  3. Closes the file that was attached to the filebuf object.

If an error occurs, close() returns 0. Otherwise, close() returns a pointer to the filebuf object. Even if an error occurs, close() performs the second and third steps listed above.

detach
public:int detach()

This is supported on AIX OS/400 z/OS

Disconnects the filebuf object from the file without closing the file. If the filebuf object is not open, detach() returns -1. Otherwise, detach() flushes any output that is waiting in the filebuf object to be sent to the file, disconnects the filebuf object from the file, and returns the file descriptor.

File Pointer Functions

fp
public:FILE* fp()

This is supported on z/OS

Returns the file pointer that is attached to the filebuf object. If the filebuf object is not opened, fp() returns 0.

overflow
public:virtual int overflow(int = EOF)

This is supported on AIX OS/400 z/OS

Emptys an output buffer. Returns EOF when an error occurs. Returns 0 otherwise.

seekoff
public:virtual streampos seekoff(streamoff, ios::seek_dir, int)

This is supported on AIX OS/400 z/OS

Moves the file get/put pointer to the position specified by the ios::seek_dir argument with the offset specified by the streamoff argument. ios::seek_dir can have the following values:

seekoff() changes the position of the file get/put pointer to the position specified by the value ios::seek_dir + streamoff. The offset can be either positive or negative. seekoff() ignores the third argument.

If the filebuf object is attached to a file that does not support seeking, or if the value of ios::seek_dir + streamoff specifies a position before the beginning of the file, seekoff() returns EOF and the position of the file get/put pointer is undefined. Otherwise, seekoff() returns the new position of the file get/put pointer.

z/OS Considerations

You can use relative byte offsets when seeking from ios::cur or ios::end. You can use relative byte offsets when seeking from ios::beg if either of the following conditions are true:

  • The file is not a variable record format file, and is opened for binary I/O.
  • The file is a variable record format file, and is opened for binary I/O with the byteseek option. The byteseek option is enabled for a specific file if the byteseek fopen() option is passed when the file is opened. The byteseek option can also be enabled for all files if you set the _EDC_BYTESEEK environment variable.

When seeking from ios::beg in text files, encoded offsets are used. You can only seek to an offset value returned by a previous call to seekoff(), and attempting to calculate a new position based on an encoded offset value results in undefined behaviour.

sync
public:virtual int sync()

This is supported on AIX OS/400 z/OS

Attempts to synchronize the get/put pointer and the file get/put pointer. sync() may cause bytes that are waiting in the stream buffer to be written to the file, or it may reposition the file get/put pointer if characters that have been read from the file are waiting in the stream buffer. If it is not possible to synchronize the get/put pointer and the file get/put pointer, sync() returns EOF. If they can be synchronized, sync() returns zero.

underflow
public:virtual int underflow()

This is supported on AIX OS/400 z/OS

Fills an input buffer. Returns EOF when an error occurs or the end of the input is reached. Returns the next character otherwise.

Open Functions

z/OS Considerations

The prot parameter is ignored.

open

Opens the file with the name name and attaches the filebuf object to it. If name does not already exist and the open mode om does not equal ios::nocreate, open() tries to create it with protection mode equal to prot. The default value of prot is filebuf::openprot. An error occurs if the filebuf object is already open. If an error occurs, open() returns 0. Otherwise, open() returns a pointer to the filebuf object.

The default protection mode for the filebuf class is S_IREAD|S_IWRITE. If you create a file with both S_IREAD and S_IWRITE set, the file is created with both read and write permission. If you create a file with only S_IREAD set, the file is created with read-only permission, and cannot be deleted later with the stdio.h library function remove(). S_IREAD and S_IWRITE are defined in sys\stat.h.

Overload 1
public:filebuf*
  open( const char* name,
        int om,
        int prot = openprot )

This is supported on AIX z/OS

Overload 2
public:filebuf*
  open( const char* name,
        int om,
        int prot = openprot,
        _CCSID_T ccsid = _CCSID_T ( 0 ) )

This is supported on OS/400

Overload 3
public:filebuf*
  open( const char* name,
        const char* attr,
        int om,
        int prot = openprot )

This is supported on z/OS

You can use the attr parameter to specify additional file attributes, such as lrecl or recfm. All the parameters documented for the fopen() function are supported, with the exception of type=record.

Overload 4
public:filebuf* open(const char* name, int om, _CCSID_T ccsid)

This is supported on OS/400

Query Functions

fd
public:int fd()

This is supported on AIX OS/400 z/OS

Returns the file descriptor that is attached to the filebuf object. If the filebuf object is closed, fd() returns EOF.

last_op
protected:int last_op()

This is supported on AIX OS/400 z/OS

Indicates whether the last operation was a read(get) or a write(put) operation.

Stream Buffer Functions

setbuf
Overload 1
public:virtual streambuf* setbuf(char* p, long len)

This is supported on AIX z/OS

Sets up a stream buffer with length in bytes equal to len, beginning at the position pointed to by p. setbuf() does the following:

  • If p is 0 or len is nonpositive, setbuf() makes the filebuf object unbuffered.
  • If the filebuf object is open and a stream buffer has been allocated, no changes are made to this stream buffer, and setbuf() returns NULL.
  • If neither of these cases is true, setbuf() returns a pointer to the filebuf object.

This function is available for 64-bit applications. The second argument is a long value

Overload 2
public:virtual streambuf* setbuf(char* p, int len)

This is supported on AIX OS/400 z/OS

Sets up a stream buffer with length in bytes equal to len, beginning at the position pointed to by p. setbuf() does the following:

  • If p is 0 or len is nonpositive, setbuf() makes the filebuf object unbuffered.
  • If the filebuf object is open and a stream buffer has been allocated, no changes are made to this stream buffer, and setbuf() returns NULL.
  • If neither of these cases is true, setbuf() returns a pointer to the filebuf object.
AIX and z/OS Considerations

This function is available for 32-bit applications. The second argument is an int value