1//
2// basic_file.hpp
3// ~~~~~~~~~~~~~~
4//
5// Copyright (c) 2003-2024 Christopher M. Kohlhoff (chris at kohlhoff dot com)
6//
7// Distributed under the Boost Software License, Version 1.0. (See accompanying
8// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
9//
10
11#ifndef BOOST_ASIO_BASIC_FILE_HPP
12#define BOOST_ASIO_BASIC_FILE_HPP
13
14#if defined(_MSC_VER) && (_MSC_VER >= 1200)
15# pragma once
16#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
17
18#include <boost/asio/detail/config.hpp>
19
20#if defined(BOOST_ASIO_HAS_FILE) \
21 || defined(GENERATING_DOCUMENTATION)
22
23#include <string>
24#include <utility>
25#include <boost/asio/any_io_executor.hpp>
26#include <boost/asio/async_result.hpp>
27#include <boost/asio/detail/cstdint.hpp>
28#include <boost/asio/detail/handler_type_requirements.hpp>
29#include <boost/asio/detail/io_object_impl.hpp>
30#include <boost/asio/detail/non_const_lvalue.hpp>
31#include <boost/asio/detail/throw_error.hpp>
32#include <boost/asio/detail/type_traits.hpp>
33#include <boost/asio/error.hpp>
34#include <boost/asio/execution_context.hpp>
35#include <boost/asio/post.hpp>
36#include <boost/asio/file_base.hpp>
37#if defined(BOOST_ASIO_HAS_IOCP)
38# include <boost/asio/detail/win_iocp_file_service.hpp>
39#elif defined(BOOST_ASIO_HAS_IO_URING)
40# include <boost/asio/detail/io_uring_file_service.hpp>
41#endif
42
43#include <boost/asio/detail/push_options.hpp>
44
45namespace boost {
46namespace asio {
47
48#if !defined(BOOST_ASIO_BASIC_FILE_FWD_DECL)
49#define BOOST_ASIO_BASIC_FILE_FWD_DECL
50
51// Forward declaration with defaulted arguments.
52template <typename Executor = any_io_executor>
53class basic_file;
54
55#endif // !defined(BOOST_ASIO_BASIC_FILE_FWD_DECL)
56
57/// Provides file functionality.
58/**
59 * The basic_file class template provides functionality that is common to both
60 * stream-oriented and random-access files.
61 *
62 * @par Thread Safety
63 * @e Distinct @e objects: Safe.@n
64 * @e Shared @e objects: Unsafe.
65 */
66template <typename Executor>
67class basic_file
68 : public file_base
69{
70public:
71 /// The type of the executor associated with the object.
72 typedef Executor executor_type;
73
74 /// Rebinds the file type to another executor.
75 template <typename Executor1>
76 struct rebind_executor
77 {
78 /// The file type when rebound to the specified executor.
79 typedef basic_file<Executor1> other;
80 };
81
82 /// The native representation of a file.
83#if defined(GENERATING_DOCUMENTATION)
84 typedef implementation_defined native_handle_type;
85#elif defined(BOOST_ASIO_HAS_IOCP)
86 typedef detail::win_iocp_file_service::native_handle_type native_handle_type;
87#elif defined(BOOST_ASIO_HAS_IO_URING)
88 typedef detail::io_uring_file_service::native_handle_type native_handle_type;
89#endif
90
91 /// Construct a basic_file without opening it.
92 /**
93 * This constructor initialises a file without opening it.
94 *
95 * @param ex The I/O executor that the file will use, by default, to
96 * dispatch handlers for any asynchronous operations performed on the file.
97 */
98 explicit basic_file(const executor_type& ex)
99 : impl_(0, ex)
100 {
101 }
102
103 /// Construct a basic_file without opening it.
104 /**
105 * This constructor initialises a file without opening it.
106 *
107 * @param context An execution context which provides the I/O executor that
108 * the file will use, by default, to dispatch handlers for any asynchronous
109 * operations performed on the file.
110 */
111 template <typename ExecutionContext>
112 explicit basic_file(ExecutionContext& context,
113 constraint_t<
114 is_convertible<ExecutionContext&, execution_context&>::value,
115 defaulted_constraint
116 > = defaulted_constraint())
117 : impl_(0, 0, context)
118 {
119 }
120
121 /// Construct and open a basic_file.
122 /**
123 * This constructor initialises a file and opens it.
124 *
125 * @param ex The I/O executor that the file will use, by default, to
126 * dispatch handlers for any asynchronous operations performed on the file.
127 *
128 * @param path The path name identifying the file to be opened.
129 *
130 * @param open_flags A set of flags that determine how the file should be
131 * opened.
132 */
133 explicit basic_file(const executor_type& ex,
134 const char* path, file_base::flags open_flags)
135 : impl_(0, ex)
136 {
137 boost::system::error_code ec;
138 impl_.get_service().open(impl_.get_implementation(), path, open_flags, ec);
139 boost::asio::detail::throw_error(ec, "open");
140 }
141
142 /// Construct a basic_file without opening it.
143 /**
144 * This constructor initialises a file and opens it.
145 *
146 * @param context An execution context which provides the I/O executor that
147 * the file will use, by default, to dispatch handlers for any asynchronous
148 * operations performed on the file.
149 *
150 * @param path The path name identifying the file to be opened.
151 *
152 * @param open_flags A set of flags that determine how the file should be
153 * opened.
154 */
155 template <typename ExecutionContext>
156 explicit basic_file(ExecutionContext& context,
157 const char* path, file_base::flags open_flags,
158 constraint_t<
159 is_convertible<ExecutionContext&, execution_context&>::value,
160 defaulted_constraint
161 > = defaulted_constraint())
162 : impl_(0, 0, context)
163 {
164 boost::system::error_code ec;
165 impl_.get_service().open(impl_.get_implementation(), path, open_flags, ec);
166 boost::asio::detail::throw_error(ec, "open");
167 }
168
169 /// Construct and open a basic_file.
170 /**
171 * This constructor initialises a file and opens it.
172 *
173 * @param ex The I/O executor that the file will use, by default, to
174 * dispatch handlers for any asynchronous operations performed on the file.
175 *
176 * @param path The path name identifying the file to be opened.
177 *
178 * @param open_flags A set of flags that determine how the file should be
179 * opened.
180 */
181 explicit basic_file(const executor_type& ex,
182 const std::string& path, file_base::flags open_flags)
183 : impl_(0, ex)
184 {
185 boost::system::error_code ec;
186 impl_.get_service().open(impl_.get_implementation(),
187 path.c_str(), open_flags, ec);
188 boost::asio::detail::throw_error(ec, "open");
189 }
190
191 /// Construct a basic_file without opening it.
192 /**
193 * This constructor initialises a file and opens it.
194 *
195 * @param context An execution context which provides the I/O executor that
196 * the file will use, by default, to dispatch handlers for any asynchronous
197 * operations performed on the file.
198 *
199 * @param path The path name identifying the file to be opened.
200 *
201 * @param open_flags A set of flags that determine how the file should be
202 * opened.
203 */
204 template <typename ExecutionContext>
205 explicit basic_file(ExecutionContext& context,
206 const std::string& path, file_base::flags open_flags,
207 constraint_t<
208 is_convertible<ExecutionContext&, execution_context&>::value,
209 defaulted_constraint
210 > = defaulted_constraint())
211 : impl_(0, 0, context)
212 {
213 boost::system::error_code ec;
214 impl_.get_service().open(impl_.get_implementation(),
215 path.c_str(), open_flags, ec);
216 boost::asio::detail::throw_error(ec, "open");
217 }
218
219 /// Construct a basic_file on an existing native file handle.
220 /**
221 * This constructor initialises a file object to hold an existing native file.
222 *
223 * @param ex The I/O executor that the file will use, by default, to
224 * dispatch handlers for any asynchronous operations performed on the file.
225 *
226 * @param native_file A native file handle.
227 *
228 * @throws boost::system::system_error Thrown on failure.
229 */
230 basic_file(const executor_type& ex, const native_handle_type& native_file)
231 : impl_(0, ex)
232 {
233 boost::system::error_code ec;
234 impl_.get_service().assign(
235 impl_.get_implementation(), native_file, ec);
236 boost::asio::detail::throw_error(ec, "assign");
237 }
238
239 /// Construct a basic_file on an existing native file.
240 /**
241 * This constructor initialises a file object to hold an existing native file.
242 *
243 * @param context An execution context which provides the I/O executor that
244 * the file will use, by default, to dispatch handlers for any asynchronous
245 * operations performed on the file.
246 *
247 * @param native_file A native file.
248 *
249 * @throws boost::system::system_error Thrown on failure.
250 */
251 template <typename ExecutionContext>
252 basic_file(ExecutionContext& context, const native_handle_type& native_file,
253 constraint_t<
254 is_convertible<ExecutionContext&, execution_context&>::value,
255 defaulted_constraint
256 > = defaulted_constraint())
257 : impl_(0, 0, context)
258 {
259 boost::system::error_code ec;
260 impl_.get_service().assign(
261 impl_.get_implementation(), native_file, ec);
262 boost::asio::detail::throw_error(ec, "assign");
263 }
264
265 /// Move-construct a basic_file from another.
266 /**
267 * This constructor moves a file from one object to another.
268 *
269 * @param other The other basic_file object from which the move will
270 * occur.
271 *
272 * @note Following the move, the moved-from object is in the same state as if
273 * constructed using the @c basic_file(const executor_type&) constructor.
274 */
275 basic_file(basic_file&& other) noexcept
276 : impl_(std::move(other.impl_))
277 {
278 }
279
280 /// Move-assign a basic_file from another.
281 /**
282 * This assignment operator moves a file from one object to another.
283 *
284 * @param other The other basic_file object from which the move will
285 * occur.
286 *
287 * @note Following the move, the moved-from object is in the same state as if
288 * constructed using the @c basic_file(const executor_type&) constructor.
289 */
290 basic_file& operator=(basic_file&& other)
291 {
292 impl_ = std::move(other.impl_);
293 return *this;
294 }
295
296 // All files have access to each other's implementations.
297 template <typename Executor1>
298 friend class basic_file;
299
300 /// Move-construct a basic_file from a file of another executor type.
301 /**
302 * This constructor moves a file from one object to another.
303 *
304 * @param other The other basic_file object from which the move will
305 * occur.
306 *
307 * @note Following the move, the moved-from object is in the same state as if
308 * constructed using the @c basic_file(const executor_type&) constructor.
309 */
310 template <typename Executor1>
311 basic_file(basic_file<Executor1>&& other,
312 constraint_t<
313 is_convertible<Executor1, Executor>::value,
314 defaulted_constraint
315 > = defaulted_constraint())
316 : impl_(std::move(other.impl_))
317 {
318 }
319
320 /// Move-assign a basic_file from a file of another executor type.
321 /**
322 * This assignment operator moves a file from one object to another.
323 *
324 * @param other The other basic_file object from which the move will
325 * occur.
326 *
327 * @note Following the move, the moved-from object is in the same state as if
328 * constructed using the @c basic_file(const executor_type&) constructor.
329 */
330 template <typename Executor1>
331 constraint_t<
332 is_convertible<Executor1, Executor>::value,
333 basic_file&
334 > operator=(basic_file<Executor1>&& other)
335 {
336 basic_file tmp(std::move(other));
337 impl_ = std::move(tmp.impl_);
338 return *this;
339 }
340
341 /// Get the executor associated with the object.
342 const executor_type& get_executor() noexcept
343 {
344 return impl_.get_executor();
345 }
346
347 /// Open the file using the specified path.
348 /**
349 * This function opens the file so that it will use the specified path.
350 *
351 * @param path The path name identifying the file to be opened.
352 *
353 * @param open_flags A set of flags that determine how the file should be
354 * opened.
355 *
356 * @throws boost::system::system_error Thrown on failure.
357 *
358 * @par Example
359 * @code
360 * boost::asio::stream_file file(my_context);
361 * file.open("/path/to/my/file", boost::asio::stream_file::read_only);
362 * @endcode
363 */
364 void open(const char* path, file_base::flags open_flags)
365 {
366 boost::system::error_code ec;
367 impl_.get_service().open(impl_.get_implementation(), path, open_flags, ec);
368 boost::asio::detail::throw_error(ec, "open");
369 }
370
371 /// Open the file using the specified path.
372 /**
373 * This function opens the file so that it will use the specified path.
374 *
375 * @param path The path name identifying the file to be opened.
376 *
377 * @param open_flags A set of flags that determine how the file should be
378 * opened.
379 *
380 * @param ec Set to indicate what error occurred, if any.
381 *
382 * @par Example
383 * @code
384 * boost::asio::stream_file file(my_context);
385 * boost::system::error_code ec;
386 * file.open("/path/to/my/file", boost::asio::stream_file::read_only, ec);
387 * if (ec)
388 * {
389 * // An error occurred.
390 * }
391 * @endcode
392 */
393 BOOST_ASIO_SYNC_OP_VOID open(const char* path,
394 file_base::flags open_flags, boost::system::error_code& ec)
395 {
396 impl_.get_service().open(impl_.get_implementation(), path, open_flags, ec);
397 BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
398 }
399
400 /// Open the file using the specified path.
401 /**
402 * This function opens the file so that it will use the specified path.
403 *
404 * @param path The path name identifying the file to be opened.
405 *
406 * @param open_flags A set of flags that determine how the file should be
407 * opened.
408 *
409 * @throws boost::system::system_error Thrown on failure.
410 *
411 * @par Example
412 * @code
413 * boost::asio::stream_file file(my_context);
414 * file.open("/path/to/my/file", boost::asio::stream_file::read_only);
415 * @endcode
416 */
417 void open(const std::string& path, file_base::flags open_flags)
418 {
419 boost::system::error_code ec;
420 impl_.get_service().open(impl_.get_implementation(),
421 path.c_str(), open_flags, ec);
422 boost::asio::detail::throw_error(ec, "open");
423 }
424
425 /// Open the file using the specified path.
426 /**
427 * This function opens the file so that it will use the specified path.
428 *
429 * @param path The path name identifying the file to be opened.
430 *
431 * @param open_flags A set of flags that determine how the file should be
432 * opened.
433 *
434 * @param ec Set to indicate what error occurred, if any.
435 *
436 * @par Example
437 * @code
438 * boost::asio::stream_file file(my_context);
439 * boost::system::error_code ec;
440 * file.open("/path/to/my/file", boost::asio::stream_file::read_only, ec);
441 * if (ec)
442 * {
443 * // An error occurred.
444 * }
445 * @endcode
446 */
447 BOOST_ASIO_SYNC_OP_VOID open(const std::string& path,
448 file_base::flags open_flags, boost::system::error_code& ec)
449 {
450 impl_.get_service().open(impl_.get_implementation(),
451 path.c_str(), open_flags, ec);
452 BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
453 }
454
455 /// Assign an existing native file to the file.
456 /*
457 * This function opens the file to hold an existing native file.
458 *
459 * @param native_file A native file.
460 *
461 * @throws boost::system::system_error Thrown on failure.
462 */
463 void assign(const native_handle_type& native_file)
464 {
465 boost::system::error_code ec;
466 impl_.get_service().assign(
467 impl_.get_implementation(), native_file, ec);
468 boost::asio::detail::throw_error(ec, "assign");
469 }
470
471 /// Assign an existing native file to the file.
472 /*
473 * This function opens the file to hold an existing native file.
474 *
475 * @param native_file A native file.
476 *
477 * @param ec Set to indicate what error occurred, if any.
478 */
479 BOOST_ASIO_SYNC_OP_VOID assign(const native_handle_type& native_file,
480 boost::system::error_code& ec)
481 {
482 impl_.get_service().assign(
483 impl_.get_implementation(), native_file, ec);
484 BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
485 }
486
487 /// Determine whether the file is open.
488 bool is_open() const
489 {
490 return impl_.get_service().is_open(impl_.get_implementation());
491 }
492
493 /// Close the file.
494 /**
495 * This function is used to close the file. Any asynchronous read or write
496 * operations will be cancelled immediately, and will complete with the
497 * boost::asio::error::operation_aborted error.
498 *
499 * @throws boost::system::system_error Thrown on failure. Note that, even if
500 * the function indicates an error, the underlying descriptor is closed.
501 */
502 void close()
503 {
504 boost::system::error_code ec;
505 impl_.get_service().close(impl_.get_implementation(), ec);
506 boost::asio::detail::throw_error(ec, "close");
507 }
508
509 /// Close the file.
510 /**
511 * This function is used to close the file. Any asynchronous read or write
512 * operations will be cancelled immediately, and will complete with the
513 * boost::asio::error::operation_aborted error.
514 *
515 * @param ec Set to indicate what error occurred, if any. Note that, even if
516 * the function indicates an error, the underlying descriptor is closed.
517 *
518 * @par Example
519 * @code
520 * boost::asio::stream_file file(my_context);
521 * ...
522 * boost::system::error_code ec;
523 * file.close(ec);
524 * if (ec)
525 * {
526 * // An error occurred.
527 * }
528 * @endcode
529 */
530 BOOST_ASIO_SYNC_OP_VOID close(boost::system::error_code& ec)
531 {
532 impl_.get_service().close(impl_.get_implementation(), ec);
533 BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
534 }
535
536 /// Release ownership of the underlying native file.
537 /**
538 * This function causes all outstanding asynchronous read and write
539 * operations to finish immediately, and the handlers for cancelled
540 * operations will be passed the boost::asio::error::operation_aborted error.
541 * Ownership of the native file is then transferred to the caller.
542 *
543 * @throws boost::system::system_error Thrown on failure.
544 *
545 * @note This function is unsupported on Windows versions prior to Windows
546 * 8.1, and will fail with boost::asio::error::operation_not_supported on
547 * these platforms.
548 */
549#if defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC >= 1400) \
550 && (!defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0603)
551 __declspec(deprecated("This function always fails with "
552 "operation_not_supported when used on Windows versions "
553 "prior to Windows 8.1."))
554#endif
555 native_handle_type release()
556 {
557 boost::system::error_code ec;
558 native_handle_type s = impl_.get_service().release(
559 impl_.get_implementation(), ec);
560 boost::asio::detail::throw_error(ec, "release");
561 return s;
562 }
563
564 /// Release ownership of the underlying native file.
565 /**
566 * This function causes all outstanding asynchronous read and write
567 * operations to finish immediately, and the handlers for cancelled
568 * operations will be passed the boost::asio::error::operation_aborted error.
569 * Ownership of the native file is then transferred to the caller.
570 *
571 * @param ec Set to indicate what error occurred, if any.
572 *
573 * @note This function is unsupported on Windows versions prior to Windows
574 * 8.1, and will fail with boost::asio::error::operation_not_supported on
575 * these platforms.
576 */
577#if defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC >= 1400) \
578 && (!defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0603)
579 __declspec(deprecated("This function always fails with "
580 "operation_not_supported when used on Windows versions "
581 "prior to Windows 8.1."))
582#endif
583 native_handle_type release(boost::system::error_code& ec)
584 {
585 return impl_.get_service().release(impl_.get_implementation(), ec);
586 }
587
588 /// Get the native file representation.
589 /**
590 * This function may be used to obtain the underlying representation of the
591 * file. This is intended to allow access to native file functionality
592 * that is not otherwise provided.
593 */
594 native_handle_type native_handle()
595 {
596 return impl_.get_service().native_handle(impl_.get_implementation());
597 }
598
599 /// Cancel all asynchronous operations associated with the file.
600 /**
601 * This function causes all outstanding asynchronous read and write
602 * operations to finish immediately, and the handlers for cancelled
603 * operations will be passed the boost::asio::error::operation_aborted error.
604 *
605 * @throws boost::system::system_error Thrown on failure.
606 *
607 * @note Calls to cancel() will always fail with
608 * boost::asio::error::operation_not_supported when run on Windows XP, Windows
609 * Server 2003, and earlier versions of Windows, unless
610 * BOOST_ASIO_ENABLE_CANCELIO is defined. However, the CancelIo function has
611 * two issues that should be considered before enabling its use:
612 *
613 * @li It will only cancel asynchronous operations that were initiated in the
614 * current thread.
615 *
616 * @li It can appear to complete without error, but the request to cancel the
617 * unfinished operations may be silently ignored by the operating system.
618 * Whether it works or not seems to depend on the drivers that are installed.
619 *
620 * For portable cancellation, consider using the close() function to
621 * simultaneously cancel the outstanding operations and close the file.
622 *
623 * When running on Windows Vista, Windows Server 2008, and later, the
624 * CancelIoEx function is always used. This function does not have the
625 * problems described above.
626 */
627#if defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC >= 1400) \
628 && (!defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0600) \
629 && !defined(BOOST_ASIO_ENABLE_CANCELIO)
630 __declspec(deprecated("By default, this function always fails with "
631 "operation_not_supported when used on Windows XP, Windows Server 2003, "
632 "or earlier. Consult documentation for details."))
633#endif
634 void cancel()
635 {
636 boost::system::error_code ec;
637 impl_.get_service().cancel(impl_.get_implementation(), ec);
638 boost::asio::detail::throw_error(ec, "cancel");
639 }
640
641 /// Cancel all asynchronous operations associated with the file.
642 /**
643 * This function causes all outstanding asynchronous read and write
644 * operations to finish immediately, and the handlers for cancelled
645 * operations will be passed the boost::asio::error::operation_aborted error.
646 *
647 * @param ec Set to indicate what error occurred, if any.
648 *
649 * @note Calls to cancel() will always fail with
650 * boost::asio::error::operation_not_supported when run on Windows XP, Windows
651 * Server 2003, and earlier versions of Windows, unless
652 * BOOST_ASIO_ENABLE_CANCELIO is defined. However, the CancelIo function has
653 * two issues that should be considered before enabling its use:
654 *
655 * @li It will only cancel asynchronous operations that were initiated in the
656 * current thread.
657 *
658 * @li It can appear to complete without error, but the request to cancel the
659 * unfinished operations may be silently ignored by the operating system.
660 * Whether it works or not seems to depend on the drivers that are installed.
661 *
662 * For portable cancellation, consider using the close() function to
663 * simultaneously cancel the outstanding operations and close the file.
664 *
665 * When running on Windows Vista, Windows Server 2008, and later, the
666 * CancelIoEx function is always used. This function does not have the
667 * problems described above.
668 */
669#if defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC >= 1400) \
670 && (!defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0600) \
671 && !defined(BOOST_ASIO_ENABLE_CANCELIO)
672 __declspec(deprecated("By default, this function always fails with "
673 "operation_not_supported when used on Windows XP, Windows Server 2003, "
674 "or earlier. Consult documentation for details."))
675#endif
676 BOOST_ASIO_SYNC_OP_VOID cancel(boost::system::error_code& ec)
677 {
678 impl_.get_service().cancel(impl_.get_implementation(), ec);
679 BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
680 }
681
682 /// Get the size of the file.
683 /**
684 * This function determines the size of the file, in bytes.
685 *
686 * @throws boost::system::system_error Thrown on failure.
687 */
688 uint64_t size() const
689 {
690 boost::system::error_code ec;
691 uint64_t s = impl_.get_service().size(impl_.get_implementation(), ec);
692 boost::asio::detail::throw_error(ec, "size");
693 return s;
694 }
695
696 /// Get the size of the file.
697 /**
698 * This function determines the size of the file, in bytes.
699 *
700 * @param ec Set to indicate what error occurred, if any.
701 */
702 uint64_t size(boost::system::error_code& ec) const
703 {
704 return impl_.get_service().size(impl_.get_implementation(), ec);
705 }
706
707 /// Alter the size of the file.
708 /**
709 * This function resizes the file to the specified size, in bytes. If the
710 * current file size exceeds @c n then any extra data is discarded. If the
711 * current size is less than @c n then the file is extended and filled with
712 * zeroes.
713 *
714 * @param n The new size for the file.
715 *
716 * @throws boost::system::system_error Thrown on failure.
717 */
718 void resize(uint64_t n)
719 {
720 boost::system::error_code ec;
721 impl_.get_service().resize(impl_.get_implementation(), n, ec);
722 boost::asio::detail::throw_error(ec, "resize");
723 }
724
725 /// Alter the size of the file.
726 /**
727 * This function resizes the file to the specified size, in bytes. If the
728 * current file size exceeds @c n then any extra data is discarded. If the
729 * current size is less than @c n then the file is extended and filled with
730 * zeroes.
731 *
732 * @param n The new size for the file.
733 *
734 * @param ec Set to indicate what error occurred, if any.
735 */
736 BOOST_ASIO_SYNC_OP_VOID resize(uint64_t n, boost::system::error_code& ec)
737 {
738 impl_.get_service().resize(impl_.get_implementation(), n, ec);
739 BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
740 }
741
742 /// Synchronise the file to disk.
743 /**
744 * This function synchronises the file data and metadata to disk. Note that
745 * the semantics of this synchronisation vary between operation systems.
746 *
747 * @throws boost::system::system_error Thrown on failure.
748 */
749 void sync_all()
750 {
751 boost::system::error_code ec;
752 impl_.get_service().sync_all(impl_.get_implementation(), ec);
753 boost::asio::detail::throw_error(ec, "sync_all");
754 }
755
756 /// Synchronise the file to disk.
757 /**
758 * This function synchronises the file data and metadata to disk. Note that
759 * the semantics of this synchronisation vary between operation systems.
760 *
761 * @param ec Set to indicate what error occurred, if any.
762 */
763 BOOST_ASIO_SYNC_OP_VOID sync_all(boost::system::error_code& ec)
764 {
765 impl_.get_service().sync_all(impl_.get_implementation(), ec);
766 BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
767 }
768
769 /// Synchronise the file data to disk.
770 /**
771 * This function synchronises the file data to disk. Note that the semantics
772 * of this synchronisation vary between operation systems.
773 *
774 * @throws boost::system::system_error Thrown on failure.
775 */
776 void sync_data()
777 {
778 boost::system::error_code ec;
779 impl_.get_service().sync_data(impl_.get_implementation(), ec);
780 boost::asio::detail::throw_error(ec, "sync_data");
781 }
782
783 /// Synchronise the file data to disk.
784 /**
785 * This function synchronises the file data to disk. Note that the semantics
786 * of this synchronisation vary between operation systems.
787 *
788 * @param ec Set to indicate what error occurred, if any.
789 */
790 BOOST_ASIO_SYNC_OP_VOID sync_data(boost::system::error_code& ec)
791 {
792 impl_.get_service().sync_data(impl_.get_implementation(), ec);
793 BOOST_ASIO_SYNC_OP_VOID_RETURN(ec);
794 }
795
796protected:
797 /// Protected destructor to prevent deletion through this type.
798 /**
799 * This function destroys the file, cancelling any outstanding asynchronous
800 * operations associated with the file as if by calling @c cancel.
801 */
802 ~basic_file()
803 {
804 }
805
806#if defined(BOOST_ASIO_HAS_IOCP)
807 detail::io_object_impl<detail::win_iocp_file_service, Executor> impl_;
808#elif defined(BOOST_ASIO_HAS_IO_URING)
809 detail::io_object_impl<detail::io_uring_file_service, Executor> impl_;
810#endif
811
812private:
813 // Disallow copying and assignment.
814 basic_file(const basic_file&) = delete;
815 basic_file& operator=(const basic_file&) = delete;
816};
817
818} // namespace asio
819} // namespace boost
820
821#include <boost/asio/detail/pop_options.hpp>
822
823#endif // defined(BOOST_ASIO_HAS_FILE)
824 // || defined(GENERATING_DOCUMENTATION)
825
826#endif // BOOST_ASIO_BASIC_FILE_HPP
827

source code of boost/libs/asio/include/boost/asio/basic_file.hpp