United States

Compaq C++

# Compaq 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 a `Mutex` 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 C Run-Time Library Reference Manual.)

## 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.

Previous | Next | Contents | Index

privacy and legal statement