Welcome to little lamb

Code » limb » commit 535b2de

doc: Complete posixplz.h - Also add mkfiletemp(), touch()..

author Olivier Brunel
2023-07-02 13:04:38 UTC
committer Olivier Brunel
2023-07-24 10:16:42 UTC
parent 0b9c56ed23dbe7feea2a077552415d2bbeb2d73f

doc: Complete posixplz.h - Also add mkfiletemp(), touch()..

..and unlink_void().

src/doc/posixplz.h.0.md +12 -5
src/doc/posixplz.h/mkfiletemp.3.md +64 -0
src/doc/posixplz.h/mkfiletempat.3.md +1 -53
src/doc/posixplz.h/touch.3.md +36 -0
src/doc/posixplz.h/unlink_void.3.md +23 -0
src/doc/posixplz.h/unlinkat_void.3.md +1 -19
src/liblimb/include/limb/posixplz.h +1 -0

diff --git a/src/doc/posixplz.h.0.md b/src/doc/posixplz.h.0.md
index 6b0d387..2845332 100644
--- a/src/doc/posixplz.h.0.md
+++ b/src/doc/posixplz.h.0.md
@@ -13,16 +13,23 @@ posixplz.h - functions that maybe should be in POSIX :-)
 
 This header defines functions that aren't but maybe should be in POSIX.
 
-! INFO: skalibs
-! This header is a complement to skalibs' own [skalibs/posixplz.h](0) and
-! thusly includes said header.
+<inc skalibs.md>
 
 ## Functions
 
 The following functions/macros are defined :
 
-: [mkfiletempat](3)
+: [mkfiletemp](3)
 :: To open a new temporary file.
 
-: [unlinkat_void](3)
+: [mkfiletempat](3)
+:: Similar to [mkfiletemp](3) only with a file descriptor for relative path.
+
+: [touch](3)
+:: To "touch" a file, i.e. update its atime & mtime to the current time.
+
+: [unlink_void](3)
 :: To remove a file without affecting `errno`.
+
+: [unlinkat_void](3)
+:: Similar to [unlink_void](3) only with a file descriptor for relative path.
diff --git a/src/doc/posixplz.h/mkfiletemp.3.md b/src/doc/posixplz.h/mkfiletemp.3.md
new file mode 100644
index 0000000..09ed8ad
--- /dev/null
+++ b/src/doc/posixplz.h/mkfiletemp.3.md
@@ -0,0 +1,64 @@
+% limb manual
+% mkfiletemp(3)
+
+# NAME
+
+mkfiletemp, mkfiletempat - open a new temporary file
+
+# SYNOPSIS
+
+    #include <limb/posixplz.h>
+
+```pre hl
+typedef int (*create_fn) (const char *<em>file</em>, mode_t <em>mode</em>, void *<em>data</em>)
+typedef int (*createat_fn) (int <em>fd</em>, const char *<em>file</em>, mode_t <em>mode</em>, void *<em>data</em>)
+
+int mkfiletemp(char *<em>name</em>, create_fn <em>fn</em>, mode_t <em>mode</em>, void *<em>data</em>)
+int mkfiletempat(int <em>bfd</em>, char *<em>name</em>, createat_fn <em>fnat</em>, mode_t <em>mode</em>, void *<em>data</em>)
+```
+
+# DESCRIPTION
+
+The `mkfiletemp`() function will open a new temporary file using the function
+pointed by `fn`, passing it a file name based on the template pointed by
+`name` - which must bend with at least 6 characters `X` that will be replaced
+with random (printable) characters - as well as the `mode` and `data` arguments.
+
+The memory pointed by `name` will be modified, replacing the trailing `X`
+characters so that `name` contains the name of the file actually opened.
+
+The `fn` function should create & open a file whose name is pointed by its first
+argument. It should return the file descriptor of the newly created file on
+success, otherwise returning -1 and setting `errno` appropriately. In case of
+failure due to *EEXIST* a new file name will automatically be generated and a
+new call made.
+
+
+The `mkfiletempat`() function is similar to `mkfiletemp`() but except it takes
+a file descriptor `bfd` which will be passed as first argument to `fnat`.
+
+The `fnat` function should create & open a file whose name is pointed by its
+second argument, which, when specifying a relative path, should be determined
+relative to the directory associated with the file descriptor passed as its
+first argument.
+If passed the special value *AT_FDCWD* in the `bfd` parameter, the current
+working directory should be used used.
+
+It should otherwise behave as `fn`, notably returning the file descriptor of the
+newly created file on success, otherwise -1 and setting `errno` appropriately 
+
+# RETURN VALUE
+
+These functions return the file descriptor to the newly created temporary file,
+as returned by `fn` or `fnat`, on success. Otherwise they return -1 and set
+`errno` to indicate the error.
+
+# ERRORS
+
+These functions may fail if :
+
+: *EINVAL*
+:: The template filename pointed by `name` did not end with at least 6 `X`.
+
+They may also fail and set `errno` for any of the errors described for the
+function pointed by `fn` or `fnat`, save for *EEXIST*.
diff --git a/src/doc/posixplz.h/mkfiletempat.3.md b/src/doc/posixplz.h/mkfiletempat.3.md
deleted file mode 100644
index be15a17..0000000
--- a/src/doc/posixplz.h/mkfiletempat.3.md
+++ /dev/null
@@ -1,53 +0,0 @@
-% limb manual
-% mkfiletempat(3)
-
-# NAME
-
-mkfiletempat - open a new temporary file
-
-# SYNOPSIS
-
-    #include <limb/posixplz.h>
-
-```pre hl
-typedef int (*createat_fn) (int <em>fd</em>, const char *<em>file</em>, mode_t <em>mode</em>, void *<em>data</em>)
-
-int mkfiletempat(int <em>bfd</em>, char *<em>name</em>, createat_fn <em>fn</em>, mode_t <em>mode</em>, void *<em>data</em>)
-```
-
-# DESCRIPTION
-
-The `mkfiletempat`() function will open a new temporary file using the function
-pointed by `fn`, passing it the `bfd` argument and a file name based on the
-template pointed by `name` - which must end with at least 6 characters `X` that
-will be replaced by random (printable) characters - as well as the `mode` and
-`data` arguments.
-
-The memory pointed by `name` will be modified, replacing the trailing `X`
-characters so that `name` contains the name of the file actually opened.
-
-The `fn` function should create & open a file whose name is pointed by its
-second argument, which, when specifying a relative path, should be determined
-relative to the directory associated with the file descriptor `bfd`.
-If passed the special value *AT_FDCWD* in the `bfd` parameter, the current
-working directory should be used used.
-
-It should return the file descriptor of the newly created file on success,
-otherwise returning -1 and setting `errno`. In case of failure due to *EEXIST*
-a new file name will automatically be generated and a new call made.
-
-# RETURN VALUE
-
-The `mkfiletempat`() function returns the file descriptor to the newly created
-temporary file, as returned by `fn`, on success. Otherwise it returns -1 and
-sets `errno` to indicate the error.
-
-# ERRORS
-
-The `mkfiletempat`() function may fail if :
-
-: *EINVAL*
-:: The template filename pointed by `name` did not end with at least 6 `X`.
-
-It may also fail and set `errno` for any of the errors described for the
-function pointed by `fn`, save for *EEXIST*.
diff --git a/src/doc/posixplz.h/mkfiletempat.3.md b/src/doc/posixplz.h/mkfiletempat.3.md
new file mode 120000
index 0000000..ce51737
--- /dev/null
+++ b/src/doc/posixplz.h/mkfiletempat.3.md
@@ -0,0 +1 @@
+mkfiletemp.3.md
\ No newline at end of file
diff --git a/src/doc/posixplz.h/touch.3.md b/src/doc/posixplz.h/touch.3.md
new file mode 100644
index 0000000..d728863
--- /dev/null
+++ b/src/doc/posixplz.h/touch.3.md
@@ -0,0 +1,36 @@
+% limb manual
+% touch(3)
+
+# NAME
+
+touch - update a file's atime & mtime timestamps
+
+# SYNOPSIS
+
+    #include <limb/posixplz.h>
+
+```pre hl
+int touch(const char *<em>file</em>)
+```
+
+# DESCRIPTION
+
+The `touch`() function will update both the `atime` and `mtime` timestamps of
+the file named `file`, creating it if it doesn't exist.
+
+# RETURN VALUE
+
+The `touch`() function returns 1 on success. Otherwise it returns 0 and sets
+`errno` to indicate the error.
+
+# ERRORS
+
+The `touch`() function may fail for any of the errors described for
+[open_create](3).
+
+It may also fail and set `errno` for the errors described for [futimens](3),
+[futimes](3) or [utimes](3) depending on what's available on the system.
+
+! NOTE:
+! The availability of functions is determined at compile-time, during the
+! compilation of skalibs.
diff --git a/src/doc/posixplz.h/unlink_void.3.md b/src/doc/posixplz.h/unlink_void.3.md
new file mode 100644
index 0000000..da805ca
--- /dev/null
+++ b/src/doc/posixplz.h/unlink_void.3.md
@@ -0,0 +1,23 @@
+% limb manual
+% unlink_void(3)
+
+# NAME
+
+unlink_void, unlinkat_void - remove a file without affecting errno
+
+# SYNOPSIS
+
+    #include <limb/posixplz.h>
+
+```pre hl
+void unlink_void(const char *<em>file</em>)
+void unlinkat_void(int <em>bfd</em>, const char *<em>file</em>, int <em>flags</em>)
+```
+
+# DESCRIPTION
+
+The `unlink_void`() function calls [unlink](3) with argument `file`, making
+sure the current value of `errno` will /not/ be changed.
+
+The `unlinkat_void`() function calls [unlinkat](3) with arguments `bfd`, `file`
+and `flags`, making sure the current value of `errno` will /not/ be changed.
diff --git a/src/doc/posixplz.h/unlinkat_void.3.md b/src/doc/posixplz.h/unlinkat_void.3.md
deleted file mode 100644
index 561d91b..0000000
--- a/src/doc/posixplz.h/unlinkat_void.3.md
+++ /dev/null
@@ -1,19 +0,0 @@
-% limb manual
-% unlinkat_void(3)
-
-# NAME
-
-unlinkat_void - remove a file without affecting errno
-
-# SYNOPSIS
-
-    #include <limb/posixplz.h>
-
-```pre hl
-void unlinkat_void(int <em>bfd</em>, const char *<em>file</em>, int <em>flags</em>)
-```
-
-# DESCRIPTION
-
-The `unlinkat_void`() function calls [unlinkat](3) with arguments `bfd`, `file`
-and `flags`, making sure the current value of `errno` will /not/ be changed.
diff --git a/src/doc/posixplz.h/unlinkat_void.3.md b/src/doc/posixplz.h/unlinkat_void.3.md
new file mode 120000
index 0000000..f897751
--- /dev/null
+++ b/src/doc/posixplz.h/unlinkat_void.3.md
@@ -0,0 +1 @@
+unlink_void.3.md
\ No newline at end of file
diff --git a/src/liblimb/include/limb/posixplz.h b/src/liblimb/include/limb/posixplz.h
index 03fffca..d730ace 100644
--- a/src/liblimb/include/limb/posixplz.h
+++ b/src/liblimb/include/limb/posixplz.h
@@ -7,6 +7,7 @@
 #include <skalibs/posixplz.h>
 
 typedef int (*createat_fn) (int fd, const char *file, mode_t mode, void *data);
+typedef create_func_ref create_fn;
 
 extern int mkfiletempat(int bfd, char *name, createat_fn fn, mode_t mode, void *data);
 extern void unlinkat_void(int bfd, const char *file, int flags);