RAWHIDE.CONF(5)

🎀 RAWHIDE.CONF(5) 🎀

okay bestie, gather round: this is the manual page for /etc/rawhide.conf, aka the config file for rh(1). It is giving “tiny language, big main character energy,” and honestly? once you get the vibe it is so good. 🫶

✨ NAME ✨

/etc/rawhide.conf — configuration file for rh(1).

💖 DESCRIPTION 💖

The /etc/rawhide.conf file (or something like it) is a standard library of functions that every rh(1) user can use. It is the first file rh(1) reads. Then any files in the /etc/rawhide.conf.d directory (or similar) whose names do not start with a dot (.) get read next, in lexicographic order — those can add more system-wide function definitions. 💅

After that, user-specific configuration is read from ~/.rhrc and ~/.rhrc.d/* files in the same manner.

Then come any files specified by rh(1)'s -f option, followed by the contents of rh(1)'s -e option argument. That -e argument can also contain additional function definitions and a trailing file test expression. All of these share the same syntax. ✨

btw, the system-wide config might live somewhere else depending on operating system preferences — think /usr/local/etc, /opt/local/etc, or /usr/pkg/etc. The output of rh --help will tell you where the system-wide configuration files are on the local system. 🦋

🌸 FILE FORMAT 🌸

The following subsections describe the syntax and semantics of rawhide search criteria source/configuration files.

🎀 File structure 🎀

Every rawhide source/configuration file consists of zero or more function definitions, optionally followed by a file test expression, which is optionally terminated by a semicolon (;).

If a source file does contain a trailing file test expression, that expression becomes the default file test expression — unless another file read later also contains a trailing file test expression, in which case that later expression becomes the default file test expression. It is not expected that any system-wide or user-specific configuration files will contain a trailing file test expression, but they can.

Files specified with the -f option are more likely to contain a trailing file test expression, in which case there is no need for the -e option (explicit or implicit). But if the -e option is also supplied, then any file test expression that it specifies takes precedence.

Technically, even the -e option argument does not require a file test expression (because there is a default which matches everything), but it will usually supply one.

💬 Comments 💬

Search criteria can include explanations in the form of comments. There are three comment styles:

/* C-style comments */ — these start with /*, end with */, and can span multiple lines.
// C++-style comments — these start with // and end at the end of the line.
# Shell-style comments — these start with # and end at the end of the line.

🧚 Grammar 🧚

The rawhide search criteria language is like a tiny subset of the C language's expression syntax, with a few domain-specific additions. All of C's conditional, logical, relational, equality, arithmetic, and bit operators are available. But the only type is integer. There are special tokens to represent various things, some built-in symbols, and user-defined functions.

Here is the grammar of the search criteria language (BNF with a few liberties taken):

         <program> ::=
               <function-list> <expression> ";" EOF
             | <function-list> <expression> EOF
             | <function-list> EOF

         <function-list> ::=
               <function> <function-list>
             | EMPTY

         <function> ::=
             IDENTIFIER <parameters> "{" <return> <expression> <eos> "}"

         <return> ::=
               "return"
             | EMPTY

         <eos> == >
               ";"
             | EMPTY

         <parameters> ::=
               "(" <id-list> ")"
             | "(" ")"
             | EMPTY

         <id-list> ::=
             IDENTIFIER <id-tail>

         <id-tail> ::=
               "," <id-list>
             | EMPTY

         <expression> ::= <or> "?" <expression> ":" <expression> | <or>

         <or> ::= <and> "||" <or> | <and>

         <and> ::= <bitor> "&&" <and> | <bitor>

         <bitor> ::= <bitxor> "|" <bitor> | <bitxor>

         <bitxor> ::= <bitand> "^" <bitxor> | <bitand>

         <bitand> ::= <eq> "&" <bitand> | <eq>

         <eq> ::= <rel> <eq-op> <rel> | <rel>
         <eq-op> ::= "==" | "!="

         <rel> ::= <shift> <rel-op> <shift> | <shift>
         <rel-op> ::= "<" | ">" | "<=" | ">="

         <shift> ::= <add> <shift-op> <shift> | <add>
         <shift-op> ::= "<<" | ">>"

         <add> ::= <mul> <add-op> <add> | <mul>
         <add-op> ::= "+" | "-"

         <mul> ::= <unary> <mul-op> <mul> | <unary>
         <mul-op> ::= "*" | "/" | "%"

         <unary> ::= <unary-op> <unary> | <factor>
         <unary-op> ::= "-" | "~" | "!"

         <factor> ::=
               <number>
             | <user-id>
             | <group-id>
             | "[" <date-time> "]"
             | <pattern>
             | <reference-file>
             | <built-in>
             | <function-call>
             | <parameter>
             | "(" <expression> ")"

         <number> ::=
               DECIMAL
             | DECIMAL NOSPACE <scale>
             | "0" NOSPACE OCTAL
             | "0x" NOSPACE HEXADECIMAL

         <scale> ::=
               "K" | "M" | "G" | "T" | "P" | "E"
             | "k" | "m" | "g" | "t" | "p" | "e"

         <user-id> ::=
               "$" NOSPACE USERNAME
             | "$$"

         <group-id> ::=
               "@" NOSPACE GROUPNAME
             | "@@"

         <date-time> ::=
               DECIMAL "/" DECIMAL "/" DECIMAL
             | DECIMAL "/" DECIMAL "/" DECIMAL DECIMAL
             | DECIMAL "/" DECIMAL "/" DECIMAL DECIMAL ":" DECIMAL
             | DECIMAL "/" DECIMAL "/" DECIMAL DECIMAL ":" DECIMAL ":" DECIMAL

         <pattern> ::=
               STRING
             | STRING NOSPACE "." NOSPACE <pattern-modifier>

         <pattern-modifier> ::=
                        "i"     | "re"     | "rei"
             | "path" | "ipath" | "repath" | "reipath"
             | "link" | "ilink  | "relink" | "reilink"
             | "body" | "ibody  | "rebody" | "reibody"
             | "what" | "iwhat  | "rewhat" | "reiwhat"
             | "mime" | "imime  | "remime" | "reimime"
             | "acl"  | "iacl"  | "reacl"  | "reiacl"
             | "ea"   | "iea"   | "reea"   | "reiea"
             | "sh"

         <reference-file> ::=
             STRING NOSPACE "." NOSPACE <reference-file-field>

         <reference-file-field> ::=
               "exists"   | "dev"     | "major"     | "minor"   | "ino"
             | "mode"     | "type"    | "perm"      | "nlink"   | "uid"
             | "gid"      | "rdev"    | "rmajor"    | "rminor"  | "size"
             | "blksize"  | "blocks"  | "atime"     | "mtime"   | "ctime"
             | "attr"     | "proj"    | "gen"       | "strlen"  | "inode"
             | "nlinks"   | "user"    | "group"     | "sz"      | "accessed"
             | "modified" | "changed" | "attribute" | "project" | "generation"
             | "len"

         <built-in> ::=
               "dev"    | "major"    | "minor"    | "ino"      | "mode"
             | "nlink"  | "uid"      | "gid"      | "rdev"     | "rmajor"
             | "rminor" | "size"     | "blksize"  | "blocks"   | "atime"
             | "mtime"  | "ctime"    | "attr"     | "proj"     | "gen"
             | "nouser" | "nogroup"  | "readable" | "writable" | "executable"
             | "strlen" | "depth"    | "prune"    | "trim"     | "exit"
             | "now"    | "today"    | "second"   | "minute"   | "hour"
             | "day"    | "week"     | "month"    | "year"     | "IFREG"
             | "IFDIR"  | "IFLNK"    | "IFCHR"    | "IFBLK"    | "IFSOCK"
             | "IFIFO"  | "IFDOOR"   | "IFMT"     | "ISUID"    | "ISGID"
             | "ISVTX"  | "IRWXU"    | "IRUSR"    | "IWUSR"    | "IXUSR"
             | "IRWXG"  | "IRGRP"    | "IWGRP"    | "IXGRP"    | "IRWXO"
             | "IROTH"  | "IWOTH"    | "IXOTH"    | "texists"  | "tdev"
             | "tmajor" | "tminor"   | "tino"     | "tmode"    | "tnlink"
             | "tuid"   | "tgid"     | "trdev"    | "trmajor"  | "trminor"
             | "tsize"  | "tblksize" | "tblocks"  | "tatime"   | "tmtime"
             | "tctime" | "tstrlen"

         <function-call> ::=
             IDENTIFIER <arguments>

         <arguments> ::=
               "(" <expr-list> ")"
             | "(" ")"
             | EMPTY

         <expr-list> ::=
             <expression> <expr-tail>

         <expr-tail> ::=
               "," <expr-list>
             | EMPTY

         <parameter> ::=
             IDENTIFIER

🌈 Operators 🌈

The following C operators are available (presented in groups of increasing precedence):

?:  Conditional (i.e., condition-expr ? if-expr : else-expr)

||  Logical or

&&  Logical and

|   Bit or

^   Bit exclusive or

&   Bit and

==  Equals
!=  Not equals

<   Less than
>   Greater than
<=  Less than or equal to
>=  Greater than or equal to

<<  Bit shift left
>>  Bit shift right

+   Addition
-   Subtraction

*   Multiplication
/   Division
%   Modulo (remainder)

-   Minus (unary)
~   Bit not (unary)
!   Logical not (unary)

Parentheses override operator precedence (e.g., (1 + 2) * 3).

Like in C, the ?: and || and && operators use “short-circuit” evaluation. 🎀

With the ternary conditional operator (?:), the second operand is only evaluated when the first operand evaluates to true (i.e., non-zero), and the third operand is only evaluated when the first operand evaluates to false (i.e., zero).

With the logical or operator (||), the second operand is only evaluated when the first operand evaluates to false. Otherwise, it is not necessary.

With the logical and operator (&&), the second operand is only evaluated when the first operand evaluates to true. Otherwise, it is not necessary.

This matters when using the prune, trim, or exit built-ins (see below), because they have control flow side-effects when they are evaluated. It is also important when using the texists built-in, the sh "pattern" modifier, and the exists reference file field (see below).

All the other binary operators always evaluate both operands.

🍓 Numbers 🍓

Numeric constants can be decimal, octal (starting with 0), or hexadecimal (starting with 0x). All numbers are integers. And everything is a number. 💀

Decimal numbers can have a suffix letter that indicates the scale (e.g., 10K), in units based on 1024 (upper case), or based on 1000 (lower case):

K = Kibibytes (KiB, units of 1024)
M = Mebibytes (MiB, units of 1024^2)
G = Gibibytes (GiB, units of 1024^3)
T = Tebibytes (TiB, units of 1024^4)
P = Pebibytes (PiB, units of 1024^5)
E = Exbibytes (EiB, units of 1024^6)

k = Kilobytes  (KB, units of 1000)
m = Megabytes  (MB, units of 1000^2)
g = Gigabytes  (GB, units of 1000^3)
t = Terabytes  (TB, units of 1000^4)
p = Petabytes  (PB, units of 1000^5)
e = Exabytes   (EB, units of 1000^6)

💬 Strings

ok so string literals live inside double quotes (""") — iconic, simple. Any double quote characters inside your string have to be quoted with a preceding backslash character ("\"). Backslashes can also be quoted with a preceding backslash, which is lowkey the same energy. And any backslashes that don't precede a double quote or another backslash? They're just treated as normal characters and get included in the string. no drama, they're just vibing there.

Strings usually contain a pattern to match against file names (or certain other information associated with files). The value of a pattern string is whether or not the pattern match succeeded. Strings can also contain a shell command to execute — and the value of a shell command string is the exit success status of that command. See the Pattern matching and Pattern modifiers sections below for details. Strings can also contain the path of a reference file to use for comparison purposes — see the Reference file fields section below. versatile queen 💅

👤 User IDs

A token starting with a dollar sign ($) immediately followed by a user name evaluates to that user's user ID. It's assumed that user names consist entirely of letters, digits, and dot (.), dash (-), and underscore characters (_). All non-ASCII characters (UTF-8 or ISO-8859-*) are considered to be "letters" — yes, all of them, she's inclusive like that 🫶

The token $$ evaluates to the current user's user ID. it's giving selfie energy tbh.

👥 Group IDs

A token starting with an at sign (@) immediately followed by a group name evaluates to that group's group ID. It's assumed that group names consist entirely of letters, digits, and dot (.), dash (-), and underscore characters (_). All non-ASCII characters (UTF-8 or ISO-8859-*) are considered to be "letters". same rules, different symbol, we love consistency ✨

The token @@ evaluates to the current user's primary group ID.

📅 Dates and date/times

Dates and date/times can be specified between square brackets ([]) — specifically [YYYY/MM/DD] and [YYYY/MM/DD hh:mm:ss]. They're interpreted as being in the local time zone. If the year is specified as a number below 100, then it's interpreted as being a year in the current century. Hours must be in 24-hour time, not 12-hour time — we're not doing AM/PM here bestie.

The seconds component is optional if it is zero (i.e., [YYYY/MM/DD hh:mm]). The minutes component is also optional if both it and the seconds are zero (i.e., [YYYY/MM/DD hh]). The hours component is also optional if it and the minutes and seconds are all zero (i.e., midnight) — then it's just a date. Dates and date/times evaluate to the corresponding number of seconds since the UNIX epoch. iconic math moment 🧮

⚠️ Note that if the month, day, hours, minutes, or seconds are outside their valid ranges, the date or date/time is normalized — so like, the 40th of October is interpreted as the 9th of November, and the time 25:90:90 is interpreted as 2:31:30 the following day. it's not an error, she just fixes it for you 😭 See mktime(3) for details.

🧮 Functions

Functions can be defined to give names to expressions, and to make those names available for use in subsequent expressions. Function names can't be the same as the names of any existing functions or built-in symbols. (no name-stealing, it's rude ✋)

f() { return expr; }

Functions can only contain a return statement or expression. The return keyword and semicolon (;) are optional — so this is equally valid:

f() { expr }

Functions can have parameters. Parameter names can't be the same as the names of any existing functions or built-in symbols either. same rule, bestie.

f(x, y, z) { (x + y) * z }

Functions with no parameters can be defined and called with or without parentheses. queen of flexibility:

f() { expr }
g { f }
g()

A function can only be called if its definition has already been encountered by the parser. So recursive functions are possible, but mutually recursive functions are not. sad but true 💀

The names of functions and parameters must start with a letter or underscore character (_), which can be followed by letters, underscores, and digits. All non-ASCII characters (UTF-8 or ISO-8859-*) are considered to be "letters".

🔮 Built-in symbols

There are various built-in symbols representing inode metadata (i.e., stat(2) structure fields), constants, and other useful information. these are the main characters of the whole operation, honestly 👑

dev — The device number of the device/filesystem that the current candidate file resides on. This is the st_dev field of the corresponding stat(2) structure. See the related major and minor built-ins (next) for extracting the major and minor device numbers from dev.
major — The major device number of the device/filesystem that the current candidate file resides on. This is part of the st_dev field of the corresponding stat(2) structure.
minor — The minor device number of the device/filesystem that the current candidate file resides on. This is part of the st_dev field of the corresponding stat(2) structure.
ino — The inode number of the current candidate file. This is the st_ino field of the corresponding stat(2) structure.
mode — The mode of the current candidate file. This is the st_mode field of the corresponding stat(2) structure. This contains the file type and permissions. The standard library provides the type and perm functions (among others) for extracting the file type and permissions from mode.
nlink — The number of hard links to the current candidate file. This is the st_nlink field of the corresponding stat(2) structure.
uid — The user ID of the owner of the current candidate file. This is the st_uid field of the corresponding stat(2) structure.
gid — The group ID of the group of the current candidate file. This is the st_gid field of the corresponding stat(2) structure.
rdev — The device number of the current candidate file. This is the st_rdev field of the corresponding stat(2) structure. This is only meaningful for character devices and block devices. See the related rmajor and rminor built-ins (next) for extracting the major and minor device numbers from rdev.
rmajor — The major device number of the current candidate file. This is part of the st_rdev field of the corresponding stat(2) structure. This is only meaningful for character devices and block devices.
rminor — The minor device number of the current candidate file. This is part of the st_rdev field of the corresponding stat(2) structure. This is only meaningful for character devices and block devices.
size — The size in bytes of the current candidate file. This is the st_size field of the corresponding stat(2) structure.
- For candidate symlinks (that are not followed with the -y or -Y option), this is the length in bytes of the target path.
- For candidate directories that are readable, this is not the st_size field of the corresponding stat(2) structure. Instead, this is the number of entries it contains (excluding . and ..).
- For candidate directories that are unreadable (and everything else), this is the usual (undocumented) st_size field of the corresponding stat(2) structure.
blksize — The preferred block size for efficient I/O on the current candidate file's filesystem. This is the st_blksize field of the corresponding stat(2) structure. On some filesystems (e.g., zfs), this is specific to each file, rather than to the whole filesystem.
- Note that this is unrelated to the blocks built-in (see next). don't get them confused bestie 🙈
blocks — The number of 512-byte blocks occupied by the current candidate file. This is the st_blocks field of the corresponding stat(2) structure.
atime — The time that the current candidate file was last accessed. This is the st_atime field of the corresponding stat(2) structure.
mtime — The time that the current candidate file's contents were last modified. This is the st_mtime field of the corresponding stat(2) structure.
ctime — The time that the current candidate file's inode was last changed. This is the st_ctime field of the corresponding stat(2) structure.
attr — On Linux, the current candidate file's ext2-style file attribute bit mask. Not all file systems support all file attributes. See chattr(1) and lsattr(1) for details. See /etc/rawhide.conf.d/attributes for all the related predicate functions (e.g., immutable, append, nodump, nocow, dax, ...).
- Note: If the current candidate file is a symlink, it is never followed for the purpose of obtaining the file attributes. This is a decision made by libe2p. This is not affected by the -y or -Y options. Also note that symlinks do not have their own file attributes (i.e., attr is zero).
- On Linux, this is only available on systems with libe2p. On Linux systems without libe2p, this is not a built-in symbol. Instead, this is a place-holder function that returns zero.
- This is also available on FreeBSD, OpenBSD, NetBSD, and macOS. The attributes/flags that are available vary from system to system. See chflags(1) for details. See /etc/rawhide.conf.d/attributes for all the related predicate functions (e.g., uimmutable, uappend, nodump, opaque, ...).
- On other systems, this doesn't exist at all. 💀
proj — On Linux, the current candidate file's ext2-style file project number. Not all file systems support all file attributes. See chattr(1) and lsattr(1) for details.
- Note: If the current candidate file is a symlink, it is always followed for the purpose of obtaining the file project. This is not affected by the -y or -Y options.
- Note: This is only available on Linux systems with libe2p. On Linux systems without libe2p, this is not a built-in symbol. Instead, this is a place-holder function that returns zero. On other systems, this doesn't exist at all.
gen — On Linux, the current candidate file's ext2-style version/generation number. Not all file systems support all file attributes. See chattr(1) and lsattr(1) for details.
- Note: If the current candidate file is a symlink, it is always followed for the purpose of obtaining the file version/generation. This is not affected by the -y or -Y options.
- Note: This is only available on Linux systems with libe2p. On Linux systems without libe2p, this is not a built-in symbol. Instead, this is a place-holder function that returns zero. On other systems, this doesn't exist at all.
nouser — This is true (i.e., non-zero) when the current candidate file's uid does not correspond to any user in the user database (e.g., the local password file /etc/passwd, NIS, and LDAP).
nogroup — This is true (i.e., non-zero) when the current candidate file's gid does not correspond to any group in the group database (e.g., the local group file /etc/group, NIS, and LDAP).

💖 `readable`

True (like, non-zero true) when the current candidate file is readable by the current user. Bestie, listen: this uses the access(2) system call, not the file permissions. So it's giving "can I actually read this rn", not "what do the mode bits say". 🫶

💖 `writable`

True (i.e., non-zero) when the current candidate file is writable by the current user. Again — access(2) system call, not the file permissions. Same vibe, different permission. ✨

💖 `executable`

True (i.e., non-zero) when the current candidate file is executable by the current user. Yep, access(2) system call, not the file permissions. It's the trifecta bestie 💅

💖 `strlen`

This is the length in bytes of the base name of the current candidate file. Heads up though: this is zero for the root directory (/), because root literally has no base name. Not me defending root's name situation 😭

💖 `depth`

How deep the current candidate file is, relative to the starting search directory. The starting search directory itself is depth 0, its children are depth 1, and so on down the tree. 🦋

💖 `prune`

This one always evaluates to true (non-zero), and as a side-effect it makes the directory tree being searched get "pruned". Translation: the current candidate file will not match, and if it's a directory, it will not be searched. It's a speed-up move for your search. 🔥

prune needs to be used with the ?: or || or && operator (see above) to conditionally skip part of a directory tree and search the rest.

prune and the -D (depth-first) option are incompatible. When -D is used, prune will not work — it will not prevent searching below the current candidate path. Same deal with the -U (unlink) option, which implies -D. 🫠

Note: this is counter-intuitive, and I need you to trust me here. prune evaluates to true, even though it effectively causes the file test expression as a whole to evaluate to false (i.e., zero), in order to prevent the current candidate file from matching. The reason prune evaluates to true rather than false is to make expressions like (bad && prune || good) possible as a syntactic alternative to (bad ? prune : good). iykyk 💀

Note: prune and trim are very similar (see next). They both prevent searching below the current candidate path. The only difference between them is whether or not the current candidate path itself is also prevented from matching. Use prune when the current candidate path needs to be excluded. Use trim when it needs to be included. Think of prune as a heavy trim. 🎀

💖 `trim`

Always evaluates to true (non-zero), and as a side-effect it makes the directory tree being searched get "trimmed". Meaning: if the current candidate file is a directory, it will not be searched (exactly like prune). But unlike prune, the current candidate file itself is not prevented from matching. So when the current candidate file isn't a directory, this does literally nothing. Still a speed-up move tho ✨

trim needs to be used with the ?: or || or && operator (see above) to conditionally skip part of a directory tree and search the rest.

trim and the -D (depth-first) option are incompatible. When -D is used, trim will not work — it will not prevent searching below the current candidate path. Same applies to -U (unlink), which implies -D. 🫠

Note: trim and prune are very similar (see above). They both prevent searching below the current candidate path. The only difference is whether or not the current candidate path itself is also prevented from matching. Use trim when the current candidate path needs to be included. Use prune when it needs to be excluded. Think of trim as a light prune. 🦋

💖 `exit`

Always evaluates to true (non-zero), and as a side-effect it terminates the search immediately after the current candidate file. This is the "find the first matching file and then dip" builtin. 👑

exit needs to be used with the ?: or || or && operator (see above) to conditionally terminate the search.

exit can be used in combination with prune and/or trim (see above), e.g. bad && prune || good && exit. Slay.

💖 `now`

The current time (when rh(1) started), in seconds since the UNIX epoch. ⏰

💖 `today`

The time last midnight (local time), in seconds since the UNIX epoch. 🌙

💖 `second`

The value 1. That's it. That's the builtin. 💅

💖 `minute`

The number of seconds in a minute.

💖 `hour`

The number of seconds in an hour.

💖 `day`

The number of seconds in a day.

💖 `week`

The number of seconds in a week.

💖 `month`

The average number of seconds in a month. Yes, average. Months are not all the same length, bestie, that's just how it is 😭

💖 `year`

The average number of seconds in a year.

💖 `IFMT`

Same as the S_IFMT bit mask from C's <sys/stat.h> header file. This bit mask is the bits in the mode that represent the file type. So the file type is (mode & IFMT) (see next), and the file permissions are (mode & ~IFMT) (see below). Bit math girlies rise 🧚

💖 `IFREG`, `IFDIR`, `IFLNK`, `IFCHR`, `IFBLK`, `IFSOCK`, `IFIFO`, `IFDOOR`

Same as the corresponding S_ values from C's <sys/stat.h> header file. These correspond to the different types of filesystem entry — that's regular file, directory, symbolic link, character device, block device, socket, fifo/pipe, and door, respectively, in that exact order. IFDOOR only applies to Solaris. 🚪

💖 `ISUID`, `ISGID`, `ISVTX`

Same as the corresponding S_ bit masks from C's <sys/stat.h> header file. These bit masks correspond to the setuid, setgid, and sticky bits in file permissions — i.e. --S------, -----S---, and --------T, respectively (aka 04000, 02000, and 01000). 💜

💖 `IRWXU`, `IRUSR`, `IWUSR`, `IXUSR`

Same as the corresponding S_ bit masks from C's <sys/stat.h> header file. These correspond to the user/owner file permissions — i.e. rwx------, r--------, -w-------, and --x------, respectively (aka 0700, 0400, 0200, and 0100). 🌸

💖 `IRWXG`, `IRGRP`, `IWGRP`, `IXGRP`

Same as the corresponding S_ bit masks from C's <sys/stat.h> header file. These correspond to the group file permissions — i.e. ---rwx---, ---r-----, ----w----, and -----x---, respectively (aka 0070, 0040, 0020, and 0010). 🍓

💖 `IRWXO`, `IROTH`, `IWOTH`, `IXOTH`

Same as the corresponding S_ bit masks from C's <sys/stat.h> header file. These correspond to the other/world file permissions — i.e. ------rwx, ------r--, -------w-, and --------x, respectively (aka 0007, 0004, 0002, and 0001). 🌈

💖 `texists`

True (non-zero) when the current candidate file is a symlink whose ultimate target exists — that's when rh(1) can actually obtain its stat(2) structure information. Important caveat: a false value (zero) might be because of permissions, not because the thing doesn't exist. Don't let it gaslight you 🙈

Use it with the ?: or || or && operator (see above) to conditionally use any of the following stat(2) structure fields relating to symlink targets. Unless the target exists, their values are all zero and meaningless.

Note: the -Y option is incompatible with this built-in. The only symlinks seen will be broken ones, and this built-in will return zero. 💀

Note: even without the -y or -Y option (so symlinks aren't followed for the purpose of searching), symlinks are followed for the purpose of obtaining the stat(2) structure information of the current candidate symlink's ultimate target — all so the following target-related built-in symbols can work. 🫶

💖 `tdev`

The device number of the device/filesystem that the current candidate symlink's ultimate target resides on. This is the st_dev field of the corresponding stat(2) structure. See the related tmajor and tminor built-ins (next) for extracting the major and minor device numbers out of tdev. 🔍

Only use this when the current candidate file is a symlink and its ultimate target exists (i.e., when texists is true). Otherwise, this is zero.

Note: the -Y option is incompatible with this built-in. The only symlinks seen will be broken ones, and this built-in will return zero.

💖 `tmajor`

The major device number of the device/filesystem that the current candidate symlink's ultimate target resides on. This is part of the st_dev field of the corresponding stat(2) structure.

Only use this when the current candidate file is a symlink and its ultimate target exists (i.e., when texists is true). Otherwise, this is zero.

Note: the -Y option is incompatible with this built-in. The only symlinks seen will be broken ones, and this built-in will return zero.

💖 `tminor`

The minor device number of the device/filesystem that the current candidate symlink's ultimate target resides on. This is part of the st_dev field of the corresponding stat(2) structure.

Only use this when the current candidate file is a symlink and its ultimate target exists (i.e., when texists is true). Otherwise, this is zero.

Note: the -Y option is incompatible with this built-in. The only symlinks seen will be broken ones, and this built-in will return zero.

💖 `tino`

The inode number of the current candidate symlink's ultimate target. This is the st_ino field of the corresponding stat(2) structure. 🎀

Only use this when the current candidate file is a symlink and its ultimate target exists (i.e., when texists is true). Otherwise, this is zero.

Note: the -Y option is incompatible with this built-in. The only symlinks seen will be broken ones, and this built-in will return zero.

💖 `tmode`

The mode of the current candidate symlink's ultimate target. This is the st_mode field of the corresponding stat(2) structure, and it holds the file type and the permissions. The standard library provides the ttype and tperm functions (among others) for extracting the file type and permissions from tmode. Combo meal energy 🍔

Only use this when the current candidate file is a symlink and its ultimate target exists (i.e., when texists is true). Otherwise, this is zero.

Note: the -Y option is incompatible with this built-in. The only symlinks seen will be broken ones, and this built-in will return zero.

💖 `tnlink`

The number of hard links to the current candidate symlink's ultimate target. This is the st_nlink field of the corresponding stat(2) structure. 🔗

This one's only meant for when the current candidate file is a symlink and its ultimate target actually exists (i.e. when texists is true). Any other situation? It's zero. 🫶

⚠️ Real talk: the -Y option does not play nice with this built-in. The only symlinks you'll ever see are broken ones, so this built-in just returns zero. Every time. 😭

💫 `tuid`

The user ID of whoever owns the current candidate symlink's ultimate target — literally the st_uid field of the corresponding stat(2) structure. 👑

Same rule as always: only use it when the current candidate file is a symlink and its ultimate target exists (i.e. texists is true). Otherwise it's zero.

⚠️ And the -Y option is incompatible with this built-in — you'll only see broken symlinks, and it'll return zero.

💫 `tgid`

The group ID of the group of the current candidate symlink's ultimate target. That's the st_gid field of the corresponding stat(2) structure. 🫂

Only use it when the current candidate file is a symlink and its ultimate target exists (i.e. texists is true). Otherwise: zero, zero, zero.

⚠️ -Y is incompatible with this built-in too — only broken symlinks show up, and it returns zero.

💫 `trdev`

The device number of the current candidate symlink's ultimate target, aka the st_rdev field of the corresponding stat(2) structure. This one only actually means something for character devices and block devices, so keep that in mind. 🔌 If you want the major and minor device numbers pulled out of trdev, that's what the related trmajor and trminor built-ins (right below) are for.

Still only valid when the current candidate file is a symlink and its ultimate target exists (i.e. texists is true). Otherwise, zero.

⚠️ -Y claps back: incompatible with this built-in, broken symlinks only, returns zero.

💫 `trmajor`

The major device number of the current candidate symlink's ultimate target — it's part of the st_rdev field of the corresponding stat(2) structure. Again: only meaningful for character devices and block devices. 🎛️

Only usable when the current candidate file is a symlink and its ultimate target exists (i.e. texists is true). Otherwise it's zero.

⚠️ The -Y option is incompatible with this built-in. Broken symlinks only, and zero comes back.

💫 `trminor`

The minor device number of the current candidate symlink's ultimate target. Also part of the st_rdev field of the corresponding stat(2) structure, and also only meaningful for character devices and block devices. 🎚️

Only for when the current candidate file is a symlink and its ultimate target exists (i.e. texists is true). Otherwise: zero.

⚠️ -Y is incompatible with this built-in. You'll only see broken symlinks and you'll get zero. No cap.

💫 `tsize`

The size, in bytes, of the current candidate symlink's ultimate target file — the st_size field of the corresponding stat(2) structure. But bestie, there are layers here: 🍰

For an ultimate target that's a readable directory, this is not the st_size field of the corresponding stat(2) structure. Instead it's the number of entries the directory contains (not counting . and ..).
For an ultimate target that's an unreadable directory (and literally everything else), it's the usual (undocumented) st_size field of the corresponding stat(2) structure.

Only use it when the current candidate file is a symlink and its ultimate target exists (i.e. texists is true). Otherwise it's zero.

⚠️ -Y is incompatible with this built-in. You'll only see broken symlinks, and it returns zero.

💫 `tblksize`

The preferred block size for efficient I/O on the current candidate symlink's ultimate target's filesystem — the st_blksize field of the corresponding stat(2) structure. 💾 On some filesystems (e.g. zfs) this is per-file rather than per-whole-filesystem, which is kind of iconic of them tbh.

📌 Heads up: this is unrelated to the tblocks built-in (next one down). Don't mix them up, iykyk.

Only used when the current candidate file is a symlink and its ultimate target exists (i.e. texists is true). Otherwise, zero.

⚠️ -Y is incompatible with this built-in — broken symlinks only, and you get zero.

💫 `tblocks`

How many 512-byte blocks the current candidate symlink's ultimate target occupies — the st_blocks field of the corresponding stat(2) structure. 🧱

Only when the current candidate file is a symlink and its ultimate target exists (i.e. texists is true). Otherwise it's zero.

⚠️ -Y is incompatible with this built-in. Only broken symlinks, only zero.

💫 `tatime`

When the current candidate symlink's ultimate target was last accessed — the st_atime field of the corresponding stat(2) structure. 👀

Only when the current candidate file is a symlink and its ultimate target exists (i.e. texists is true). Otherwise, zero.

⚠️ -Y is incompatible with this built-in. Broken symlinks only, and zero.

💫 `tmtime`

When the current candidate symlink's ultimate target's contents were last modified — the st_mtime field of the corresponding stat(2) structure. ✏️

Only when the current candidate file is a symlink and its ultimate target exists (i.e. texists is true). Otherwise, zero.

⚠️ -Y is incompatible with this built-in. Broken symlinks only, zero only.

💫 `tctime`

When the current candidate symlink's ultimate target's inode was last changed — the st_ctime field of the corresponding stat(2) structure. 🕰️

Only when the current candidate file is a symlink and its ultimate target exists (i.e. texists is true). Otherwise, zero.

⚠️ -Y is incompatible with this built-in. Broken symlinks only, and zero.

💫 `tstrlen`

The length in bytes of the base name of the current candidate symlink's immediate target path. 🎀 Lowkey important detail: this is zero if the target path is the root directory (/), because root has no base name.

This one's only used when the current candidate file is a symlink — otherwise it's zero. But here's the slay part: the ultimate target does not need to exist. ✨

⚠️ And unlike its friends above, the -Y option affects this built-in: the only symlinks you'll see are broken ones, but this built-in still returns the correct length. Main character behaviour fr fr.

🌈 Pattern matching 🌈

By default, string literals ("pattern") hold shell-style file glob patterns that get matched against each candidate file's base name. Want variations? Scroll down to the Pattern modifiers section, bestie. 👇

Pattern strings evaluate to true (i.e. non-zero) if the pattern match succeeds, or false (i.e. zero) otherwise.

The following POSIX glob pattern notation is supported on all platforms:

? — Matches any single character. A leading dot character (.) is not treated as a special character, so for example ?profile would match .profile. This is unlike /bin/sh behaviour, but it's like POSIX find(1) behaviour. 🤯
* — Matches any string of characters, including the empty string. A leading dot character (.) is not treated as a special character here either — for example * would match .profile. Again: unlike /bin/sh, like POSIX find(1).
[abc] — Matches any single character in the given set. Ranges work too (e.g. [a-z0-9]). 🔤
[!abc] — Matches any single character not in the given set. Ranges work here too (e.g. [!A-Z]).

🌸 And although it's non-standard (i.e., officially undefined), on most systems you can use the more familiar ^ instead of ! to complement the set in character classes (e.g. [^abc]) — but not on Solaris. 💀

Locale-specific character class notation should also be available on all platforms (i.e. named character classes like [[:lower:]], collating symbols like [[.a-acute.]], and equivalence class expressions like [[=a=]]), but not all locales support all of them. 🗺️

The special meanings of ?, * and [ can be removed by quoting them with a preceding backslash character (\).

The following Ksh extended glob pattern notation is supported on platforms with GNU glibc (i.e. Linux):

?(a|b|c) — Matches if zero or one occurrences of any of the sub-patterns match the text.
*(a|b|c) — Matches if zero or more occurrences of any of the sub-patterns match the text.
+(a|b|c) — Matches if one or more occurrences of any of the sub-patterns match the text.
@(a|b|c) — Matches if exactly one occurrence of any of the sub-patterns matches the text.
!(a|b|c) — Matches if the text cannot be matched by any of the sub-patterns. 🙅‍♀️

The special meanings of ?, *, +, @, !, (, | and ) can be removed by quoting them with a preceding backslash character (\).

The output of rh --help states if Ksh extended glob pattern notation is available on the local system. 🖥️

See fnmatch(3) and glob(7) for more details.

🎀 Pattern modifiers 🎀

Pattern modifiers ("pattern".modifier) are suffixes you tack onto string literals — they change how the string is interpreted and what actually gets done with it. 💅 There must be no spaces around the dot between the string literal and the modifier name.

You can give modifier names in full (e.g. "pattern".path), but a unique prefix is enough (e.g. "pattern".pat, "pattern".pa, or "pattern".p). For every modifier below, both the full name and the shortest unique prefix are shown. 🌟

The following modifiers exist, but not all are available on all systems.

`path` (or `p`)

Apply the glob pattern to each candidate file's full path starting from the search directory, not just its base name. Slash characters ("/") are not treated as special characters. For example, "./sr*sc".path would match ./src/misc.

Note: since a slash character can never appear in a file's base name, if a glob pattern string with no pattern modifier does contain a slash character (e.g., "/"), then instead of attempting (and failing 💀) to match it against the file's base name, an implicit path pattern modifier is assumed (e.g., "/".path), and it gets matched against the file's full path starting from the search directory instead. iykyk.

`link` (or `l`)

Apply the glob pattern to each candidate symlink's target path, rather than its base name. Slash characters ("/") are not treated as special characters. For example, "./sr*sc".path would match ./src/misc.

`body` (or `b`)

Apply the glob pattern to each candidate file's contents, rather than its base name. Slash characters ("/") are not treated as special characters.

Note that this is an expensive pattern modifier, because each candidate file is read in its entirety to determine whether or not the pattern matches 😭. It can be worthwhile preceding this with other predicates to reduce the number and limit the size of candidate files that this is applied to. fr fr, be smart about it.

This probably shouldn't be used with very large files. It would require a lot of memory or swap, and on 32-bit systems, the possible file size is also limited by the available address space. If this is an issue, you can always use grep(1) (or similar) via the sh "pattern" modifier instead.

Also note that this only works with regular files that are readable to the current user.

Also note that the body and ibody glob pattern modifiers shouldn't be used with binary files that might contain null bytes 💀. For binary files, use the rebody or reibody regular expression pattern modifiers instead (see below).

Note: if the current candidate file is a symlink, its body is unaffected by the -y or -Y options. For the purpose of this predicate, the symlink is always followed.

`what` (or `w`)

Apply the glob pattern to each candidate file's file type description (as would be output by the file(1) utility), rather than its base name. Slash characters ("/") are not treated as special characters. This is available on systems with libmagic(3) installed. slay.

Note that this is an expensive pattern modifier because each candidate file is at least partially read to determine its file type. It can be worthwhile preceding this with other predicates to reduce the number of candidate files that this is applied to.

Also note that this only works with files that are readable to the current user.

Also note that any errors encountered result in an error message taking the place of the file type description being matched 👀. To see these error messages, you can use the -L option with its %w format conversion.

Note: if the current candidate file is a symlink, its file type description is affected by the -y or -Y options.

`mime` (or `m`)

Apply the glob pattern to each candidate file's MIME type (including the character set), rather than its base name. Slash characters ("/") are not treated as special characters. This is available on systems with libmagic(3) installed.

Note that this is an expensive pattern modifier because each candidate file is at least partially read to determine its MIME type. It can be worthwhile preceding this with other predicates to reduce the number of candidate files that this is applied to.

Also note that this only works with files that are readable to the current user.

Also note that any errors encountered result in an error message taking the place of the MIME type being matched. To see these error messages, you can use the -L option with its %W format conversion.

Note: if the current candidate file is a symlink, its MIME type is affected by the -y or -Y options.

`i`

Apply the glob pattern without case-sensitivity ✨. This is available on most systems, but maybe not all.

The output of rh --help states if case-insensitive glob matching is available on the local system.

`ipath` (or `ip`)

Like the path modifier, but apply the glob pattern without case-sensitivity. This is available on most systems, but maybe not all.

Note: since a slash character can never appear in a file's base name, if a glob pattern string with the i pattern modifier does contain a slash character (e.g., "/".i), then instead of attempting (and failing) to match it against the file's base name, an implicit ipath pattern modifier is assumed (e.g., "/".ipath), and it will be matched against the file's full path starting from the search directory instead.

`ilink` (or `il`)

Like the link modifier, but apply the glob pattern without case-sensitivity. This is available on most systems, but maybe not all.

`ibody` (or `ib`)

Like the body modifier, but apply the glob pattern without case-sensitivity.

`iwhat` (or `iw`)

Like the what modifier, but apply the glob pattern without case-sensitivity. This is available on most systems with libmagic(3) installed, but maybe not all.

`imime` (or `im`)

Like the mime modifier, but apply the glob pattern without case-sensitivity. This is available on most systems with libmagic(3) installed, but maybe not all.

`re`

Match each candidate file's base name against a Perl-compatible regular expression (regex) instead of a glob pattern 🔥. See perlre(1), pcre2pattern(3), and pcre2syntax(3) for details. This is available on systems that have libpcre2-8 installed.

The output of rh --help states whether or not Perl-compatible regular expressions are available on the local system.

Regex patterns are not automatically anchored to the start and end, and so do not have to match the entire text. no cap.

The following PCRE2 options are always enabled:

PCRE2_DOTALL — the . meta-character matches any character, including the newline character. This prevents surprises when files have newline characters in their names. This is like Perl's /s modifier.
PCRE2_MULTILINE — the ^ meta-character matches after every internal newline character, not just at the start. The $ meta-character matches before every internal newline character, not just at the end. This is useful for access control list (ACL) and extended attribute (EA) searches (see below) where the text can occupy multiple lines. This is like Perl's /m modifier.
PCRE2_EXTENDED — ignore (outside character classes) most whitespace characters and everything from a hash character ("#") until the end of the line. Matching a whitespace or hash character requires quoting it with a preceding backslash character ("\"). Complex regex patterns can be made more readable this way, and it enables comments in regex patterns 💅. This is like Perl's /x modifier.
PCRE2_EXTENDED_MORE — ignore space and tab characters inside character classes. Matching a space or tab in a character class requires quoting it with a preceding backslash character ("\"). Complex character classes can be made more readable this way. This is like Perl's /xx modifier.
PCRE2_NO_AUTO_CAPTURE — prevent parentheses from automatically capturing matching text (i.e., always treat (...) as (?:...)). There are no uses for captures in rh(1), and this should make matching ever so slightly smaller and faster, without the explicit ?:. This is like Perl's /n modifier.

Note that the regex pattern and the text being matched are generally assumed to be encoded as UTF-8. If you need to suppress this assumption, set the environment variable RAWHIDE_PCRE2_NOT_UTF8_DEFAULT=1. When this environment variable is set, individual regex patterns can still enable UTF-8 interpretation with a leading (*UTF). This UTF-8 assumption is made when the locale uses UTF-8 (i.e., when the $LANG environment variable includes "UTF-8"). When the locale doesn't use UTF-8, and you want rh to assume that everything is UTF-8 anyway, set the environment variable RAWHIDE_PCRE2_UTF8_DEFAULT=1.

`repath` (or `rep`)

Like the re modifier, but apply the regex to each candidate file's full path starting from the search directory, not just its base name.

Note: since a slash character can never appear in a file's base name, if a regex pattern string with the re pattern modifier does contain a slash character (e.g., "/".re), then instead of attempting (and failing) to match it against the file's base name, an implicit repath pattern modifier is assumed (e.g., "/".repath), and it will be matched against the file's full path starting from the search directory instead.

`relink` (or `rel`)

Like the re modifier, but apply the regex to each candidate symlink's target path, rather than its base name.

`rebody` (or `reb`)

Like the re modifier, but apply the regex to each candidate file's contents, rather than its base name. See body above for more details 👆.

`rewhat` (or `rew`)

Like the re modifier, but apply the regex to each candidate file's file type description, rather than its base name. This is available on systems that have libpcre2-8 and libmagic installed. See what above for more details.

`remime` (or `rem`)

Like the re modifier, but apply the regex to each candidate file's MIME type, rather than its base name. This is available on systems that have libpcre2-8 and libmagic installed. See mime above for more details.

`rei`

Like the re modifier, but apply the regex without case-sensitivity ✨.

`reipath` (or `reip`)

Like the repath modifier, but apply the regex without case-sensitivity.

Note: since a slash character can never appear in a file's base name, if a regex pattern string with the rei pattern modifier does contain a slash character (e.g., "/".rei), then instead of attempting (and failing) to match it against the file's base name, an implicit reipath pattern modifier is assumed (e.g., "/".reipath), and it will be matched against the file's full path starting from the search directory instead.

reilink (or reil) — literally the relink modifier, but the regex gets applied without case-sensitivity. lowercase bestie hours 💅
reibody (or reib) — same deal as rebody, except the regex is applied without case-sensitivity. 🫶
reiwhat (or reiw) — the rewhat modifier's chill twin: same regex, no case-sensitivity. ✨
reimime (or reim) — and remime, but the regex is applied without case-sensitivity. that's the whole sentence, slay. 🎀
acl (or a) — applies your glob pattern to each candidate file's access control list (ACL) instead of its base name. no cap, it's searching the ACL text itself. 👑

This one's available on systems with "POSIX" ACLs (e.g., Linux, FreeBSD, Solaris (for ufs), and Cygwin), and NFSv4 ACLs (e.g., FreeBSD and Solaris (for zfs)), and macOS with its own Extended ACLs. OpenBSD and NetBSD don't do ACLs at all — not their era. See acl(2) or acl(3) or acl(5) for more details.

The output of rh --help states if access control lists are available on the local system.

"POSIX" ACL text is multiple lines, each one terminated by a newline character. it's giving:

user::rwx
user:name:rwx
group::rwx
group:name:rwx
mask::rwx
other::rwx

NFSv4 ACL text, though, comes in two forms, because of course it does. In the compact form, the items look like these:

    owner@:rwxp--aARWcCos:-------:allow
 user:name:rwxp--aARWcCos:-------:allow
    group@:r-x---a-R-c--s:-------:allow
group:name:r-x---a-R-c--s:-------:allow
 everyone@:r-x---a-R-c--s:-------:allow

In the non-compact form, the items each look something like this:

owner@:read_data/write_data/append_data/read_xattr/write_xattr
  /execute/read_attributes/write_attributes/read_acl/write_acl
  /write_owner/synchronize:allow

Searches can be made for either form. But ⚠️ be warned that the permission names in the non-compact form do not always appear in the same order (at least on Solaris). so don't come crying to me when your glob misses. 😭

On FreeBSD, NFSv4 ACL text has each item on a separate line, terminated by a newline character, and there are leading spaces for vertical alignment before each item. On Solaris, NFSv4 ACL text is a comma-separated list of items with no leading spaces and no newline character. different fonts of the same energy fr fr.

macOS has its own Extended ACLs that look like this:

!#acl 1
user:906E2CAD-E971-12D8-ACB9-000A95DF094B:drew:502:allow:write

An easy way to see what ACLs look like on your system is:

$ rh -L '%p\n%z\n'

But bear in mind that this reformats multiple lines into a comma-separated list. That can be avoided if the locale uses UTF-8 and jq(1) is installed:

$ rh -L %j | jq -r .access_control_list

Note that glob patterns are anchored to the start and end, and so must match the entire text. the whole thing, not just a vibe. 🧚

On Solaris, ACLs are always present by default, even if they are trivially identical to the file permission bits. This can be convenient, but if it seems like noise, it can be silenced (but only on Solaris) by setting the environment variable RAWHIDE_SOLARIS_ACL_NO_TRIVIAL=1.

iacl (or ia) — like the acl modifier, but the glob pattern is applied without case-sensitivity. This might not be available on all systems. 🙈
reacl (or rea) — like the acl modifier, but instead of a glob pattern, it matches each candidate file's access control list (ACL) against a Perl-compatible regular expression (regex). This is available on systems that have libpcre2-8 installed, and supported access control lists. See the re modifier above for more information. ✨
reiacl (or reia) — like the reacl modifier, but the regex is applied without case-sensitivity. 💜
ea (or e) — applies the glob pattern to each candidate file's extended attributes (EA), rather than its base name. 🦋

This is available on Linux, FreeBSD, macOS, Solaris, and Cygwin. OpenBSD and NetBSD don't do EAs. See xattr(1) or xattr(7) or extattr(2) or fsattr(7) for more details.

The output of rh --help states if extended attributes are available on the local system.

The extended attributes text, if any, will be possibly multiple lines, one per extended attribute, each terminated by a newline character. Each extended attribute starts with its name. If it also has a value, then the name is followed by colon and space characters (": "), and then the value. Note that on macOS, some extended attribute names contain a colon character, but they aren't typically followed by a space character. iykyk. 🍓

Note that any control characters (i.e., ASCII 0-31, 127) in extended attribute names or values, and any non-ASCII bytes (i.e., 128-255) in the values, will be presented as C-like backslash escape sequences such as "\n" for the newline character, and "\0" for the null character, or as hexadecimal escape sequences such as "\x1b" for the escape character. Any backslash characters are quoted with a preceding backslash. Note that commas are not quoted. okay? okay. 💀

This encoding is the text that patterns must be written to match against. But you can still match against any text in extended attribute names, and ASCII-only text in their values, as you normally would. whew. 😭

Note that glob patterns are anchored to the start and end, and so must match the entire text. no partial credit, bestie. ⭐

On FreeBSD, extended attributes in the user namespace are presented with "user." as a prefix to their actual name, and those in the system namespace are presented with "system." as a name prefix. On FreeBSD, only the root user may see extended attributes in the system namespace. main character privileges only. 👑

On most systems with extended attributes, the values are typically only up to a few hundred bytes in size. But on Solaris, extended attributes take the form of regular files in a special extended attributes directory "hidden" inside each real file. Entire files can be copied into that special directory, and they become extended attributes. So extended attributes could tend to be larger on Solaris. it's built different. 🔥

The default maximum total size for (encoded) extended attributes is 4KiB on most systems, and 64KiB on Solaris. If this is not enough, extended attributes will be silently truncated. ⚠️ This affects extended attribute searching (ea), and the -L %x format conversion. To prevent truncation, set the environment variable RAWHIDE_EA_SIZE to a positive integer value that is large enough for your needs. Note that the value must be the size in bytes. Scale units are not supported. just the number, babes. 🎀

On Solaris, every file's extended attributes directory contains the SUNWattr_ro and SUNWattr_rw extended attributes. By default, they are included for every file that has any other extended attributes. They can be excluded by setting the environment variable RAWHIDE_SOLARIS_EA_NO_SUNWATTR=1.

Also on Solaris, since extended attributes are files (of a sort), they each have their own stat(2) information. By default, this information is represented as an artificial extended attribute whose name is the name of the corresponding real extended attribute followed by "/stat". These artificial extended attributes have the following format:

name/stat: -rw-r--r-- nlink user group size mtime atime ctime

The name is the name of the corresponding real extended attribute. The "/stat:" is literal. The nlink is always 1. The user and group are names or numeric IDs. The size is in bytes. The mtime, atime, and ctime are in ISO date/time format ("YYYY-MM-DD HH:MM:SS +HHMM"). 🌸

This makes it possible on Solaris to search for files by the stat(2) information of their extended attributes. But it can only be a text-based search (glob or regex). text-based only, ngl. 🙈

These artificial extended attributes can be suppressed by setting the environment variable RAWHIDE_SOLARIS_EA_NO_STATINFO=1.

iea (or ie) — like the ea modifier, but the glob pattern is applied without case-sensitivity. This might not be available on all systems. 💅
reea (or ree) — like the ea modifier, but matches each candidate file's extended attributes (EA) against a Perl-compatible regular expression (regex) instead of a glob pattern. This is available on systems that have libpcre2-8 installed, and supported extended attributes. See the re modifier above for more information. 🦋
reiea (or reie) — like the reea modifier, but the regex is applied without case-sensitivity. ✨
sh (or s) — okay so this one does NOT treat the string literal as a pattern at all. it treats it as an external shell command to execute via system(3) (i.e., via /bin/sh). It evaluates to the exit success status of the external shell command. If its exit status is zero, then the value is true (i.e., non-zero). Otherwise, it is false (i.e., zero). iconic logic, honestly. 💅

This enables arbitrary command line utilities to contribute to the search criteria. But ⚠️ be warned, this can be slow, because it involves the creation of possibly many other processes. But it makes many things possible. To reduce the number of external shell commands that need to be executed, the sh "pattern" modifier can be used conditionally with the ?: or || or && operator (see above). work smarter, not harder. 🧚

The string can contain %s which will be replaced with the matching entry's full path starting from the search directory. It can also contain %S which will be replaced with the matching entry's base name (or with "/" when the matching entry is the root directory (/) which has no base name). For example, given the matching file /etc/passwd, %s and %S would be replaced with "/etc/passwd" and "passwd", respectively. To include a literal per cent sign ("%") in the shell command, use %%. It is an error if % is not followed by s, S, or %. 🔥

Any shell meta-characters in the interpolated path or base name are quoted with preceding backslash characters ("\") to prevent shell command injection, so there is no need to place any quote characters around %s or %S. she's safe, she's careful, she ate. 👑

Every shell command is executed after safely changing the current working directory to the directory containing each candidate file. This minimizes the number of path-based race conditions. So the %S interpolation is more likely to be useful than the %s interpolation. 🫶

And if the user's $PATH environment variable includes the current working directory, or any other non-absolute paths, that could be dangerous, so they are automatically removed first. 💀 no cap, that's a real safety thing, don't @ me.

⚠️ Heads up bestie: since the shell commands run from the directory that holds each matching entry, if they actually need the matching entry's full path counted from the search directory (i.e. %s), then it's so much better if your starting search paths are all absolute paths, so %s is always an absolute path. Otherwise the shell command might have to change its current working directory back to the initial working directory. Also, %s suffers from a whole bunch of path-based race conditions, which is insecure on hosts with malicious local actors who have write access to the directory tree being searched — so like, don't generally use it, fr fr.

🎀 Reference file fields 🎀

Reference file fields ("/path".field) are suffixes you tack onto string literals, and they represent the inode metadata of arbitrary reference files — all for the purpose of comparison. Important: there must be no spaces around the dot between the path string and the field name. None. Zero. Nada. 💅

If the path is the empty string (e.g., "".field), then it refers to the most recent reference file path the parser encountered. This makes multiple references to the same reference file way more concise (e.g., "/path".exists && mtime > "".mtime). Iconic, honestly.

Here's the full lineup of reference file fields available 👇

exists — This is true (i.e., non-zero) when the reference file exists (i.e., when rh(1) can obtain its stat(2) structure information). Watch out though: a false value (i.e., zero) might be caused by permissions, not by the file not existing. 🙈

If there's any chance the reference file does not exist, then exists must be used to determine whether the rest of the reference file fields can even be used. If a reference file doesn't exist and any of its stat(2) structure fields below get used in a file test expression, an error message will be output and rh(1) will terminate with a non-zero exit status. So exists is meant to be used with the ?: or || or && operator (see above) to conditionally use any of the following stat(2) structure fields (e.g., "/path".exists && size > "".size). 🫶

dev — The device number of the device/filesystem that the reference file resides on. This is the st_dev field of the corresponding stat(2) structure. Peep the related major and minor reference file fields (next) for extracting the major and minor device numbers from dev.