Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/io/basic istream/sync"

From cppreference.com
< cpp‎ | io‎ | basic istream
 
m (fmt, headers sorted, -on)
 
(27 intermediate revisions by 7 users not shown)
Line 1: Line 1:
−
{{cpp/io/basic_istream/title | sync}}
+
{{cpp/io/basic_istream/title|sync}}
−
{{cpp/io/basic_istream/sidebar}}
+
{{cpp/io/basic_istream/navbar}}
−
{{ddcl |
+
{{ddcl|
 
int sync();
 
int sync();
 
}}
 
}}
  
−
Fills the input cache buffer with data from the underlying input device.  
+
Synchronizes the input buffer with the associated data source.
  
−
<!-- ======== -->
+
Behaves as {{named req|UnformattedInputFunction}}, except that {{lc|gcount()}} is not affected. After constructing and checking the sentry object,
−
{{params}}
+
−
{{param none}}
+
  
−
<!-- ======== -->
+
If {{lc|rdbuf()}} is a null pointer, returns {{c|-1}}.
−
{{returns}}
+
  
−
If the stream is buffered and the function is successful, {{cpp|0}} is returned. If the stream is unbuffered, {{cpp|-1}} is returned. In the case of error, {{cpp|setstate(badbit)}} is called and depending on exceptions bitmask, exception is thrown.
+
Otherwise, calls {{c|rdbuf()->pubsync()}}. If that function returns {{c|-1}}, calls {{c|setstate(badbit)}} and returns {{c|-1}}. Otherwise, returns {{c|0}}.
  
−
<!-- ======== -->
+
===Parameters===
−
{{example}}
+
(none)
−
{{example cpp
+
 
−
| code=
+
===Return value===
−
| output=
+
{{c|0}} on success, {{c|-1}} on failure or if the stream does not support this operation (is unbuffered).
 +
 
 +
===Notes===
 +
As with {{lc|readsome()}}, it is implementation-defined whether this function does anything with library-supplied streams. The intent is typically for the next read operation to pick up any changes that may have been made to the associated input sequence after the stream buffer last filled its get area. To achieve that, {{tt|sync()}} may empty the get area, or it may refill it, or it may do nothing. A notable exception is Visual Studio, where this operation discards the unprocessed input when called with a standard input stream.
 +
 
 +
===Example===
 +
{{example
 +
|Demonstrates the use of input stream {{tt|sync()}} with file input. Note that output here is implementation-defined, since calls to {{ltt|cpp/io/basic_filebuf/sync|std::basic_filebuf::sync}} are implementation-defined for reads.
 +
|code=
 +
#include <fstream>
 +
#include <iostream>
 +
 
 +
void file_abc()
 +
{
 +
    std::ofstream f("test.txt");
 +
    f << "abc\n";
 +
}
 +
 
 +
void file_123()
 +
{
 +
    std::ofstream f("test.txt");
 +
    f << "123\n";
 +
}
 +
 
 +
int main()
 +
{
 +
    file_abc(); // file now contains "abc"
 +
    std::ifstream f("test.txt");
 +
    std::cout << "Reading from the file\n";
 +
    char c;
 +
    f >> c;
 +
    std::cout << c;
 +
    file_123(); // file now contains "123"
 +
    f >> c;
 +
    std::cout << c;
 +
    f >> c;
 +
    std::cout << c << '\n';
 +
    f.close();
 +
 
 +
    file_abc(); // file now contains "abc"
 +
    f.open("test.txt");
 +
    std::cout << "Reading from the file, with sync()\n";
 +
    f >> c;
 +
    std::cout << c;
 +
    file_123(); // file now contains "123"
 +
    f.sync();
 +
    f >> c;
 +
    std::cout << c;
 +
    f >> c;
 +
    std::cout << c << '\n';
 +
}
 +
|p=true
 +
|output=<!--Note: output as seen on Sun and IBM, but the Linux/gcc that was tested printed "abc" both times-->
 +
Reading from the file
 +
abc
 +
Reading from the file, with sync()
 +
a23
 
}}
 
}}
  
−
<!-- ======== -->
+
===Defect reports===
−
{{see also}}
+
{{dr list begin}}
−
{{dcl list begin}}
+
{{dr list item|wg=lwg|dr=62|std=C++98|before={{tt|sync()}} returned {{c|traits::eof()}} if {{c|rdbuf()->pubsync()}} returns {{c|-1}}|after=returns {{c|-1}} in this case}}
−
{{dcl list template | cpp/io/basic_ostream/dcl list flush | mem=std::basic_ostream}}
+
{{dr list end}}
−
{{dcl list end}}
+
 
 +
===See also===
 +
{{dsc begin}}
 +
{{dsc inc|cpp/io/basic_streambuf/dsc sync}}
 +
{{dsc inc|cpp/io/basic_ostream/dsc flush}}
 +
{{dsc end}}
 +
 
 +
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Latest revision as of 06:53, 9 September 2023

 
C++
 
Input/output library
 
std::basic_istream
 
int sync();

Synchronizes the input buffer with the associated data source.

Behaves as UnformattedInputFunction, except that gcount() is not affected. After constructing and checking the sentry object,

If rdbuf() is a null pointer, returns -1.

Otherwise, calls rdbuf()->pubsync(). If that function returns -1, calls setstate(badbit) and returns -1. Otherwise, returns ​0​.

Contents

[edit] Parameters

(none)

[edit] Return value

​0​ on success, -1 on failure or if the stream does not support this operation (is unbuffered).

[edit] Notes

As with readsome(), it is implementation-defined whether this function does anything with library-supplied streams. The intent is typically for the next read operation to pick up any changes that may have been made to the associated input sequence after the stream buffer last filled its get area. To achieve that, sync() may empty the get area, or it may refill it, or it may do nothing. A notable exception is Visual Studio, where this operation discards the unprocessed input when called with a standard input stream.

[edit] Example

Demonstrates the use of input stream sync() with file input. Note that output here is implementation-defined, since calls to std::basic_filebuf::sync are implementation-defined for reads.

Run this code
#include <fstream>
#include <iostream>
 
void file_abc()
{
    std::ofstream f("test.txt");
    f << "abc\n";
}
 
void file_123()
{
    std::ofstream f("test.txt");
    f << "123\n";
}
 
int main()
{
    file_abc(); // file now contains "abc"
    std::ifstream f("test.txt");
    std::cout << "Reading from the file\n";
    char c;
    f >> c;
    std::cout << c;
    file_123(); // file now contains "123"
    f >> c;
    std::cout << c;
    f >> c;
    std::cout << c << '\n';
    f.close();
 
    file_abc(); // file now contains "abc"
    f.open("test.txt");
    std::cout << "Reading from the file, with sync()\n";
    f >> c;
    std::cout << c;
    file_123(); // file now contains "123"
    f.sync();
    f >> c;
    std::cout << c;
    f >> c;
    std::cout << c << '\n';
}

Possible output: 

Reading from the file
abc
Reading from the file, with sync()
a23

[edit] Defect reports

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

DR Applied to Behavior as published Correct behavior
LWG 62 C++98 sync() returned traits::eof() if rdbuf()->pubsync() returns -1 returns -1 in this case

[edit] See also

[virtual]
 synchronizes the buffers with the associated character sequence
(virtual protected member function of std::basic_streambuf<CharT,Traits>) [edit]
synchronizes with the underlying storage device
(public member function of std::basic_ostream<CharT,Traits>) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/io/basic_istream/sync&oldid=158537"