DEC C++
Class Library Reference Manual


Previous Contents Index

The output is a,a,10.
#2

#include <string.hxx> 
#include <iostream.hxx> 
 
void print_name(String &name) 
{ 
   cout << lock << "Hello, " << name << endl << unlock; 
} 

This synchronizes access to the cout object so that the "Hello, ", name, and new-line character are written to cout as a single unit. If you do not use the lock and unlock manipulators in this example, another thread could possibly insert its own text into cout in the midst of your output.


HEADER

#include <iomanip.hxx>

Alternative Header

#include <iomanip.h>


DECLARATIONS


 
SMANIP(long)       resetiosflags(long); 
SMANIP(long)       setiosflags(long); 
SMANIP(int)        setfill(int); 
SMANIP(int)        setprecision(int); 
SMANIP(int)        setw(int w); 
 
SMANIPREF(Mutex)   lock(Mutex &m) 
SMANIPREF(Mutex)   unlock(Mutex &m) 


FUNCTIONS

These functions are used for extending the iostream package with user-defined parameterized manipulators.

SMANIP(long) resetiosflags(long x)

In the stream (ios or a stream derived from ios), clears the format flags denoted by x.

SMANIP(int) setfill(int x)

Sets the fill character to be the value specified by x. The fill character is a data member of the ios class; however, setting it with this function affects only output streams.

SMANIP(long) setiosflags(long x)

In the stream (ios or a stream derived from ios), turns on the format flags denoted by x. If you are setting a flag that is part of a collection (for example, basefield), note that this manipulator does not clear the other flags in the collection.

SMANIP(int) setprecision(int x)

Sets the variable that controls the number of digits inserted by the floating-point inserter to be x. This variable is a data member of the ios class; however, setting it with this function affects only output streams.

SMANIP(int) setw(int w)

In the stream (ios or a stream derived from ios), sets the field width of the stream to w.

SYNCHRONIZING ACCESS TO USER-DEFINED STREAM OBJECTS

The following parameterized manipulators are for use in synchronizing access to user-defined stream objects. To use these manipulators, you must first define a Mutex object, which you then pass to the manipulator. The association of a Mutex object with a stream object is not enforced by the iostream package. This association is enforced only by you, the programmer. Refer to Chapter 6 for information on the Mutex class.

SMANIPREF(Mutex) lock(Mutex &m)

Locks the recursive Mutex represented by m.

SMANIPREF(Mutex) unlock(Mutex &m)

Unlocks the recursive Mutex represented by m.

Examples

#1

char c; 
cin >> resetiosflags(ios::skipws) 
    >> c 
    >> setiosflags(ios::skipws); 

Turns off the flag (resets it to 0) that tells the extractor (>>) to skip leading white space and then turns that flag back on again (sets it to 1).

#2

cout.fill(*) 
cout.setf(ios::left,ios::adjustfield); 
cout << setw(6) << 23 << "," ; 
cout.fill(%); 
cout.setf(ios::right,ios::adjustfield); 
cout << setw(4) << 34 << "\n" ; 

Places padding characters (specified by the fill state variable) after the first number and before the second number. The output is 23****,%%34.

#3

#include <string.hxx> 
#include <fstream.hxx> 
#include <mutex.hxx> 
#include <iomanip.hxx> 
 
main () 
{ 
   String name("Henry"); 
   void print_name (String &, ostream &, Mutex &); 
 
   ofstream mystream(1); 
   Mutex mystream_lock; 
 
   print_name(name, mystream, mystream_lock); 
   return 0; 
} 
 
   void print_name(String &name, ostream &stream, Mutex &stream_lock) 
{ 
      stream << lock(stream_lock) << "Hello, " << name << endl 
             << unlock(stream_lock); 
} 

This example associates aMutex object with a stream object to synchronize access to the stream. The Mutex is locked before using the stream and then unlocked afterwards. For the synchronization to work properly, each thread that uses this stream must perform the same lock/unlock sequence with the same Mutex.


SEE ALSO

IMANIP(TYPE) class
IOMANIP(TYPE) class
OMANIP(TYPE) class
SMANIP(TYPE) class

filebuf class

Provides a data buffer abstraction for input/output facilities through file descriptors.

HEADER

#include <fstream.hxx>

Alternative Header

#include <fstream.h>


DECLARATION


class filebuf: public streambuf 
{ 
public: 
    static const int    openprot; 
 
                        filebuf(); 
                        filebuf(int fd); 
                        filebuf(int fd, char *p, int len); 
                        ~filebuf(); 
 
    filebuf             *attach(int fd); 
    filebuf             *close(); 
    int                 fd(); 
    int                 is_open(); 
    filebuf             *open(const char *name, int mode, int prot = openprot); 
 
    virtual int         overflow(int = EOF); 
    virtual streampos   seekoff(streamoff, seek_dir, int mode); 
    virtual streampos   seekpos(streampos, int mode); 
    virtual streambuf   *setbuf(char *p, int len); 
    virtual int         sync(); 
    virtual int         underflow(); 
}; 


DESCRIPTION

This class specializes the streambuf class to use a file as a repository of characters. Writing to the file consumes characters; reading from the file produces characters. Files that allow searches are said to be seekable. When a file is readable and writable, the filebuf object permits character insertion and extraction.

If your program expects a buffer to be allocated when none was allocated, then the iostream package allocates a default buffer with a length specified by BUFSIZ as defined in stdio.h. The package then issues the following warning:


Warning; a null pointer to streambuf was passed to ios::init() 


DATA MEMBER

const int openprot = 0644

Provides default protection for the open() function. (For an explanation of the file protection, see the chmod(1) reference page.)

CONSTRUCTORS AND DESTRUCTORS

filebuf()

Constructs a filebuf object that is initially closed.

filebuf(int fd)

Constructs a filebuf object connected to file descriptor fd.

filebuf(int fd, char *p, int len)

Constructs a filebuf object connected to file descriptor fd, which is initialized to use the reserve area (buffer) starting at p and containing len bytes.

~filebuf()

Deletes a filebuf object.

MEMBER FUNCTIONS

filebuf *attach(int fd)

Connects the filebuf object to an open file whose descriptor is passed through the fd argument. It normally returns a reference to the filebuf object, but returns 0 if the filebuf object is connected to an open file.

filebuf *close()

Flushes any waiting output, closes the file descriptor, and disconnects a filebuf object. Unless an error occurs, the filebuf object's error state will be cleared. The close() function returns the address of the filebuf object unless errors occur, in which case this function returns 0. Even if errors occur, close() leaves the file descriptor and filebuf object closed.

int fd()

Returns the file descriptor associated with a filebuf object. If the filebuf object is closed, fd returns EOF.

int is_open()

Returns a nonzero value when a filebuf object is connected to a file descriptor; otherwise, it returns 0.

filebuf *open(const char *name, int mode, int prot)

Opens a file with the name specified by name and connects a filebuf object to it. If the file does not exist, the function tries to create it with the protection mode prot unless ios::nocreate is specified in mode. By default, prot is filebuf::openprot.

The function fails if the filebuf object is open. The open() function normally returns the address of the filebuf object, but returns 0 if an error occurs. The members of open_mode are bits that may be joined together by or (because this joining takes an int, open() takes an int rather than an open_mode argument). For an explanation of the meanings of these bits in open_mode, see the Enumerated Types section for the ios class.

virtual int overflow(int c)

Called to consume characters in classes derived from streambuf. If c is not EOF, this function must also either save c or consume it. Although it can be called at other times, this function usually is called when the put area is full and an attempt is being made to store a new character. The normal action is to consume the characters between pbase() and pptr(), call setp() to establish a new put area, and (if c != EOF) store c using sputc(). A call to overflow(c) should return EOF to indicate an error; otherwise, it should return something else.

virtual streampos seekoff(streamoff off, seek_dir dir, int mode)

Moves the get pointer, put pointer, or both as designated by the off and dir arguments. It may fail if the file does not support seeking, or if the attempted motion is otherwise invalid (for example, attempting to seek a position before the beginning of the file). The off argument is interpreted as a count relative to the place in the file specified by dir. The mode argument is ignored. A call to seekoff() returns the new position or EOF if a failure occurs. After a failure, the position of the file is undefined.

virtual streampos seekpos(streampos pos, int mode)

Moves the file to a position pos. The mode argument is ignored. The function normally returns pos but it returns EOF on failure.

virtual streambuf *setbuf(char *p, int len)

Sets up the reserve area as the number of bytes specified in the second argument, beginning at the pointer specified in the first argument. If the pointer is null, or the number of bytes is less than 1, the filebuf object is unbuffered. This function normally returns a pointer to the filebuf object; however, if the filebuf object is open and a buffer is allocated, then no changes are made to the reserve area and to the buffering status, and setbuf() returns 0.

virtual int sync()

Tries to get the state of the get pointer, the put pointer, or both, to agree (synchronize) with the state of the file to which the filebuf object is connected. This means that the function may write characters to the file if some of the characters have been buffered for output, or the function may try to reposition (seek) the file if characters have been read and buffered for input. Normally sync() returns 0, but it returns EOF if synchronization is not possible.

When certain characters must be written together, the program should use setbuf() (or a constructor) to ensure that the reserve area is at least as large as the number of characters to be written together. Your program can then call sync(), store the characters, and then call sync() once again.

virtual int underflow()

Called in classes derived from streambuf to supply characters for fetching; that is, to create a condition in which the get area is not empty. If the function is called when characters occupy the get area, it should create a nonempty area and return the next character (which it should also leave in the get area). If no more characters are available, underflow() should return EOF and leave an empty get area.

SEE ALSO

ios class
streambuf class

fstream class

Supports formatted and unformatted input from and output to files.

HEADER FILE

#include <fstream.hxx>

Alternative Header

#include <fstream.h>


DECLARATION


class fstream: public iostream 
{ 
public: 
                 fstream(); 
                 fstream(const char *name, int mode, 
                     int prot = filebuf::openprot); 
                 fstream(int fd); 
                 fstream(int fd, char *p, int len); 
                 ~fstream(); 
 
    void         attach(int fd); 
    void         close(); 
    void         open(const char *name, int mode, 
                     int prot = filebuf::openprot) ; 
    filebuf      *rdbuf(); 
    void         setbuf(char *p, int len); 
}; 


DESCRIPTION

This class specializes the iostream class to files by using a filebuf object to do the input and output. Your program can perform common operations, such as opening and closing files, without explicitly mentioning filebuf objects.


CONSTRUCTORS AND DESTRUCTORS

fstream()

Constructs an unopened fstream object.

fstream(int fd)

Constructs an fstream object connected to the file whose descriptor is passed through the fd argument. The file must be open.

fstream(int fd, char *p, int len)

Constructs an fstream object connected to a file whose descriptor is passed through the fd argument, and also initializes the associated filebuf object to use the len bytes starting at p as the reserve area. If p is null or len is 0, the filebuf object is unbuffered.

fstream(const char *name, int mode, int prot)

Constructs an fstream object and opens the file specified by the name argument. The mode and prot arguments specify the file open mode and protection. By default, prot is filebuf::openprot. If the open action fails, the error state (io_state) of the constructed fstream object indicates failure.

~fstream()

Deletes an fstream object.

MEMBER FUNCTIONS

void attach(int fd)

Connects an fstream object to a file whose descriptor is passed through the fd argument. A failure occurs when the fstream object is connected to a file, in which case ios::failbit is set in the filebuf object's error state.

void close()

Closes any associated filebuf object and consequently breaks the connection of the fstream object to the file. The error state of the fstream object is cleared except on failure. A failure occurs when the call to the filebuf object's close() function fails.

void open(const char *name, int mode, int prot)

Opens a file with the file name specified by name and connects the fstream object to it. If the file does not exist, the function tries to create it with the protection specified by the prot argument unless ios::nocreate is set. By default, prot is filebuf::openprot.

Failure occurs if the fstream object is open or when the call to the filebuf object's open() function fails, in which case ios::failbit is set in the filebuf object error state. The members of open_mode are bits that may be joined together by or (because this joining takes an int, open() takes an int rather than an open_mode argument). For an explanation of the meanings of these bits in open_mode, see the Enumerated Types section for the ios class.

filebuf *rdbuf()

Returns a pointer to the filebuf object associated with the fstream object. This function has the same meaning as ios::rdbuf(), but has a different type.

void setbuf(char *p, int len)

Calls the associated filebuf object setbuf() function to request space for a reserve area. A failure occurs if the filebuf object is open or if the call to rdbuf()->setbuf fails for any other reason.

IAPP(TYPE) class

For an istream object, declares predefined parameterized applicators.

HEADER FILE

#include <iomanip.hxx>

Alternative Header

#include <iomanip.h>


COMPILE-TIME PARAMETER

TYPE---The type of the istream object. It must be an identifier.

DECLARATION


class IAPP(TYPE) 
{ 
public: 
    IAPP(TYPE)(istream &(*f)(istream &, TYPE)); 
    IMANIP(TYPE) operator()(TYPE a); 
}; 


CONSTRUCTOR

IAPP(TYPE) (istream &(*f) (istream &, TYPE))

Creates an applicator; *f is the left operand of the insertion operator.

OPERATOR

IMANIP(TYPE) operator () (TYPE a)

Casts an object of type a into a manipulator function for an istream object.

SEE ALSO

IMANIP(TYPE) class

ifstream class

Supports formatted and unformatted input from files.

HEADER FILE

#include <fstream.hxx>

Alternative Header

#include <fstream.h>


DECLARATION


class ifstream: public istream 
{ 
public: 
                ifstream(); 
                ifstream(const char *name, int mode = ios::in, 
                     int prot = filebuf::openprot); 
                ifstream(int fd); 
                ifstream(int fd, char *p, int len); 
                ~ifstream(); 
 
    void        attach(int fd); 
    void        close(); 
    void        open(const char *name, int mode = ios::in, 
                     int prot = filebuf::openprot); 
    filebuf     *rdbuf(); 
    void        setbuf(char *p, int len); 
}; 


DESCRIPTION

This class specializes the istream class to files by using a filebuf object to do the input. Your program can perform common operations, such as opening and closing files, without explicitly mentioning filebuf objects.


CONSTRUCTORS AND DESTRUCTORS

ifstream()

Constructs an unopened ifstream object.

ifstream(int fd)

Constructs an ifstream object connected to a file whose descriptor is passed through the fd argument. The file must already be open.

ifstream(int fd, char *p, int len)

Constructs an ifstream object connected to a file whose descriptor is passed through the fd argument, and also initializes the associated filebuf object to use the len bytes starting at p as the reserve area. If p is null or len is 0, the filebuf object is unbuffered.

ifstream(const char *name, int mode, int prot)

Constructs an ifstream object and opens the file with the file name specified by name. The mode and prot arguments specify the file open mode and protection. By default, prot is filebuf::openprot. If the open fails, the error state (io_state) of the constructed ifstream object indicates failure.

~ifstream()

Deletes an ifstream object.

MEMBER FUNCTIONS

void attach(int fd)

Connects an ifstream object to a file whose descriptor is passed through the fd argument. A failure occurs when the ifstream object is connected to a file, in which case ios::failbit is set in the ifstream object error state.

void close()

Closes any associated filebuf object and consequently breaks the connection of the ifstream object to the file. The error state of the fstream object is cleared except on failure. A failure occurs when the call to the filebuf object's close() function fails.

void open(const char *name, int mode, int prot)

Opens a file specified by the name argument and connects the ifstream object to it. If the file does not exist, the function tries to create it with the protection specified by the prot argument unless ios::nocreate is set. By default, prot is filebuf::openprot.

Failure occurs if the ifstream object is open or when the call to the filebuf object open() function fails, in which case ios::failbit is set in the filebuf object error state. The members of open_mode are bits that may be joined together by or (because this joining takes an int, open() takes an int rather than an open_mode argument). For an explanation of the meanings of these bits in open_mode, see the Enumerated Types section for the ios class.

filebuf *rdbuf()

Returns a pointer to the filebuf object associated with the ifstream object. This function has the same meaning as ios::rdbuf() but has a different type.

void setbuf(char *p, int len)

Calls the associated filebuf object setbuf() function to request space for a reserve area. A failure occurs if the filebuf object is open or if the call to rdbuf()->setbuf fails for any other reason.

IMANIP(TYPE) class

For an istream object, declares the predefined parameterized manipulators and provides macros for user-defined parameterized manipulators.

HEADER FILE

#include <iomanip.hxx>

Alternative Header


Previous Next Contents Index