Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
std::basic_...buf::seekoff(3) C++ Standard Libarystd::basic_...buf::seekoff(3)

NAME
       std::basic_filebuf::seekoff - std::basic_filebuf::seekoff

Synopsis
	  protected:

	  virtual pos_type seekoff( off_type off,
				    std::ios_base::seekdir dir,

				    std::ios_base::openmode	  which	     =
       std::ios_base::in |
	  std::ios_base::out );

	  Repositions the file pointer,	if possible, to	the position that cor-
       responds	to
	  exactly off characters from beginning, end, or current  position  of
       the file
	  (depending on	the value of dir).

	  If the associated file is not	open (is_open()	== false), fails imme-
       diately.

	  If the multibyte character encoding is state-dependent (codecvt::en-
       coding()	returned
	  -1) or variable-length (codecvt::encoding() returned 0) and the off-
       set off is not 0,
	  fails	 immediately:  this  function  cannot  determine the number of
       bytes that
	  correspond to	off characters.

	  If dir is not	std::basic_ios::cur or the offset off is  not  0,  and
       the most	recent
	  operation  done  on  this filebuf object was output (that is,	either
       the put buffer is
	  not empty, or	the most recently  called  function  was  overflow()),
       then calls
	  std::codecvt::unshift	 to  determine the unshift sequence necessary,
       and writes that
	  sequence to the file by calling overflow().

	  Then converts	the argument dir to a value whence of type int as fol-
       lows:

	  value	of dir	      value of whence
	  std::basic_ios::beg SEEK_SET
	  std::basic_ios::end SEEK_END
	  std::basic_ios::cur SEEK_CUR

	  Then,	if the character encoding is fixed-width  (codecvt::encoding()
       returns some
	  positive   number   width),	moves	the  file  pointer  as	if  by
       std::fseek(file,	width*off,
	  whence).

	  Otherwise, moves the file  pointer  as  if  by  std::fseek(file,  0,
       whence).

	  The  openmode	 argument,  required by	the base class function	signa-
       ture, is	usually
	  ignored, because std::basic_filebuf maintains	only  one  file	 posi-
       tion.

Parameters
	  off	- relative position to set the position	indicator to
		  defines  base	 position  to apply the	relative offset	to. It
       can be one of the
		  following constants:

	  dir	- Constant Explanation
		  beg	   the beginning of a stream
		  end	   the ending of a stream
		  cur	   the current position	of stream position indicator
		  defines which	of the input and/or output  sequences  to  af-
       fect. It	can be one
		  or a combination of the following constants:
	  which	-
		  Constant Explanation
		  in	   affect the input sequence
		  out	   affect the output sequence

Return value
	  A newly constructed object of	type pos_type which stores the result-
       ing file
	  position, or pos_type(off_type(-1)) on failure.

Notes
	  seekoff()  is	 called	 by std::basic_streambuf::pubseekoff, which is
       called by
	  std::basic_istream::seekg,	std::basic_ostream::seekp,    std::ba-
       sic_istream::tellg, and
	  std::basic_ostream::tellp.

Example
       // Run this code

	#include <fstream>
	#include <iostream>
	#include <locale>

	template<typename CharT>
	int get_encoding(const std::basic_istream<CharT>& stream)
	{
	    using Facet	= std::codecvt<CharT, char, std::mbstate_t>;
	    return std::use_facet<Facet>(stream.getloc()).encoding();
	}

	int main()
	{
	    // prepare a 10-byte file holding 4	characters ("z") in UTF-8
	    std::ofstream("text.txt")					    <<
       "\x7a\xc3\x9f\xe6\xb0\xb4\xf0\x9d\x84\x8b";

	    // open using a non-converting encoding
	    std::ifstream f1("text.txt");
	    std::cout << "f1's locale's	encoding() returns "
		      << get_encoding(f1) << '\n'
		      << "pubseekoff(3,	beg) returns "
		      << f1.rdbuf()->pubseekoff(3, std::ios_base::beg) << '\n'
		      << "pubseekoff(0,	end) returns "
		      <<  f1.rdbuf()->pubseekoff(0,   std::ios_base::end)   <<
       '\n';

	    // open using UTF-8
	    std::wifstream f2("text.txt");
	    f2.imbue(std::locale("en_US.UTF-8"));
	    std::cout << "f2's locale's	encoding() returns "
		      << get_encoding(f2) << '\n'
		      << "pubseekoff(3,	beg) returns "
		      << f2.rdbuf()->pubseekoff(3, std::ios_base::beg) << '\n'
		      << "pubseekoff(0,	end) returns "
		      <<   f2.rdbuf()->pubseekoff(0,   std::ios_base::end)  <<
       '\n';
	}

Output:
	f1's locale's encoding() returns 1
	pubseekoff(3, beg) returns 3
	pubseekoff(0, end) returns 10
	f2's locale's encoding() returns 0
	pubseekoff(3, beg) returns -1
	pubseekoff(0, end) returns 10

	  Defect reports

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

	    DR	 Applied to	  Behavior as published		  Correct  be-
       havior
	  LWG	  55	 C++98		seekoff	   returned    an    undefined
       pos_type(off_type(-1))
			    invalid stream position on failure is returned  on
       failure

See also
	  pubseekoff invokes seekoff()
		     (public	member	  function    of    std::basic_stream-
       buf<CharT,Traits>)
	  seekpos    repositions the file position, using absolute addressing
	  [virtual]  (virtual protected	member function)
	  fseek	     moves the file position indicator to a specific  location
       in a file
		     (function)

http://cppreference.com		  2024.06.10	 std::basic_...buf::seekoff(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::filebuf::seekoff&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help