.\" ident @(#)basic_ifstream.3 .\" Standard Template Library .\" $$RW_INSERT_HEADER "slyrs.man" .TH basic_ifstream 3C++ "02 Apr 1998" "Rogue Wave Software" "-" .ce2 Standard C++ Library Copyright 1998, Rogue Wave Software, Inc. .SH NAME \f2basic_ifstream\fP, \f2ifstream\fP, \f2wifstream\fP \ - Supports reading from named files or other devices associated with a file descriptor. .SH SYNOPSIS .br #include .br template > .br class basic_ifstream .br : public basic_istream .SH DESCRIPTION The template class basic_ifstream supports reading from named files or other devices associated with a file descriptor. It uses a basic_filebuf object to control the associated sequences. It inherits from basic_istream and can therefore use all the formatted and unformatted input functions. .SH INTERFACE .br template > .br class basic_ifstream .br : public basic_istream { .br .br public: .br .RE .RS 1 typedef basic_ios ios_type; .RE .RS 0 .RE .RS 1 typedef traits traits_type; .br typedef charT char_type; .br typedef typename traits::int_type int_type; .br typedef typename traits::pos_type pos_type; .br typedef typename traits::off_type off_type; .RE .RS 0 .RE .RS 1 basic_ifstream(); .RE .RS 5 .RE .RS 1 explicit basic_ifstream(const char *s, .RE .RS 25 ios_base::openmode mode = .br ios_base::in, .br long protection = 0666); .RE .RS 0 .RE .RS 1 explicit basic_ifstream(int fd); .br basic_ifstream(int fd, char_type* buf, int len); .RE .RS 0 .RE .RS 1 virtual ~basic_ifstream(); .RE .RS 0 .RE .RS 1 basic_filebuf *rdbuf() const; .br bool is_open(); .br void open(const char *s, ios_base::openmode mode = .RE .RS 11 ios_base::in, long protection = 0666); .RE .RS 0 .RE .RS 1 void close(); .RE .RS 0 .br }; .SH TYPES .br char_type .RE .RS 3 The type \f2char_type\fP is a synonym for the template parameter \f2charT\fP. .RE .br ifstream .RE .RS 3 The type \f2ifstream\fP is an instantiation of class \f2basic_ifstream\fP on type \f2char\fP: \f2typedef basic_ifstream ifstream;\fP .RE .br int_type .RE .RS 3 The type \f2int_type\fP is a synonym of type \f2traits::in_type\fP. .RE .br ios_type .RE .RS 3 The type\f2 ios_type\fP is an instantiation of class \f2basic_ios\fP on type \f2charT\fP. .RE .br off_type .RE .RS 3 The type \f2off_type\fP is a synonym of type \f2traits::off_type\fP. .RE .br pos_type .RE .RS 3 The type \f2pos_type\fP is a synonym of type \f2traits::pos_type\fP. .RE .br traits_type .RE .RS 3 The type \f2traits_type\fP is a synonym for the template parameter \f2traits\fP. .RE .br wifstream .RE .RS 3 The type \f2wifstream\fP is an instantiation of class \f2basic_ifstream\fP on type \f2wchar_t\fP: \f2typedef basic_ifstream wifstream;\fP .RE .SH CONSTRUCTORS .br basic_ifstream(); .RE .RS 3 Constructs an object of class basic_ifstream, initializing the base class basic_istream with the associated file buffer, which is initialized by calling the \f2basic_filebuf\fP constructor \f2basic_filebuf()\fP. After construction, a file can be attached to the basic_ifstream_object by using the \f2open\fP member function. .RE .br basic_ifstream(const char* s, .RE .RS 14 ios_base::openmode mode= ios_base::in, .br long protection= 0666); .RE .RS 3 Constructs an object of class basic_ifstream, initializing the base class basic_istream with the associated file buffer, which is initialized by calling the \f2basic_filebuf\fP constructor \f2basic_filebuf()\fP. The constructor then calls the open function \f2open(s,mode,protection)\fP in order to attach the file, whose name is pointed to by \f2s\fP, to the basic_ifstream object. The third argument \f2protection\fP holds file permissions. It does not appear in the Standard C++ description and is included as an extension. It determines the file read/write/execute permissions under UNIX. It is more limited under DOS since files are always readable and do not have special execute permission. .RE .RE .RS 0 explicit basic_ifstream(int fd); .RE .RS 3 Constructs an object of class basic_ifstream, initializing the base class basic_istream with the associated file buffer, which is initialized by calling the \f2basic_filebuf\fP constructor \f2basic_filebuf()\fP. The constructor then calls the \f2basic_filebuf\fP open function \f2open(fd)\fP in order to attach the file descriptor \f2fd\fP to the basic_ifstream object. This constructor is not described in the C++ standard, and is included as an extension in order to manipulate pipes, sockets, or other UNIX devices that can be accessed through file descriptors. If the function fails, it sets \f2ios_base::failbit.\fP .RE .br basic_ifstream(int fd, char_type* buf,int len); .RE .RS 3 Constructs an object of class basic_ifstream, initializing the base class basic_istream with the associated file buffer, which is initialized by calling the \f2basic_filebuf\fP constructor \f2basic_filebuf()\fP. The constructor then calls the \f2basic_filebuf\fP open function \f2open(fd)\fP in order to attach the file descriptor \f2fd\fP to the basic_ifstream object. The underlying buffer is then replaced by calling the \f2basic_filebuf\fP member function \f2setbuf\fP with parameters \f2buf\fP and \f2len\fP. This constructor is not described in the C++ standard, and is included as an extension in order to manipulate pipes, sockets, or other UNIX devices that can be accessed through file descriptors. It also maintains compatibility with the old iostreams library. If the function fails, it sets \f2ios_base::failbit.\fP .RE .SH DESTRUCTORS .br virtual ~basic_ifstream(); .RE .RS 3 Destroys an object of class \f2basic_ifstream\fP. .RE .SH MEMBER FUNCTIONS .br void .br close(); .RE .RS 3 Calls the associated \f2basic_filebuf\fP function \f2close()\fP and if this function fails, it calls the \f2basic_ios\fP member function \f2setstate(failbit)\fP. .RE .br bool .br is_open(); .RE .RS 3 Calls the associated \f2basic_filebuf\fP function \f2is_open()\fP and returns its result. .RE .br void .br open(const char* s,ios_base::openmode = .RE .RS 4 ios_base::in, long protection = 0666); .RE .RS 3 Calls the associated \f2basic_filebuf\fP function \f2open(s,mode,protection)\fP. If this function fails opening the file, it calls the \f2basic_ios\fP member function \f2setstate(failbit)\fP. The third argument \f2protection\fP holds file permissions. It does not appear in the Standard C++ description and is included as an extension. It determines the file read/write/execute permissions under UNIX. It is more limited under DOS since files are always readable and do not have special execute permission. .RE .RE .RS 0 basic_filebuf* .br rdbuf() const; .RE .RS 3 Returns a pointer to the \f2basic_filebuf\fP associated with the stream. .RE .SH EXAMPLE .br // .br // stdlib/examples/manual/ifstream.cpp .br // .br #include .br #include .br #include .br .br void main ( ) .br { .RE .RS 1 using namespace std; .RE .RS 0 .RE .RS 1 long l= 20; .br const char *ntbs="Le minot passait la piece a frotter"; .br char c; .br char buf[50]; .RE .RS 0 .br try { .br .RE .RS 2 // create a read/write file-stream object on char .br // and attach it to an ifstream object .RE .RS 1 ifstream in("ifstream.out",ios_base::in | .RE .RS 13 ios_base::out | ios_base::trunc); .RE .RS 0 .RE .RS 2 // tie the ostream object to the ifstream object .RE .RS 1 ostream out(in.rdbuf()); .RE .RS 0 .RE .RS 2 // output ntbs in out .RE .RS 1 out << ntbs << endl; .RE .RS 0 .RE .RS 2 // seek to the beginning of the file .RE .RS 1 in.seekg(0); .RE .RS 0 .RE .RS 2 // output each word on a separate line .RE .RS 1 while ( in.get(c) ) .RE .RS 3 { .RE .RS 4 if ( char_traits::eq(c,' ') ) .RE .RS 5 cout << endl; .RE .RS 4 else .RE .RS 5 cout << c; .RE .RS 3 } .RE .RS 1 cout << endl << endl; .RE .RS 0 .RE .RS 2 // move back to the beginning of the file .RE .RS 1 in.seekg(0); .RE .RS 0 .RE .RS 2 // clear the state flags .RE .RS 1 in.clear(); .RE .RS 0 .RE .RS 2 // does the same thing as the previous code .br // output each word on a separate line .RE .RS 1 while ( in >> buf ) .RE .RS 2 cout << buf << endl; .RE .RS 4 .RE .RS 1 cout << endl << endl; .RE .RS 0 .RE .RS 2 // output the base info before each integer .RE .RS 1 out << showbase; .RE .RS 0 .RE .RS 1 ostream::pos_type pos= out.tellp(); .RE .RS 0 .RE .RS 2 // output l in hex with a field with of 20 .RE .RS 1 out << hex << setw(20) << l << endl; .RE .RS 0 .RE .RS 2 // output l in oct with a field with of 20 .RE .RS 1 out << oct << setw(20) << l << endl; .RE .RS 0 .RE .RS 2 // output l in dec with a field with of 20 .RE .RS 1 out << dec << setw(20) << l << endl; .RE .RS 0 .RE .RS 2 // move back to the beginning of the file .RE .RS 1 in.seekg(0); .RE .RS 0 .RE .RS 2 // output the all file .RE .RS 1 cout << in.rdbuf(); .RE .RS 0 .RE .RS 2 // clear the flags .RE .RS 1 in.clear(); .RE .RS 0 .RE .RS 2 // seek the input sequence to pos .RE .RS 1 in.seekg(pos); .RE .RS 0 .RE .RS 1 int a,b,d; .RE .RS 0 .RE .RS 2 // read the previous outputted integer .RE .RS 1 in >> a >> b >> d; .RE .RS 0 .RE .RS 2 // output 3 times 20 .RE .RS 1 cout << a << endl << b << endl << d << endl; .RE .RS 0 .br } .RE .RS 1 catch( ios_base::failure& var ) .RE .RS 3 { .RE .RS 5 cout << var.what(); .RE .RS 3 } .RE .RS 0 .br } .SH SEE ALSO char_traits(3C++), ios_base(3C++), basic_ios(3C++), basic_filebuf(3C++), basic_ofstream(3C++), basic_fstream(3C++) Working Paper for Draft Proposed International Standard for Information Systems--Programming Language C++, Section 27.8.1.5 .SH STANDARDS CONFORMANCE ANSI X3J16/ISO WG21 Joint C++ Committee