• R/O
  • SSH

posixpp: Commit

The main posixpp library and associated tests.


Commit MetaInfo

Revision2c7097052749d60c03ccd99703d2f43698294318 (tree)
Time2021-05-11 00:59:13
AuthorEric Hopper <hopper@omni...>
CommiterEric Hopper

Log Message

More dup documentation, add some TODOs.

Change Summary

Incremental Difference

diff -r 845b89885277 -r 2c7097052749 pubincludes/posixpp/fd.h
--- a/pubincludes/posixpp/fd.h Sun May 02 23:30:36 2021 -0700
+++ b/pubincludes/posixpp/fd.h Mon May 10 08:59:13 2021 -0700
@@ -51,13 +51,48 @@
5151 //! Avoid if at all possible, just like constructor.
5252 [[nodiscard]] constexpr int as_fd() const noexcept { return fd_; }
5353
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+ */
5575 [[nodiscard]] expected<fd> dup() const noexcept {
5676 using ::syscalls::linux::dup;
5777 return error_cascade(dup(fd_), int_to_fd);
5878 }
5979
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+ */
6196 [[nodiscard]] expected<void> dup2(
6297 fd &newfd,
6398 ::std::optional<bool> cloexec=::std::optional<bool>{}
@@ -77,6 +112,7 @@
77112 );
78113 }
79114 }
115+ //! @}
80116
81117 //! \brief Sets fd to invalid value and also calls close regardless of
82118 //! whether fd is currently an invalid value.
diff -r 845b89885277 -r 2c7097052749 pubincludes/posixpp/simpleio.h
--- a/pubincludes/posixpp/simpleio.h Sun May 02 23:30:36 2021 -0700
+++ b/pubincludes/posixpp/simpleio.h Mon May 10 08:59:13 2021 -0700
@@ -41,7 +41,7 @@
4141
4242 [[nodiscard]] expected<fd>
4343 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
4545 return openat(fd(-100), pathname, flags, modeflags{});
4646 }
4747 [[nodiscard]] expected<fd>
@@ -52,6 +52,7 @@
5252 [[nodiscard]] expected<fd>
5353 inline open(char const *pathname, openflags flags, modeflags mode) noexcept
5454 {
55+ // TODO: Fix hard coded the value for AT_FDCWD
5556 return openat(fd(-100), pathname, flags, mode);
5657 }
5758 [[nodiscard]] expected<fd>
Show on old repository browser