basic_file.hpp 27 KB

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