###
### Configures control of SetId permissions.
###
### To activate the use of this file, add "setid-control"
### to the "FEATURES" variable, in your "/etc/make.conf" file.
###
### Notes on the format of this file:
### - fields are separated by colons (':');
### - if two (or more) lines have the same package category and name, only
###       the first one is ever matched (the others are ignored).
### - empty lines, and lines containing only space characters, are ignored;
### - decorating space characters (spaces, tabulations, etc.) are not allowed;
### - space characters which are part of a field value, must be escaped with
###       a backslash ('\') character;
### - lines beginning with a number sign ('#'), not preceded 
###       by any space character, are ignored (number signs anywhere else
###       are not, so do not try to use comments at the end of a line).
###
### Fields, in order:
### - the package category and name (in the form: category/name);
### - the file absolute path;
### - the file user (name, or id, if unnamed);
### - the file group (name, or id, if unnamed);
### - the file permissions (as an octal number -see `man chmod`);
### - the file permissions to be set by `emerge` (optional).
###
### Examples:
### 
### sys-apps/slocate:/usr/bin/slocate:root:locate:2711
### sys-apps/util-linux:/bin/mount:root:root:2751:0751
### sys-apps/util-linux:/bin/umount:root:root:2751:0751
###
### The first example means we authorize the file "/usr/bin/slocate", from the
### "sys-apps/slocate" package, file owned by the "root" user,
### and "locate" group, with permissions "2711" (rwx--s--x), to keep its
### SetId permissions when it is installed by `emerge`.
###
### The second and third examples mean that the "/bin/mount"
### and "/bin/umount" files, from the "sys-apps/util-linux" package,
### files owned by the "root "user", and "root" group,
### with permissions "2751" (rwxr-s--x), must be stripped from their SetId
### permissions, as specified by the last field, "0751" (rwxr-x--x).
### 
###
### Rules when `emerge` encounters a file with SetId permissions:
### - If the file matches the package category and name,
###       and the file absolute path fields, but does not match the file user,
###       group, or permissions fields, then the SetId permissions
###       of the executable are stripped, and a warning is displayed (it helps
###       you better control the file permissions, in case of a change of user,
###       group or permissions, but it means you must be careful
###       of these warnings, so executables will not stop working properly,
###       in case of a change which would cause `emerge` to strip
###       the SetId permissions of the file).
### - If the file matches the package category and name, file absolute path,
###       user, group and permissions fields, and the file permissions
###       to be set by `emerge` are defined as the last field, then `emerge`
###       will change the file permissions as defined.
###
### Notes:
### - If `emerge` finds a file with SetId permissions, which is still not
###       defined in this file, it will automatically add an entry,
###       with stripped SetId permissions as the last field, and display
###       a warning. If you accept the original SetId permissions, just remove
###       the last field, and either add the appropriate SetId permissions
###       to the file manually, or re-emerge the package again, so `emerge`
###       will reinstall the file, without stripping the SetId permissions.
### - If you are warned by `emerge` that the file permissions does not match
###       the ones defined in this file, and you set the file permissions to be
###       set by `emerge`, as the last field, then do not forget to also modify
###       this field, as possibly needed by the change of permissions.
###
### Todo:
### - Add a bit of flexibility to the file format (comments everywhere,
###       decorating spaces, and maybe allow space characters
###       as field separators... -the file is grealty easier to read
###       with tabulations, though the line length greatly increase...).
### - Maybe support empty fields (they would match any value...), though it
###       greatly diminishes the usefulness of the setid-control feature.
### - Maybe support more flexible file permissions (like "ugo-s",
###       for the last field -well, for now, it works out of the box,
###       but we might try some checks on this field, so we me think a bit
###       about it).
###

### Here goes the entries...


###
### Ends the file (`emerge` will append default entries after this point).
###