docs/manual: makedevs only accepts numerical values

Because of a limitation in how makedevs resolves names [0], usernames
and groupnames would be resolved with UIDs and GIDs from the host, not
the target.

Fixing makedevs would involve us rewriting a /etc/passwd and /etc/group
parser (not too complex, still not trivial).

Document that the user and group fields should only be numbers, not
names. Also, the manual is currently misleading, as an example indeed
uses names for the user and group fields. Fix that and expand the
explanations.

The mode field should also be numbers, not a rwx combo.

Slight typographical eye-candy about major/minor fields.

[0] it uses getpwnma(3) and getgrnam(3) to resolve names to IDs, and
those only resolve names on the host (i.e. there is no way to specify
a chroot-like feature)

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>

diff --git a/docs/manual/makedev-syntax.txt b/docs/manual/makedev-syntax.txt
index 283119d574b9e65511b65fb1981efda43e1394bb..cae37f77d379db4e1ec4699beb106efd9b31a1c7 100644 (file)
--- a/docs/manual/makedev-syntax.txt
+++ b/docs/manual/makedev-syntax.txt
@@ -28,8 +28,9 @@ There are a few non-trivial blocks:
   * c: a character device file
   * b: a block device file
   * p: a named pipe
-- +mode+, +uid+ and +gid+ are the usual permissions settings
-- +major+ and +minor+ are here for device files - set to - for other
+- +mode+, +uid+ and +gid+ are the usual permissions settings (only
+  numerical values are allowed)
+- +major+ and +minor+ are here for device files, set to +-+ for other
   files
 - +start+, +inc+ and +count+ are for when you want to create a batch
   of files, and can be reduced to a loop, beginning at +start+,
@@ -43,10 +44,12 @@ this syntax, you will need to put:
 ----
 
 Alternatively, if you want to change owner/permission of a directory
-recursively, you can put:
+recursively, you can put (to set UID to 123, GID to 456 and access
+rights to rwxr-x--- for the directory /usr/share/myapp and all files
+and directories below it):
 
 ----
-/usr/share/myapp r 750 myuser myuser - - - - -
+/usr/share/myapp r 750 123 456 - - - - -
 ----
 
 On the other hand, if you want to create the device file +/dev/hda+