fstream - Oracle Solaris Studio 12.4 Man Pages

Language:

fstream(3CC4)

Name

fstream - 文件 I/O 的流类

Synopsis

 
#include <fstream.h>
typedef long streampos;
typedef long streamoff;
class unsafe_ios {
public:
     // exported types
        // stream status bits
        enum io_state   {
            goodbit  = 0x00,        // no bit set: all is ok
            eofbit   = 0x01,        // at end of file
            failbit  = 0x02,        // last I/O operation failed
            badbit   = 0x04,        // invalid operation attempted
            hardfail = 0x80         // unrecoverable error
            };

        // stream operation mode
        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
        };

        // stream seek direction
        enum seek_dir { beg=0, cur=1, end=2 };

     // see ios(3CC4) for remainder ...
};
class  filebuf : public streambuf {
     // see filebuf(3CC4) ...
};
class unsafe_fstreambase : virtual public unsafe_ios {
        unsafe_fstreambase();
        unsafe_fstreambase(const char*, int, int = filebuf::openprot);
        unsafe_fstreambase(int);
        unsafe_fstreambase(int _f, char*, int);
        ~unsafe_fstreambase();

        void open(const char*, int, int = filebuf::openprot);
        void attach(int);
        void close();
        void setbuf(char*, int);
        filebuf* rdbuf();
};
class fstreambase : virtual public ios, public unsafe_fstreambase {
public:
        fstreambase() ;

        fstreambase(const char*, int, int=filebuf::openprot) ;
        fstreambase(int) ;
        fstreambase(int, char*, int) ;

        void    open(const char*, int, int=filebuf::openprot) ;
        void     attach(int);
        void     close() ;
        void     setbuf(char*, int) ;
        filebuf* rdbuf();
};
class ifstream : public fstreambase, public istream {
public:
     // exported functions
     void open(const char* fname, int omode=ios::in,
        int prot=filebuf::openprot);
     filebuf* rdbuf();
public:
     // exported constructors
     ifstream();
     ifstream(const char* fname, int omode=ios::in,
        int prot=filebuf::openprot);
     ifstream(int fileno);
     ifstream(int fileno, char* buf, int size);
};
class ofstream : public fstreambase, public ostream {
public:
     // exported functions
     void open(const char* fname, int omode=ios::out,
        int prot=filebuf::openprot);
     filebuf* rdbuf();
public:
     // exported constructors
     ofstream();
     ofstream(const char* fname, int omode=ios::out,
        int prot=filebuf::openprot);
     ofstream(int fileno);
     ofstream(int fileno, char* buf, int size);
};
class fstream : public fstreambase, public iostream {
public:
     // exported functions
     void open(const char * fname, int omode,
        int prot=filebuf::openprot);
     filebuf* rdbuf();
public:
     // exported constructors
     fstream();
     fstream(const char* fname, int omode,
        int prot=filebuf::openprot);
     fstream(int fileno);
     fstream(int fileno, char* buf, int size);
};

Description

类 ifstream、ofstream 和 fstream 分别是类 istream、ostream 和 iostream 的特例，适用于使用文件的 I/O。也就是说，关联的 streambuf 是一个 filebuf。

辅助类 fstreambase 是一个实现细节，主要是提供了一组通用函数。不再进一步对其进行讨论。

我们将把这些类放在一起讨论，使用表示法 Xstream 以相同的方式引用 ifstream、ofstream 和 fstream 中的任何一个。

fstream、ifstream 和 ofstream 类型的对象使用互斥锁针对多个线程的同时访问提供保护。类 unsafe_fstreambase 可用来派生不需要多线程安全性的新文件类。所提供的三个文件类的基类是类 fstreambase，它使用互斥锁提供多线程安全性。

至于其他 iostream 类，可以通过调用类 stream_MT 定义的成员函数 set_safe_flag 来禁用互斥锁定。

构造函数

Xstream(): 构造未连接到任何文件的关闭 Xstream。
Xstream(name, mode, prot): 构造一个 Xstream 并打开文件 name，将 mode 用于打开模式位，将 prot 用于文件保护位。（请参见下文中的 open。）缺省打开模式对于 ifstream 来说是 input（输入），对于 ofstream 来说是 output（输出）。缺省保护是 filebuf::openprot，即 0666。任何错误都将存储在 Xstream 错误状态中；请参见 ios(3CC4)。
Xstream(f): 构造一个附加到文件描述符 f（该文件描述符必须已打开）的 Xstream。（它不针对此条件进行测试。）
Xstream(f, ptr, len): 构造一个附加到文件描述符 f（该文件描述符必须已打开）的 Xstream。（它不针对此条件进行测试。）filebuf 将使用开头位于 ptr 指向的位置的 len char 作为缓冲区（保留区）。如果 ptr 为零或者 len 不大于零，则不会有储存区并且 fbuf 是无缓冲的。

成员函数

fs.attach(f)

将 fs 连接到打开的文件描述符 f。如果 fs 已连接到某个文件，则会忽略请求，并且将在 fs 错误状态中设置 ios::failbit。

fs.close()

关闭关联的 filebuf 并断开文件与 fs 的连接。如果 filebuf 的 close 调用成功，则会清除错误状态；否则将在 fs 错误状态中设置 ios::failbit。

fs.open(name, mode, prot)

打开文件 name 并将其文件描述符连接到 fs；如果文件不存在，并且未在 mode 中设置 ios::nocreate，则 open 将尝试使用 prot 中指定的保护位（缺省值为 0666）创建文件。mode 参数是来自 ios::open_mode 的位的集合，可以通过 or 运算符连接在一起。

ios::app: 最初查找到文件末尾。任何后续写入将始终附加到文件末尾。此标志暗示 ios::out。
ios::ate: 最初查找到文件末尾。此标志不暗示 ios::out，只是在文件末尾开始操作。
ios::in: 打开文件用于输入。如果打开某个文件进行输入并且该文件不存在，则不会创建该文件。ifstream 的构造或打开始终暗示该位，这意味着不需要设置该位。当为 fstream 设置了此参数时，表示在可能时应当允许输入。当为 ofstream 设置了此参数时，表示当文件处于打开状态时不应当截断文件。
ios::out: 打开文件用于输出。ofstream 的构造或打开始终暗示该位，这意味着不需要设置该位。当为 fstream 设置了此参数时，表示在可能时应当允许输出。可以为 ifstream 设置，但不允许输出到文件。
ios::trunc: 如果文件存在，则在打开该文件时会将其截断到零长度。当指定或暗示了 ios::out 并且未指定 ios::ate 或 ios::app 时，将暗示该位。
ios::nocreate: 如果文件尚未存在，则不会创建该文件；在这种情况下，open 将失败。
ios::noreplace: 文件不应当已存在；如果已存在，则 open 将失败。只有当打开文件进行输出时，该位才有意义。

filebuf* fb = fs.rdbuf()

返回指向与 fs 关联的 filebuf 的指针。这与此函数的基类版本相同，但是返回类型比较特别，是一个 filebuf。

fs.setbuf(ptr, len)

这提供位于 ptr 的 len char 的缓冲区作为保留区。它调用 setbuf 的 filebuf 版本，并使用其返回值调整 fs 的错误状态。也就是说，它在成功时清除错误状态，在发生错误时设置 ios::failbit。