| Revisão | 2c7097052749d60c03ccd99703d2f43698294318 (tree) |
|---|---|
| Hora | 2021-05-11 00:59:13 |
| Autor | Eric Hopper <hopper@omni...> |
| Commiter | Eric Hopper |
More dup documentation, add some TODOs.
pubincludes/posixpp/fd.h (diff) pubincludes/posixpp/simpleio.h (diff)| @@ -51,13 +51,48 @@ | ||
| 51 | 51 | //! Avoid if at all possible, just like constructor. |
| 52 | 52 | [[nodiscard]] constexpr int as_fd() const noexcept { return fd_; } |
| 53 | 53 | |
| 54 | - //! See man page dup(2) | |
| 54 | + /** | |
| 55 | + * \name Member functions for fd duplication. | |
| 56 | + * | |
| 57 | + * These functions duplicate file descriptors in various ways. It's | |
| 58 | + * tempting to be clever and have the copy constructor and assignment | |
| 59 | + * operators do this. But I think the semantics are subtly different enough | |
| 60 | + * to make that very confusing. | |
| 61 | + * | |
| 62 | + * In the Posix model, there is an underlying kernel global file handle | |
| 63 | + * list that per-process file handles merely refer to. Most attributes | |
| 64 | + * (like the current file position for reads or writes) are attributes of | |
| 65 | + * this global handle. A very small number (most notably the close on exec | |
| 66 | + * flag) are attributes of the process-level file handle. | |
| 67 | + */ | |
| 68 | + //! @{ | |
| 69 | + /** | |
| 70 | + * \brief See man page dup(2) - kind of like a copy constructor. | |
| 71 | + * | |
| 72 | + * The two file descriptors both reference the same underlying kernel file | |
| 73 | + * handle, and so share a file pointer and other attributes. | |
| 74 | + */ | |
| 55 | 75 | [[nodiscard]] expected<fd> dup() const noexcept { |
| 56 | 76 | using ::syscalls::linux::dup; |
| 57 | 77 | return error_cascade(dup(fd_), int_to_fd); |
| 58 | 78 | } |
| 59 | 79 | |
| 60 | - //! See man page dup2(2) or dup3(2) (if the cloexec flag has a value). | |
| 80 | + /** | |
| 81 | + * See man page dup2(2) or dup3(2) (if the cloexec flag has a value). | |
| 82 | + * | |
| 83 | + * This is sort of like an assignment operator that causes the destination | |
| 84 | + * file descriptor to refer to the same kernel file handle that the original | |
| 85 | + * does. | |
| 86 | + * | |
| 87 | + * @param fd File descriptor to replace. May or may not be already open. If | |
| 88 | + * already open, it will be closed, before the original file descriptor is | |
| 89 | + * duplicated into it. | |
| 90 | + * | |
| 91 | + * @param cloexec Whether or not the close on exec flag should be set for | |
| 92 | + * the destination file descriptor. Unlike most attributes associated with | |
| 93 | + * a file handle, this flag is per process fd, not per kernel file handle. | |
| 94 | + * This is intended to save a system call to set this flag. | |
| 95 | + */ | |
| 61 | 96 | [[nodiscard]] expected<void> dup2( |
| 62 | 97 | fd &newfd, |
| 63 | 98 | ::std::optional<bool> cloexec=::std::optional<bool>{} |
| @@ -77,6 +112,7 @@ | ||
| 77 | 112 | ); |
| 78 | 113 | } |
| 79 | 114 | } |
| 115 | + //! @} | |
| 80 | 116 | |
| 81 | 117 | //! \brief Sets fd to invalid value and also calls close regardless of |
| 82 | 118 | //! whether fd is currently an invalid value. |
| @@ -41,7 +41,7 @@ | ||
| 41 | 41 | |
| 42 | 42 | [[nodiscard]] expected<fd> |
| 43 | 43 | inline open(char const *pathname, openflags flags) noexcept { |
| 44 | - // Hard coded the value for AT_FDCWD | |
| 44 | + // TODO: Fix hard coded the value for AT_FDCWD | |
| 45 | 45 | return openat(fd(-100), pathname, flags, modeflags{}); |
| 46 | 46 | } |
| 47 | 47 | [[nodiscard]] expected<fd> |
| @@ -52,6 +52,7 @@ | ||
| 52 | 52 | [[nodiscard]] expected<fd> |
| 53 | 53 | inline open(char const *pathname, openflags flags, modeflags mode) noexcept |
| 54 | 54 | { |
| 55 | + // TODO: Fix hard coded the value for AT_FDCWD | |
| 55 | 56 | return openat(fd(-100), pathname, flags, mode); |
| 56 | 57 | } |
| 57 | 58 | [[nodiscard]] expected<fd> |
Fork