docs/manual: extend makedev syntax section

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(-)

All,

On 2024-01-18 17:08 +0100, yann.morin@orange.com spake thusly:
> 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;

Woops... *flags

Regards,
Yann E. MORIN.

>   - 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
>

On Thu, 18 Jan 2024 17:08:50 +0100
<yann.morin@orange.com> wrote:

> 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(-)

Applied to master (with the typo in the commit log fixed), thanks!

Thomas

>>>>> "Thomas" == Thomas Petazzoni via buildroot <buildroot@buildroot.org> writes:

 > On Thu, 18 Jan 2024 17:08:50 +0100
 > <yann.morin@orange.com> wrote:

 >> 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(-)

 > Applied to master (with the typo in the commit log fixed), thanks!

Committed to 2023.02.x and 2023.11.x, thanks.