home | help 
std::basic_filebuf::open(3)    C++ Standard Libary   std::basic_filebuf::open(3)

NAME
     std::basic_filebuf::open - std::basic_filebuf::open

Synopsis
	basic_filebuf* open( const char* s, std::ios_base::openmode mode   (1)
	);
	basic_filebuf*	open(  const std::string& str,			     (2)
     (since C++11)
	std::ios_base::openmode mode );
	basic_filebuf* open( const std::filesystem::path&  p,		     (3)
     (since C++17)
			     std::ios_base::openmode mode );
	basic_filebuf*	open(  const std::filesystem::path::value_type* s,   (4)
     (since C++17)
			     std::ios_base::openmode mode );

	If the associated file was already open (is_open() != false), returns  a
     null pointer
	right away.

	Otherwise, opens the file with the given name (s
	, p.c_str()
	(since	  C++17)   or	str.c_str(),   depending   on	the   overload).
     std::ios_base::openmode
	values may be written as, e.g., std::ios_base::out | std::ios_base::app.

	Overload (4) is only provided  if  std::filesystem::path::value_type  is
     (since C++17)
	not char.

	The  file is opened as if by calling std::fopen with the second argument
     (file access
	mode) determined by the result of mode & ~std::ios_base::ate as follows,
     open()
	fails if the result is not some combination of flags shown in the table:

	     mode & ~std::ios_base::ate 	astd::fopena	Action	if  file
     Action if file
	binary	in  out  trunc	app noreplace	      access	  already exists
     does not exist
				(since C++23)	   mode
	-	    +	    -	     -		-	 -		     "r"
     Failure to
	+	+   -	 -	-   -		  "rb"		 Read from start
     open
	-	    +	    +	     -		-	 -		    "r+"
     Error
	+      +  +   -     -	-	      "r+b"
	-      -  +   -     -	-	      "w"
	-      -  +   +     -	-
	+	-   +	 -     -   -		 "wb"		Destroy contents
     Create new
	+      -  +   +     -	-
	-      +  +   +     -	-	      "w+"
	+      +  +   +     -	-	      "w+b"
	-      -  +   -     -	+	      "wx"
	-      -  +   +     -	+
	+      -  +   -     -	+	       "wbx"	       Failure	to  open
     Create new
	+      -  +   +     -	+
	-      +  +   +     -	+	      "w+x"
	+      +  +   +     -	+	      "w+bx"
	-      -  +   -     +	-	      "a"
	-      -  -   -     +	-
	+      -  +   -     +	-	      "ab"
	+	-   -	 -	+    -				   Write  to end
     Create new
	-      +  +   -     +	-	      "a+"
	-      +  -   -     +	-
	+      +  +   -     +	-	      "a+b"
	+      +  -   -     +	-

	If the open operation succeeds and (openmode & std::ios_base::ate) !=  0
     (the ate bit
	is  set),  repositions	the  file  position to the end of file, as if by
     calling
	std::fseek(file, 0, SEEK_END), where file is  the  pointer  returned  by
     calling
	std::fopen. If the repositioning fails, calls close() and returns a null
     pointer to
	indicate failure.

Parameters
	s,  str,  p  -	the file name to open; s must point to a null-terminated
     string
	openmode   -   the   file   opening   mode,   a   binary   OR	of   the
     std::ios_base::openmode modes

Return value
	this on success, a null pointer on failure.

Notes
	open()	is typically called through the constructor or the open() member
     function of
	std::basic_fstream.

Example
     // Run this code

      #include <fstream>
      #include <iostream>

      int main()
      {
	  std::string filename = "Test.b";
	  std::filebuf fb;

	  // prepare a file to read
	  double d = 3.14;
	  if (!fb.open(filename, std::ios::binary | std::ios::out))
	  {
	      std::cout << "Open file " << filename << " for write failed\n";
	      return 1;
	  }
	  fb.sputn(reinterpret_cast<char*>(&d), sizeof d);
	  fb.close();

	  // open file for reading
	  double d2 = 0.0;
	  if (!fb.open(filename, std::ios::binary | std::ios::in))
	  {
	      std::cout << "Open file " << filename << " for read failed\n";
	      return 1;
	  }

	  auto got = fb.sgetn(reinterpret_cast<char*>(&d2), sizeof d2);
	  if (sizeof(d2) != got)
	      std::cout << "Read of " << filename << " failed\n";
	  else
	      std::cout << "Read back from file: " << d2 << '\n';
      }

Output:
      Read back from file: 3.14

	Defect reports

	The following behavior-changing defect	reports  were  applied	retroac-
     tively to
	previously published C++ standards.

	  DR	 Applied to	      Behavior as published		 Correct
     behavior
	LWG 596 C++98	   open() could not open files in append     can open in
     append mode
			   mode

See also
	is_open checks if the associated file is open
		(public member function)
	close	flushes the put area buffer and closes the associated file
		(public member function)

http://cppreference.com 	   2024.06.10	     std::basic_filebuf::open(3)
home | help