Welcome to little lamb

Code » limb » commit 16a3d8e

djbunix: Add fd related functions

author Olivier Brunel
2024-01-01 19:02:06 UTC
committer Olivier Brunel
2024-01-05 09:47:08 UTC
parent f681bba68dafa716b6a9d30671e43fe0921fc591

djbunix: Add fd related functions

Namely fd_copy, fd_copy2, fd_move, fd_move2 to copy/move fds; and
pipe_internal, pipecoe, pipenb, pipenbcoe to create pipes.

Note all those are from skalibs, we're just documenting here.

src/doc/djbunix.h/djbunix.h.0.md +26 -0
src/doc/djbunix.h/fd_copy.3.md +62 -0
src/doc/djbunix.h/fd_copy2.3.md +1 -0
src/doc/djbunix.h/fd_move.3.md +1 -0
src/doc/djbunix.h/fd_move2.3.md +1 -0
src/doc/djbunix.h/pipe_internal.3.md +44 -0
src/doc/djbunix.h/pipecoe.3.md +1 -0
src/doc/djbunix.h/pipenb.3.md +1 -0
src/doc/djbunix.h/pipenbcoe.3.md +1 -0

diff --git a/src/doc/djbunix.h/djbunix.h.0.md b/src/doc/djbunix.h/djbunix.h.0.md
index d2e618e..5510409 100644
--- a/src/doc/djbunix.h/djbunix.h.0.md
+++ b/src/doc/djbunix.h/djbunix.h.0.md
@@ -255,6 +255,19 @@ The following functions/macros are defined :
 :: Similar to [sa_read](3) but with a limit.
 
 
+: [fd_copy](3)
+:: Wrapper for [dup2](3) that can't be interrupted by signals.
+
+: [fd_copy2](3)
+:: Same as [fd_copy](3) but copies two file descriptors.
+
+: [fd_move](3)
+:: Same as [fd_copy ](3) but closing the original file descriptor.
+
+: [fd_move2](3)
+:: Same as [fd_move](3) but moves two file descriptors.
+
+
 : [fd_close](3)
 :: Close a file descriptor without affecting `errno`.
 
@@ -262,6 +275,19 @@ The following functions/macros are defined :
 :: Return whether or not two file descriptors reference the same file.
 
 
+: [pipenb](3)
+:: Create a pipe in non-blocking mode.
+
+: [pipecoe](3)
+:: Create a pipe in close-on-exec mode.
+
+: [pipenbcoe](3)
+:: Create a pipe in non-blocking & close-on-exec modes.
+
+: [pipe_internal](3)
+:: Create a pipe according to specified flags.
+
+
 : [fd_chdir](3)
 :: Similar to [fchdir](3) but without signal interruption.
 
diff --git a/src/doc/djbunix.h/fd_copy.3.md b/src/doc/djbunix.h/fd_copy.3.md
new file mode 100644
index 0000000..4581f42
--- /dev/null
+++ b/src/doc/djbunix.h/fd_copy.3.md
@@ -0,0 +1,62 @@
+% limb manual
+% fd_copy(3)
+
+# NAME
+
+fd_copy, fd_copy2, fd_move, fd_move2 - copy/move file descriptors
+
+# SYNOPSIS
+
+    #include <limb/djbunix.h>
+
+```pre hl
+int fd_copy(int <em>to</em>, int <em>from</em>)
+int fd_copy2(int <em>to1</em>, int <em>from1</em>, int <em>to2</em>, int <em>from2</em>)
+
+int fd_move(int <em>to</em>, int <em>from</em>)
+int fd_move2(int <em>to1</em>, int <em>from1</em>, int <em>to2</em>, int <em>from2</em>)
+```
+
+# DESCRIPTION
+
+The `fd_copy`() function duplicates the file descriptor `from` into file
+descriptor `to`, so that both refer to the same open file, that cannot be
+interrupted by signals.
+
+The `fd_copy2`() function is similar to `fd_copy`() but duplicating file
+descriptor `from1` to file descriptor `to1` and file descriptor `from2` to file
+descriptor `to2`.
+Either both file descriptors will be copied, or none will have been.
+
+
+The `fd_move`() function is similar to [fd_copy](3) but closing `from`
+afterwards.
+
+The `fd_move2`() function is similar to `fd_move`() but moving file descriptor
+`from1` to file descriptor `to1` and file descriptor `from2` to file
+descriptor `to2`.
+Either both file descriptors will be moved, or none will have been.
+
+It is supported to "re-use" file descriptors, e.g. `to2` can be `from1` and/or
+`from2` can be `to1`, as long as it makes sense.
+
+# RETURN VALUE
+
+These functions return 0 on success. Otherwise they return -1 and set `errno` to
+indicate the error.
+
+# ERRORS
+
+The `fd_copy`(), `fd_copy2`() and `fd_move2`() functions may fail if :
+
+: *EINVAL*
+:: File descriptors are invalid, e.g. `from` and `to` are the same for
+:: `fd_copy`(); `to1` and `from2` are the same for `fd_copy2`(), `from1` and
+:: `from2` are the same /and/ `to1` and `to2` are the same for `fd_move2`()...
+
+These functions may also fail and set `errno` for any of the errors specified
+for [dup2](3), except for *EINTR*.
+
+# SEE ALSO
+
+[fd_same](3)
diff --git a/src/doc/djbunix.h/fd_copy2.3.md b/src/doc/djbunix.h/fd_copy2.3.md
new file mode 120000
index 0000000..7a48e59
--- /dev/null
+++ b/src/doc/djbunix.h/fd_copy2.3.md
@@ -0,0 +1 @@
+fd_copy.3.md
\ No newline at end of file
diff --git a/src/doc/djbunix.h/fd_move.3.md b/src/doc/djbunix.h/fd_move.3.md
new file mode 120000
index 0000000..7a48e59
--- /dev/null
+++ b/src/doc/djbunix.h/fd_move.3.md
@@ -0,0 +1 @@
+fd_copy.3.md
\ No newline at end of file
diff --git a/src/doc/djbunix.h/fd_move2.3.md b/src/doc/djbunix.h/fd_move2.3.md
new file mode 120000
index 0000000..7a48e59
--- /dev/null
+++ b/src/doc/djbunix.h/fd_move2.3.md
@@ -0,0 +1 @@
+fd_copy.3.md
\ No newline at end of file
diff --git a/src/doc/djbunix.h/pipe_internal.3.md b/src/doc/djbunix.h/pipe_internal.3.md
new file mode 100644
index 0000000..1efa1c2
--- /dev/null
+++ b/src/doc/djbunix.h/pipe_internal.3.md
@@ -0,0 +1,44 @@
+% limb manual
+% pipe_internal(3)
+
+# NAME
+
+pipe_internal, pipecoe, pipenb, pipenbcpe - create a pipe
+
+# SYNOPSIS
+
+    #include <limb/djbunix.h>
+
+```pre hl
+int pipe_internal(int *<em>fds</em>, unsigned int <em>flags</em>)
+
+int pipecoe(int *<em>fds</em>)
+int pipenb(int *<em>fds</em>)
+int pipenbcoe(int *<em>fds</em>)
+```
+
+# DESCRIPTION
+
+The `pipe_internal`() creates a pipe and places two file descriptors in `fds[0]`
+and `fds[1]`, the reading and writing ends, respectively, of the pipe.
+
+The created pipe will have its *O_NONBLOCK* and *O_CLOEXEC* flags cleared,
+unless specified (as a bitwise OR value) in `flags`.
+
+The `pipecoe`() macro is similar to `pipe_internal`() with *O_CLOEXEC* set.
+
+The `pipenb`() macro is similar to `pipe_internal`() with *O_NONBLOCK* set.
+
+The `pipenbcoe`() macro is similar to `pipe_internal`() with both *O_CLOEXEC
+| O_NONBLOCK* set.
+
+
+# RETURN VALUE
+
+These functions return 0 on success. Otherwise they return -1 and set `errno` to
+indicate the error.
+
+# ERRORS
+
+These functions may fail and set `errno` for any of the errors specified for
+[pipe2](3) when available, [pipe](3), [coe](3) and [ndelay_on](3) when not.
diff --git a/src/doc/djbunix.h/pipecoe.3.md b/src/doc/djbunix.h/pipecoe.3.md
new file mode 120000
index 0000000..e4f0379
--- /dev/null
+++ b/src/doc/djbunix.h/pipecoe.3.md
@@ -0,0 +1 @@
+pipe_internal.3.md
\ No newline at end of file
diff --git a/src/doc/djbunix.h/pipenb.3.md b/src/doc/djbunix.h/pipenb.3.md
new file mode 120000
index 0000000..e4f0379
--- /dev/null
+++ b/src/doc/djbunix.h/pipenb.3.md
@@ -0,0 +1 @@
+pipe_internal.3.md
\ No newline at end of file
diff --git a/src/doc/djbunix.h/pipenbcoe.3.md b/src/doc/djbunix.h/pipenbcoe.3.md
new file mode 120000
index 0000000..e4f0379
--- /dev/null
+++ b/src/doc/djbunix.h/pipenbcoe.3.md
@@ -0,0 +1 @@
+pipe_internal.3.md
\ No newline at end of file