[Buildroot] [PATCH] docs/manual: extend makedev syntax section

* [Buildroot] [PATCH] docs/manual: extend makedev syntax section
@ 2024-01-18 16:08 yann.morin
  2024-01-18 16:26 ` yann.morin
  2024-02-06 10:53 ` Thomas Petazzoni via buildroot
  0 siblings, 2 replies; 4+ messages in thread
From: yann.morin @ 2024-01-18 16:08 UTC (permalink / raw)
  To: buildroot; +Cc: yann.morin

From: "Yann E. MORIN" <yann.morin@orange.com>

The section of the manual describing the makedev syntax is not
up-to-date with the current features, and does not properly describe
existing ones.

  - extend the list of types with the requirements on the existence of
    the target file or directory; for 'c', 'b', and 'p', the existence
    requirement is inherited from mknod(2):

    ERRORS
        ...
        ENOENT A directory component in pathname does not exist or is a
               dangling symbolic link.

    for the other types, the existence requirements are extracted from
    the source of makedev.c;

  - format the types fags, so they are rendered in monospace;

  - extend the 'mode' description, as it can be set to -1 for 'f', 'd',
    or 'r', so that only the uid and gid are set. This is most useful
    for 'r', where setting the same mode recursively for all the
    sub-directories and files alike does not really make sense; indeed
    in this case, the modes are usually set correctly when the package
    (or rootfs overlay) installs the files, and only the uid and gid are
    interesting to set;

  - extend and update the examples to show-case the -1 mode use-case.

Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
---
 docs/manual/makedev-syntax.adoc | 33 +++++++++++++++++++--------------
 1 file changed, 19 insertions(+), 14 deletions(-)

diff --git a/docs/manual/makedev-syntax.adoc b/docs/manual/makedev-syntax.adoc
index d6efb31d42..e63c9233eb 100644
--- a/docs/manual/makedev-syntax.adoc
+++ b/docs/manual/makedev-syntax.adoc
@@ -22,14 +22,19 @@ There are a few non-trivial blocks:
 
 - +name+ is the path to the file you want to create/modify
 - +type+ is the type of the file, being one of:
-  * f: a regular file
-  * d: a directory
-  * r: a directory recursively
-  * c: a character device file
-  * b: a block device file
-  * p: a named pipe
+  * `f`: a regular file, which must already exist
+  * `F`: a regular file, which is ignored and not created if missing
+  * `d`: a directory, which is created, as well as its parents, if missing
+  * `r`: a directory recursively, which must already exist
+  * `c`: a character device file, which parent directory must exist
+  * `b`: a block device file, which parent directory must exist
+  * `p`: a named pipe, which parent directory must exist
 - +mode+ are the usual permissions settings (only numerical values
-  are allowed)
+  are allowed);
+  for type `d`, the mode of existing parents is not changed, but the mode
+  of created parents is set;
+  for types `f`, `F`, and `r`, +mode+ can also be set to +-1+ to not
+  change the mode (and only change uid and gid)
 - +uid+ and +gid+ are the UID and GID to set on this file; can be
   either numerical values or actual names
 - +major+ and +minor+ are here for device files, set to +-+ for other
@@ -38,22 +43,22 @@ There are a few non-trivial blocks:
   of files, and can be reduced to a loop, beginning at +start+,
   incrementing its counter by +inc+ until it reaches +count+
 
-Let's say you want to change the permissions of a given file; using
-this syntax, you will need to write:
+Let's say you want to change the ownership and permissions of a given
+file; using this syntax, you will need to write:
 
 ----
 /usr/bin/foo f 755 0 0 - - - - -
 /usr/bin/bar f 755 root root - - - - -
 /data/buz f 644 buz-user buz-group - - - - -
+/data/baz f -1 baz-user baz-group - - - - -
 ----
 
-Alternatively, if you want to change owner/permission of a directory
-recursively, you can write (to set UID to foo, GID to bar and access
-rights to rwxr-x--- for the directory /usr/share/myapp and all files
-and directories below it):
+Alternatively, if you want to change owner of a directory recursively,
+you can write (to set UID to `foo` and GID to `bar` for the directory
+`/usr/share/myapp` and all files and directories below it):
 
 ----
-/usr/share/myapp r 750 foo bar - - - - -
+/usr/share/myapp r -1 foo bar - - - - -
 ----
 
 On the other hand, if you want to create the device file +/dev/hda+
-- 
2.34.1

____________________________________________________________________________________________________________
Ce message et ses pieces jointes peuvent contenir des informations confidentielles ou privilegiees et ne doivent donc
pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu ce message par erreur, veuillez le signaler
a l'expediteur et le detruire ainsi que les pieces jointes. Les messages electroniques etant susceptibles d'alteration,
Orange decline toute responsabilite si ce message a ete altere, deforme ou falsifie. Merci.

This message and its attachments may contain confidential or privileged information that may be protected by law;
they should not be distributed, used or copied without authorisation.
If you have received this email in error, please notify the sender and delete this message and its attachments.
As emails may be altered, Orange is not liable for messages that have been modified, changed or falsified.
Thank you.

_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

^ permalink raw reply related	[flat|nested] 4+ messages in thread