author | Olivier Brunel
<jjk@jjacky.com> 2023-07-02 13:04:38 UTC |
committer | Olivier Brunel
<jjk@jjacky.com> 2023-07-24 10:16:42 UTC |
parent | 0b9c56ed23dbe7feea2a077552415d2bbeb2d73f |
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);