]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
2 | <HTML> | |
3 | <HEAD> | |
4 | <TITLE>File Descriptor Devices</TITLE> | |
5 | <LINK REL="stylesheet" HREF="../../../../boost.css"> | |
6 | <LINK REL="stylesheet" HREF="../theme/iostreams.css"> | |
7 | <STYLE> H3 CODE { font-size: 110% } </STYLE> | |
8 | </HEAD> | |
9 | <BODY> | |
10 | ||
11 | <!-- Begin Banner --> | |
12 | ||
13 | <H1 CLASS="title">File Descriptors</H1> | |
14 | <HR CLASS="banner"> | |
15 | ||
16 | <!-- End Banner --> | |
17 | ||
18 | <DL class="page-index"> | |
19 | <DT><A href="#overview">Overview</A></DT> | |
20 | <DT><A href="#acknowledgments">Acknowledments</A></DT> | |
21 | <DT><A href="#installation">Installation</A></DT> | |
22 | <DT><A href="#headers">Headers</A></DT> | |
23 | <DT><A href="#reference">Reference</A> | |
24 | <UL> | |
25 | <LI CLASS="square"><A href="#file_descriptor_source">Class <CODE>file_descriptor_source</CODE></A></LI> | |
26 | <LI CLASS="square"><A href="#file_descriptor_sink">Class <CODE>file_descriptor_sink</CODE></A></LI> | |
27 | <LI CLASS="square"><A href="#file_descriptor">Class <CODE>file_descriptor</CODE></A></LI> | |
28 | </UL> | |
29 | </DT> | |
30 | </DL> | |
31 | ||
32 | <HR> | |
33 | ||
34 | <A NAME="overview"></A> | |
35 | <H2>Overview</H2> | |
36 | ||
37 | <P> | |
38 | The classes <CODE>file_descriptor_source</CODE>, <CODE>file_descriptor_sink</CODE> and <CODE>file_descriptor</CODE> provide file access via operating system file handles or file descriptors. These <A HREF="../guide/concepts.html#device_concepts">Devices</A> behave much like the <A HREF="file.html">File Wrappers</A> <CODE>basic_file_source</CODE>, <CODE>basic_file_sink</CODE> and <CODE>basic_file</CODE>, with the following important differences: | |
39 | </P> | |
40 | <UL> | |
41 | <LI CLASS="square">A file descriptor Device may be constructed from a file descriptor which is already open. | |
42 | <LI CLASS="square">The only <A HREF="../guide/buffering.html">buffering</A> is provded by the Boost Iostreams library. | |
43 | <LI CLASS="square">There is no automatic line-ending conversion. | |
44 | <LI CLASS="square">Wide-character streams are not supported. | |
45 | </UL> | |
46 | ||
47 | <P> | |
48 | When a file descriptor Device is copied, the result represents the same underlying file descriptor. The underlying file descriptor is <I>not</I> duplicated. | |
49 | </P> | |
50 | ||
51 | <P> | |
52 | The classes <CODE>file_descriptor</CODE> supports 64-bit seek offsets whenever they are supported by the underlying operating system or runtime library. Currently, file descriptor Devices may not work corectly with file descriptors opened in non-blocking mode. | |
53 | </P> | |
54 | ||
55 | <P> | |
56 | Line-ending conversion can be provided, if desired, using the class <A HREF="newline_filter.html"><CODE>newline_filter</CODE></A>. Wide-character versions of the file descriptor Devices may be defined as follows, using the template <A HREF="code_converter.html"><CODE>code_converter</CODE></A>: | |
57 | <PRE CLASS="broken_ie"> <SPAN CLASS="preprocessor">#include</SPAN> <A CLASS="header" HREF="../../../../boost/iostreams/code_converter.hpp"><SPAN CLASS="literal"><boost/iostreams/code_converter.hpp></SPAN></A> | |
58 | <SPAN CLASS="preprocessor">#include</SPAN> <A CLASS="header" HREF="../../../../boost/iostreams/device/file_descriptor.hpp"><SPAN CLASS="literal"><boost/iostreams/maped_file.hpp></SPAN></A> | |
59 | ||
60 | <SPAN CLASS='keyword'>typedef</SPAN> code_converter<file_descriptor_source> wfile_descriptor_source; | |
61 | <SPAN CLASS='keyword'>typedef</SPAN> code_converter<file_descriptor_sink> wfile_descriptor_sink;</PRE> | |
62 | </P> | |
63 | ||
64 | <A NAME="acknowledgments"></A> | |
65 | <H2>Acknowledgments</H2> | |
66 | ||
67 | <P> | |
68 | The file descriptor Devices are based on work of Nicolai Josuttis (<A CLASS="bib_ref" HREF="../bibliography.html#josuttis1">[Josuttis1]</A> <I>pp.</I> 672-3 and <A CLASS="bib_ref" HREF="../bibliography.html#josuttis2">[Josuttis2]</A>). | |
69 | </P> | |
70 | ||
71 | <A NAME="installation"></A> | |
72 | <H2>Installation</H2> | |
73 | ||
74 | <P> | |
75 | The file descriptor Devices depends on the source file <A CLASS="header" HREF="../../src/file_descriptor.cpp"><CODE><libs/iostreams/src/file_descriptor.cpp></CODE></A>, which makes use of Windows or POSIX headers depending on the user's operating system. For installation instructions see <A HREF="../installation.html">Installation</A>. | |
76 | </P> | |
77 | ||
78 | <A NAME="headers"></A> | |
79 | <H2>Headers</H2> | |
80 | ||
81 | <DL class="page-index"> | |
82 | <DT><A CLASS="header" HREF="../../../../boost/iostreams/device/file_descriptor.hpp"><CODE><boost/iostreams/device/file_descriptor.hpp></CODE></A></DT> | |
83 | </DL> | |
84 | ||
85 | ||
86 | <A NAME="reference"></A> | |
87 | <H2>Reference</H2> | |
88 | ||
89 | <A NAME="file_descriptor_source"></A> | |
90 | <H3>Class <CODE>file_descriptor_source</CODE></H3> | |
91 | ||
92 | <H4>Description</H4> | |
93 | ||
94 | <P>Model of <A HREF="../concepts/device.html">SeekableSource</A> and <A HREF="../concepts/closable.html">Closable</A> providing read-only access to a file through an operating system file descriptor.</P> | |
95 | ||
96 | <H4>Synopsis</H4> | |
97 | ||
98 | <PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams { | |
99 | ||
100 | <SPAN CLASS="keyword">enum</SPAN> file_descriptor_flags { | |
101 | never_close_handle, | |
102 | close_handle | |
103 | }; | |
104 | ||
105 | <SPAN CLASS="keyword">class</SPAN> file_descriptor_source { | |
106 | <SPAN CLASS="keyword">public</SPAN>: | |
107 | <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='keyword'>char</SPAN> char_type; | |
108 | <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN> handle_type; | |
109 | <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN> category; | |
110 | <A CLASS="documented" HREF="#file_descriptor_source_ctor">file_descriptor_source</A>(); | |
111 | <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> Path> | |
112 | <A CLASS="documented" HREF="#file_descriptor_source_ctor">file_descriptor_source</A>( <SPAN CLASS="keyword">const</SPAN> Path& pathname, | |
113 | std::ios_base::open_mode mode = | |
114 | std::ios_base::in ); | |
115 | <A CLASS="documented" HREF="#file_descriptor_source_ctor">file_descriptor_source</A>( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
116 | ||
117 | <SPAN CLASS='comment'>// Windows-only</SPAN> | |
118 | <A CLASS="documented" HREF="#file_descriptor_source_ctor">file_descriptor_source</A>( HANDLE hFile, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
119 | ||
120 | <SPAN CLASS='comment'>// Deprecated</SPAN> | |
121 | <A CLASS="documented" HREF="#file_descriptor_source_ctor">file_descriptor_source</A>( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
122 | ||
123 | <SPAN CLASS='comment'>// Deprecated, Windows-only</SPAN> | |
124 | <A CLASS="documented" HREF="#file_descriptor_source_ctor">file_descriptor_source</A>( HANDLE hFile, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
125 | ||
126 | <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> Path> | |
127 | <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#file_descriptor_source_open">open</A>( <SPAN CLASS="keyword">const</SPAN> Path& pathname, | |
128 | std::ios_base::open_mode mode = | |
129 | std::ios_base::in ); | |
130 | <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#file_descriptor_source_open">open</A>( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
131 | ||
132 | <SPAN CLASS='comment'>// Windows-only</SPAN> | |
133 | <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#file_descriptor_source_open">open</A>( HANDLE hFile, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
134 | ||
135 | <SPAN CLASS='comment'>// Deprecated</SPAN> | |
136 | <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#file_descriptor_source_open">open</A>( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
137 | ||
138 | <SPAN CLASS='comment'>// Deprecated, Windows-only</SPAN> | |
139 | <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#file_descriptor_source_open">open</A>( HANDLE hFile, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
140 | ||
141 | <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#file_descriptor_source_is_open">is_open</A>() <SPAN CLASS="keyword">const</SPAN>; | |
142 | ||
143 | handle_type <A CLASS="documented" HREF="#file_descriptor_source_handle">handle</A>() <SPAN CLASS="keyword">const</SPAN>; | |
144 | }; | |
145 | ||
146 | } } <SPAN CLASS='comment'>// End namespace boost::io</SPAN></PRE> | |
147 | ||
148 | <A NAME="file_descriptor_source_ctor"></A> | |
149 | <H4><CODE>file_descriptor_source::file_descriptor_source</CODE></H4> | |
150 | ||
151 | <PRE CLASS="broken_ie"> file_descriptor_source(); | |
152 | <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> Path> | |
153 | file_descriptor_source( <SPAN CLASS="keyword">const</SPAN> Path& pathname, | |
154 | std::ios_base::open_mode mode = | |
155 | std::ios_base::in ); | |
156 | file_descriptor_source( <SPAN CLASS="keyword">int </SPAN>fd, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
157 | ||
158 | <SPAN CLASS='comment'>// Windows-only</SPAN> | |
159 | file_descriptor_source( HANDLE hFile, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
160 | ||
161 | <SPAN CLASS='comment'>// Deprecated</SPAN> | |
162 | file_descriptor_source( <SPAN CLASS="keyword">int </SPAN>fd, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
163 | ||
164 | <SPAN CLASS='comment'>// Deprecated, Windows-only</SPAN> | |
165 | file_descriptor_source( HANDLE hFile, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> );</PRE> | |
166 | <P> | |
167 | The first member constructs an empty <CODE>file_descriptor_source</CODE>. | |
168 | </P> | |
169 | ||
170 | <P> | |
171 | The second member constructs a <CODE>file_descriptor_source</CODE> to access the file with the given pathname. <CODE>Path</CODE> should be either a string or a Boost.Filesystem path. The parameter <CODE>mode</CODE> has the same interpretation as <CODE>(mode | std::ios_base::in)</CODE> in <CODE>std::basic_filebuf::open</CODE>.<A CLASS="footnote_ref" NAME="note_1_ref" HREF="#note_1"><SUP>[1]</SUP></A> | |
172 | </P> | |
173 | ||
174 | <P> | |
175 | The third member constructs a <CODE>file_descriptor_source</CODE> to access the file with the given operating system or runtime-library file descriptor. | |
176 | If the second argument is <CODE>close_handle</CODE>, the file descriptor is closed when the <CODE>file_descriptor_source</CODE> being constructed — or one of its copies — is closed or destructed. | |
177 | </P> | |
178 | ||
179 | <P> | |
180 | The fourth member is the same as the third, except that it accepts a Windows file handle instead of a file descriptor. | |
181 | If the second argument is <CODE>close_handle</CODE>, the file descriptor is closed when the <CODE>file_descriptor_source</CODE> being constructed — or one of its copies — is closed or destructed. | |
182 | </P> | |
183 | ||
184 | <P> | |
185 | The deprecated members are there to provide backwards compatability with old versions. | |
186 | To use them you need to define <CODE>BOOST_IOSTREAMS_USE_DEPRECATED</CODE>. | |
187 | The descriptor is always closed by <CODE>close</CODE> but only closed in destructors if <CODE>close_on_exit</CODE> is <CODE>true</CODE>. | |
188 | </P> | |
189 | ||
190 | <A NAME="file_descriptor_source_open"></A> | |
191 | <H4><CODE>file_descriptor_source::open</CODE></H4> | |
192 | ||
193 | <PRE CLASS="broken_ie"> <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> Path> | |
194 | <SPAN CLASS="keyword">void</SPAN> open( <SPAN CLASS="keyword">const</SPAN> Path& pathname, | |
195 | std::ios_base::open_mode mode = | |
196 | std::ios_base::in ); | |
197 | <SPAN CLASS="keyword">void</SPAN> open( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
198 | ||
199 | <SPAN CLASS='comment'>// Windows-only</SPAN> | |
200 | <SPAN CLASS="keyword">void</SPAN> open( HANDLE hFile, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
201 | ||
202 | <SPAN CLASS='comment'>// Deprecated</SPAN> | |
203 | <SPAN CLASS="keyword">void</SPAN> open( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
204 | ||
205 | <SPAN CLASS='comment'>// Deprecated, Windows-only</SPAN> | |
206 | <SPAN CLASS="keyword">void</SPAN> open( HANDLE hFile, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> );</PRE> | |
207 | ||
208 | <P> | |
209 | The parameters of <CODE>open</CODE> the same as those of the corresponding constructors. | |
210 | If the file descriptor already holds a file, it'll be closed | |
211 | (unless opened or constructed with <CODE>never_close_handle</CODE>). | |
212 | </P> | |
213 | ||
214 | <A NAME="file_descriptor_source_is_open"></A> | |
215 | <H4><CODE>file_descriptor_source::is_open</CODE></H4> | |
216 | ||
217 | <PRE CLASS="broken_ie"> <SPAN CLASS="keyword">bool</SPAN> is_open() <SPAN CLASS="keyword">const</SPAN>;</PRE> | |
218 | ||
219 | <P>Returns <CODE>true</CODE> if the underlying file was opened successfully.</P> | |
220 | ||
221 | <A NAME="file_descriptor_source_handle"></A> | |
222 | <H4><CODE>file_descriptor_source::handle</CODE></H4> | |
223 | ||
224 | <PRE CLASS="broken_ie"> handle_type handle() <SPAN CLASS="keyword">const</SPAN>;</PRE> | |
225 | ||
226 | <P>Returns the underlying OS file descriptor. On Windows, this is a <CODE>HANDLE</CODE>. On other systems, it is an <CODE><SPAN CLASS="keyword">int</SPAN></CODE>.</P> | |
227 | ||
228 | <A NAME="file_descriptor_sink"></A> | |
229 | <H3>Class <CODE>file_descriptor_sink</CODE></H3> | |
230 | ||
231 | <H4>Description</H4> | |
232 | ||
233 | <P>Model of <A HREF="../concepts/device.html">SeekableSink</A> and <A HREF="../concepts/closable.html">Closable</A> providing write-only access to a file through an operating system file descriptor. | |
234 | ||
235 | <H4>Synopsis</H4> | |
236 | ||
237 | <PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams { | |
238 | ||
239 | <SPAN CLASS="keyword">enum</SPAN> file_descriptor_flags { | |
240 | never_close_handle, | |
241 | close_handle | |
242 | }; | |
243 | ||
244 | <SPAN CLASS="keyword">class</SPAN> file_descriptor_sink { | |
245 | <SPAN CLASS="keyword">public</SPAN>: | |
246 | <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='keyword'>char</SPAN> char_type; | |
247 | <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN> handle_type; | |
248 | <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN> category; | |
249 | <A CLASS="documented" HREF="#file_descriptor_sink_ctor">file_descriptor_sink</A>(); | |
250 | <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> Path> | |
251 | <A CLASS="documented" HREF="#file_descriptor_sink_ctor">file_descriptor_sink</A>( <SPAN CLASS="keyword">const</SPAN> Path& pathname, | |
252 | std::ios_base::open_mode mode = | |
253 | std::ios_base::out ); | |
254 | <A CLASS="documented" HREF="#file_descriptor_sink_ctor">file_descriptor_sink</A>( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
255 | ||
256 | <SPAN CLASS='comment'>// Windows-only</SPAN> | |
257 | <A CLASS="documented" HREF="#file_descriptor_sink_ctor">file_descriptor_sink</A>( HANDLE hFile, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
258 | ||
259 | <SPAN CLASS='comment'>// Deprecated</SPAN> | |
260 | <A CLASS="documented" HREF="#file_descriptor_sink_ctor">file_descriptor_sink</A>( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
261 | ||
262 | <SPAN CLASS='comment'>// Deprecated, Windows-only</SPAN> | |
263 | <A CLASS="documented" HREF="#file_descriptor_sink_ctor">file_descriptor_sink</A>( HANDLE hFile, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
264 | ||
265 | <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> Path> | |
266 | <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#file_descriptor_sink_open">open</A>( <SPAN CLASS="keyword">const</SPAN> Path& pathname, | |
267 | std::ios_base::open_mode mode = | |
268 | std::ios_base::out ); | |
269 | <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#file_descriptor_sink_open">open</A>( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
270 | ||
271 | <SPAN CLASS='comment'>// Windows-only</SPAN> | |
272 | <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#file_descriptor_sink_open">open</A>( HANDLE hFile, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
273 | ||
274 | <SPAN CLASS='comment'>// Deprecated</SPAN> | |
275 | <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#file_descriptor_sink_open">open</A>( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
276 | ||
277 | <SPAN CLASS='comment'>// Deprecated, Windows-only</SPAN> | |
278 | <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#file_descriptor_sink_open">open</A>( HANDLE hFile, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
279 | ||
280 | <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#file_descriptor_sink_is_open">is_open</A>() <SPAN CLASS="keyword">const</SPAN>; | |
281 | ||
282 | handle_type <A CLASS="documented" HREF="#file_descriptor_sink_handle">handle</A>() <SPAN CLASS="keyword">const</SPAN>; | |
283 | }; | |
284 | ||
285 | } } <SPAN CLASS='comment'>// End namespace boost::io</SPAN></PRE> | |
286 | ||
287 | <A NAME="file_descriptor_sink_ctor"></A> | |
288 | <H4><CODE>file_descriptor_sink::file_descriptor_sink</CODE></H4> | |
289 | ||
290 | <PRE CLASS="broken_ie"> file_descriptor_sink(); | |
291 | <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> Path> | |
292 | file_descriptor_sink( <SPAN CLASS="keyword">const</SPAN> Path& pathname, | |
293 | std::ios_base::open_mode mode = | |
294 | std::ios_base::out ); | |
295 | file_descriptor_sink( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
296 | ||
297 | <SPAN CLASS='comment'>// Windows-only</SPAN> | |
298 | file_descriptor_sink( HANDLE hFile, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
299 | ||
300 | <SPAN CLASS='comment'>// Deprecated</SPAN> | |
301 | file_descriptor_sink( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
302 | ||
303 | <SPAN CLASS='comment'>// Deprecated, Windows-only</SPAN> | |
304 | file_descriptor_sink( HANDLE hFile, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> );</PRE> | |
305 | ||
306 | <P> | |
307 | The first member constructs an empty <CODE>file_descriptor_sink</CODE>. | |
308 | </P> | |
309 | ||
310 | <P> | |
311 | The second member constructs a <CODE>file_descriptor_sink</CODE> to access the file with the given pathname. <CODE>Path</CODE> should be either a string or a Boost.Filesystem path. The parameter <CODE>mode</CODE> has the same interpretation as <CODE>(mode | std::ios_base::out)</CODE> in <CODE>std::basic_filebuf::open</CODE>.<A CLASS="footnote_ref" NAME="note_1_ref2" HREF="#note_1"><SUP>[1]</SUP></A> | |
312 | </P> | |
313 | ||
314 | <P> | |
315 | The third member constructs a <CODE>file_descriptor_sink</CODE> to access the file with the given operating system or runtime-library file descriptor. | |
316 | If the second argument is <CODE>close_handle</CODE>, the file descriptor is closed when the <CODE>file_descriptor_sink</CODE> being constructed — or one of its copies — is closed or destructed. | |
317 | </P> | |
318 | ||
319 | <P> | |
320 | The fourth member is the same as the third, except that it accepts a Windows file handle instead of a file descriptor. | |
321 | If the second argument is <CODE>close_handle</CODE>, the file descriptor is closed when the <CODE>file_descriptor_sink</CODE> being constructed — or one of its copies — is closed or destructed. | |
322 | </P> | |
323 | ||
324 | <P> | |
325 | The deprecated members are there to provide backwards compatability with old versions. | |
326 | To use them you need to define <CODE>BOOST_IOSTREAMS_USE_DEPRECATED</CODE>. | |
327 | The descriptor is always closed by <CODE>close</CODE> but only closed in destructors if <CODE>close_on_exit</CODE> is <CODE>true</CODE>. | |
328 | </P> | |
329 | ||
330 | <A NAME="file_descriptor_sink_open"></A> | |
331 | <H4><CODE>file_descriptor_sink::open</CODE></H4> | |
332 | ||
333 | <PRE CLASS="broken_ie"> <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> Path> | |
334 | <SPAN CLASS="keyword">void</SPAN> open( <SPAN CLASS="keyword">const</SPAN> Path& pathname, | |
335 | std::ios_base::open_mode mode = | |
336 | std::ios_base::out ); | |
337 | <SPAN CLASS="keyword">void</SPAN> open( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
338 | ||
339 | <SPAN CLASS='comment'>// Windows-only</SPAN> | |
340 | <SPAN CLASS="keyword">void</SPAN> open( HANDLE hFile, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
341 | ||
342 | <SPAN CLASS='comment'>// Deprecated</SPAN> | |
343 | <SPAN CLASS="keyword">void</SPAN> open( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
344 | ||
345 | <SPAN CLASS='comment'>// Deprecated, Windows-only</SPAN> | |
346 | <SPAN CLASS="keyword">void</SPAN> open( HANDLE hFile, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> );</PRE> | |
347 | ||
348 | <P> | |
349 | The parameters of <CODE>open</CODE> the same as those of the corresponding constructors. | |
350 | If the file descriptor already holds a file, it'll be closed | |
351 | (unless opened or constructed with <CODE>never_close_handle</CODE>). | |
352 | </P> | |
353 | ||
354 | <A NAME="file_descriptor_sink_is_open"></A> | |
355 | <H4><CODE>file_descriptor_sink::is_open</CODE></H4> | |
356 | ||
357 | <PRE CLASS="broken_ie"> <SPAN CLASS="keyword">bool</SPAN> is_open() <SPAN CLASS="keyword">const</SPAN>;</PRE> | |
358 | ||
359 | <P>Returns <CODE>true</CODE> if the underlying file was opened successfully.</P> | |
360 | ||
361 | <A NAME="file_descriptor_sink_handle"></A> | |
362 | <H4><CODE>file_descriptor_sink::handle</CODE></H4> | |
363 | ||
364 | <PRE CLASS="broken_ie"> handle_type handle() <SPAN CLASS="keyword">const</SPAN>;</PRE> | |
365 | ||
366 | <P>Returns the underlying OS file descriptor. On Windows, this is a <CODE>HANDLE</CODE>. On other systems, it is an <CODE><SPAN CLASS="keyword">int</SPAN></CODE>.</P> | |
367 | ||
368 | <A NAME="file_descriptor"></A> | |
369 | <H3>Class <CODE>file_descriptor</CODE></H3> | |
370 | ||
371 | <H4>Description</H4> | |
372 | ||
373 | <P>Model of <A HREF="../concepts/seekable_device.html">SeekableDevice</A> and <A HREF="../concepts/closable.html">Closable</A> providing read-write access to a file through an operating system file descriptor. | |
374 | ||
375 | <H4>Synopsis</H4> | |
376 | ||
377 | <PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams { | |
378 | ||
379 | <SPAN CLASS="keyword">enum</SPAN> file_descriptor_flags { | |
380 | never_close_handle, | |
381 | close_handle | |
382 | }; | |
383 | ||
384 | <SPAN CLASS="keyword">class</SPAN> file_descriptor { | |
385 | <SPAN CLASS="keyword">public</SPAN>: | |
386 | <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='keyword'>char</SPAN> char_type; | |
387 | <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN> handle_type; | |
388 | <SPAN CLASS='keyword'>typedef</SPAN> <SPAN CLASS='omitted'>[implementation-defined]</SPAN> category; | |
389 | <A CLASS="documented" HREF="#file_descriptor_constructor">file_descriptor</A>(); | |
390 | <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> Path> | |
391 | <A CLASS="documented" HREF="#file_descriptor_constructor">file_descriptor</A>( <SPAN CLASS="keyword">const</SPAN> Path& pathname, | |
392 | std::ios_base::open_mode mode = | |
393 | std::ios_base::in | std::ios_base::out ); | |
394 | <A CLASS="documented" HREF="#file_descriptor_constructor">file_descriptor</A>( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
395 | ||
396 | <SPAN CLASS='comment'>// Windows-only</SPAN> | |
397 | <A CLASS="documented" HREF="#file_descriptor_constructor">file_descriptor</A>( HANDLE hFile, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
398 | ||
399 | <SPAN CLASS='comment'>// Deprecated</SPAN> | |
400 | <A CLASS="documented" HREF="#file_descriptor_constructor">file_descriptor</A>( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
401 | ||
402 | <SPAN CLASS='comment'>// Deprecated, Windows-only</SPAN> | |
403 | <A CLASS="documented" HREF="#file_descriptor_constructor">file_descriptor</A>( HANDLE hFile, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
404 | ||
405 | <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> Path> | |
406 | <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#file_descriptor_open">open</A>( <SPAN CLASS="keyword">const</SPAN> Path& pathname, | |
407 | std::ios_base::open_mode mode = | |
408 | std::ios_base::in | std::ios_base::out ); | |
409 | <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#file_descriptor_open">open</A>( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
410 | ||
411 | <SPAN CLASS='comment'>// Windows-only</SPAN> | |
412 | <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#file_descriptor_open">open</A>( HANDLE hFile, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
413 | ||
414 | <SPAN CLASS='comment'>// Deprecated</SPAN> | |
415 | <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#file_descriptor_open">open</A>( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
416 | ||
417 | <SPAN CLASS='comment'>// Deprecated, Windows-only</SPAN> | |
418 | <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#file_descriptor_open">open</A>( HANDLE hFile, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
419 | ||
420 | <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#file_descriptor_is_open">is_open</A>() <SPAN CLASS="keyword">const</SPAN>; | |
421 | ||
422 | handle_type <A CLASS="documented" HREF="#file_descriptor_handle">handle</A>() <SPAN CLASS="keyword">const</SPAN>; | |
423 | }; | |
424 | ||
425 | } } <SPAN CLASS='comment'>// End namespace boost::io</SPAN></PRE> | |
426 | ||
427 | <A NAME="file_descriptor_constructor"></A> | |
428 | <H4><CODE>file_descriptor::file_descriptor</CODE></H4> | |
429 | ||
430 | <PRE CLASS="broken_ie"> file_descriptor(); | |
431 | <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> Path> | |
432 | file_descriptor( <SPAN CLASS="keyword">const</SPAN> Path& pathname, | |
433 | std::ios_base::open_mode mode = | |
434 | std::ios_base::in | std::ios_base::out ); | |
435 | file_descriptor( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
436 | ||
437 | <SPAN CLASS='comment'>// Windows-only</SPAN> | |
438 | file_descriptor( HANDLE hFile, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
439 | ||
440 | <SPAN CLASS='comment'>// Deprecated</SPAN> | |
441 | file_descriptor( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
442 | ||
443 | <SPAN CLASS='comment'>// Deprecated, Windows-only</SPAN> | |
444 | file_descriptor( HANDLE hFile, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> );</PRE> | |
445 | ||
446 | <P> | |
447 | The first member constructs an empty <CODE>file_descriptor</CODE>. | |
448 | </P> | |
449 | ||
450 | <P> | |
451 | The second member constructs a <CODE>file_descriptor</CODE> to access the file with the given pathname. <CODE>Path</CODE> should be either a string or a Boost.Filesystem path. The parameter <CODE>mode</CODE> has the same interpretation as in <CODE>std::basic_filebuf::open</CODE>.<A CLASS="footnote_ref" NAME="note_1_ref3" HREF="#note_1"><SUP>[1]</SUP></A> | |
452 | </P> | |
453 | ||
454 | <P> | |
455 | The third member constructs a <CODE>file_descriptor</CODE> to access the file with the given operating system or runtime-library file descriptor. | |
456 | If the second argument is <CODE>close_handle</CODE>, the file descriptor is closed when the <CODE>file_descriptor</CODE> being constructed — or one of its copies — is closed or destructed. | |
457 | </P> | |
458 | ||
459 | <P> | |
460 | The fourth member is the same as the third, except that it accepts a Windows file handle instead of a file descriptor. | |
461 | If the second argument is <CODE>close_handle</CODE>, the file descriptor is closed when the new <CODE>file_descriptor</CODE> — or one of its copies — is closed or destructed. | |
462 | </P> | |
463 | ||
464 | <P> | |
465 | The deprecated members are there to provide backwards compatability with old versions. | |
466 | To use them you need to define <CODE>BOOST_IOSTREAMS_USE_DEPRECATED</CODE>. | |
467 | The descriptor is always closed by <CODE>close</CODE> but only closed in destructors if <CODE>close_on_exit</CODE> is <CODE>true</CODE>. | |
468 | </P> | |
469 | ||
470 | <A NAME="file_descriptor_open"></A> | |
471 | <H4><CODE>file_descriptor::open</CODE></H4> | |
472 | ||
473 | <PRE CLASS="broken_ie"> <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> Path> | |
474 | <SPAN CLASS="keyword">void</SPAN> open( <SPAN CLASS="keyword">const</SPAN> Path& pathname, | |
475 | std::ios_base::open_mode mode = | |
476 | std::ios_base::in | std::ios_base::out ); | |
477 | <SPAN CLASS="keyword">void</SPAN> open( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
478 | ||
479 | <SPAN CLASS='comment'>// Windows-only</SPAN> | |
480 | <SPAN CLASS="keyword">void</SPAN> open( HANDLE hFile, <SPAN CLASS="keyword">file_descriptor_flags</SPAN> ); | |
481 | ||
482 | <SPAN CLASS='comment'>// Deprecated</SPAN> | |
483 | <SPAN CLASS="keyword">void</SPAN> open( <SPAN CLASS="keyword">int</SPAN> fd, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> ); | |
484 | ||
485 | <SPAN CLASS='comment'>// Deprecated, Windows-only</SPAN> | |
486 | <SPAN CLASS="keyword">void</SPAN> open( HANDLE hFile, <SPAN CLASS="keyword">bool</SPAN> close_on_exit = <SPAN CLASS="keyword">false</SPAN> );</PRE> | |
487 | ||
488 | <P> | |
489 | The parameters of <CODE>open</CODE> the same as those of the corresponding constructors. | |
490 | If the file descriptor already holds a file, it'll be closed | |
491 | (unless opened or constructed with <CODE>never_close_handle</CODE>). | |
492 | </P> | |
493 | ||
494 | <A NAME="file_descriptor_is_open"></A> | |
495 | <H4><CODE>file_descriptor::is_open</CODE></H4> | |
496 | ||
497 | <PRE CLASS="broken_ie"> <SPAN CLASS="keyword">bool</SPAN> is_open() <SPAN CLASS="keyword">const</SPAN>;</PRE> | |
498 | ||
499 | <P>Returns <CODE><SPAN CLASS="keyword">true</SPAN></CODE> if the underlying file was opened successfully.</P> | |
500 | ||
501 | <A NAME="file_descriptor_handle"></A> | |
502 | <H4><CODE>file_descriptor::handle</CODE></H4> | |
503 | ||
504 | <PRE CLASS="broken_ie"> handle_type handle() <SPAN CLASS="keyword">const</SPAN>;</PRE> | |
505 | ||
506 | <P>Returns the underlying OS file descriptor. On Windows, this is a <CODE>HANDLE</CODE>. On other systems, it is an <CODE><SPAN CLASS="keyword">int</SPAN></CODE>.</P> | |
507 | ||
508 | <!-- Begin Footnotes --> | |
509 | ||
510 | <HR> | |
511 | ||
512 | <P> | |
513 | <A CLASS="footnote_ref" NAME="note_1" HREF="#note_1_ref"><SUP>[1]</SUP></A><A CLASS="bib_ref" HREF="../bibliography.html#iso">[I<SPAN STYLE="font-size:80%">SO</SPAN>]</A>, Table 92. | |
514 | </P> | |
515 | ||
516 | <!-- End Footnotes --> | |
517 | ||
518 | <!-- Begin Footer --> | |
519 | ||
520 | <HR> | |
521 | ||
522 | <P CLASS="copyright">© Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>© Copyright 2004-2007 <a href="http://www.coderage.com/turkanis/" target="_top">Jonathan Turkanis</a></P> | |
523 | <P CLASS="copyright"> | |
524 | Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at <A HREF="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>) | |
525 | </P> | |
526 | ||
527 | <!-- End Footer --> | |
528 | ||
529 | </BODY> |