Message ID | e050e870b2afb35643036a87df540add584c95b4.1705594130.git.yann.morin@orange.com |
---|---|
State | Accepted |
Headers | show |
Series | docs/manual: extend makedev syntax section | expand |
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.
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+