1// -*- mode:doc; -*-
2// vim: set syntax=asciidoc:
3
4[[makedev-syntax]]
5== Makedev syntax documentation
6
7The makedev syntax is used in several places in Buildroot to
8define changes to be made for permissions, or which device files to
9create and how to create them, in order to avoid calls to mknod.
10
11This syntax is derived from the makedev utility, and more complete
12documentation can be found in the +package/makedevs/README+ file.
13
14It takes the form of a space separated list of fields, one file per
15line; the fields are:
16
17|===========================================================
18|name |type |mode |uid |gid |major |minor |start |inc |count
19|===========================================================
20
21There are a few non-trivial blocks:
22
23- +name+ is the path to the file you want to create/modify
24- +type+ is the type of the file, being one of:
25  * `f`: a regular file, which must already exist
26  * `F`: a regular file, which is ignored and not created if missing
27  * `d`: a directory, which is created, as well as its parents, if missing
28  * `r`: a directory recursively, which must already exist
29  * `c`: a character device file, which parent directory must exist
30  * `b`: a block device file, which parent directory must exist
31  * `p`: a named pipe, which parent directory must exist
32- +mode+ are the usual permissions settings (only numerical values
33  are allowed);
34  for type `d`, the mode of existing parents is not changed, but the mode
35  of created parents is set;
36  for types `f`, `F`, and `r`, +mode+ can also be set to +-1+ to not
37  change the mode (and only change uid and gid)
38- +uid+ and +gid+ are the UID and GID to set on this file; can be
39  either numerical values or actual names
40- +major+ and +minor+ are here for device files, set to +-+ for other
41  files
42- +start+, +inc+ and +count+ are for when you want to create a batch
43  of files, and can be reduced to a loop, beginning at +start+,
44  incrementing its counter by +inc+ until it reaches +count+
45
46Let's say you want to change the ownership and permissions of a given
47file; using this syntax, you will need to write:
48
49----
50/usr/bin/foo f 755 0 0 - - - - -
51/usr/bin/bar f 755 root root - - - - -
52/data/buz f 644 buz-user buz-group - - - - -
53/data/baz f -1 baz-user baz-group - - - - -
54----
55
56Alternatively, if you want to change owner of a directory recursively,
57you can write (to set UID to `foo` and GID to `bar` for the directory
58`/usr/share/myapp` and all files and directories below it):
59
60----
61/usr/share/myapp r -1 foo bar - - - - -
62----
63
64On the other hand, if you want to create the device file +/dev/hda+
65and the corresponding 15 files for the partitions, you will need for
66+/dev/hda+:
67
68----
69/dev/hda b 640 root root 3 0 0 0 -
70----
71
72and then for device files corresponding to the partitions of
73+/dev/hda+, +/dev/hdaX+, +X+ ranging from 1 to 15:
74
75----
76/dev/hda b 640 root root 3 1 1 1 15
77----
78
79Extended attributes are supported if
80+BR2_ROOTFS_DEVICE_TABLE_SUPPORTS_EXTENDED_ATTRIBUTES+ is enabled.
81This is done by adding a line starting with +|xattr+ after
82the line describing the file. Right now, only capability
83is supported as extended attribute.
84
85|=====================
86| \|xattr | capability
87|=====================
88
89- +|xattr+ is a "flag" that indicate an extended attribute
90- +capability+ is a capability to add to the previous file
91
92If you want to add the capability cap_sys_admin to the binary foo,
93you will write :
94
95----
96/usr/bin/foo f 755 root root - - - - -
97|xattr cap_sys_admin+eip
98----
99
100You can add several capabilities to a file by using several +|xattr+ lines.
101If you want to add the capability cap_sys_admin and cap_net_admin to the
102binary foo, you will write :
103
104----
105/usr/bin/foo f 755 root root - - - - -
106|xattr cap_sys_admin+eip
107|xattr cap_net_admin+eip
108----
109