FILE(1POSIX)

📦 version 2017a, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

🌸 FILE(1POSIX) 🌸

okay bestie, welcome to the POSIX Programmer's Manual — this is the file page, and she is LONG, so buckle up 💖 (also: we're doing this in parts, so don't go anywhere 👀)

✨ PROLOG ✨

so like, this manual page is part of the POSIX Programmer's Manual. the Linux implementation of this interface may differ — so if you're on Linux, go check the corresponding Linux manual page for the deets on Linux behavior 🐧 — or honestly the interface might just not be implemented on Linux at all. yeah. it's giving "read the fine print" 💅

🎀 NAME 🎀

file — determine file type 🔍✨

🦋 SYNOPSIS 🦋

file [-dh] [-M file] [-m file] file...

file -i [-h] file...

💜 DESCRIPTION 💜

so the file utility is gonna run a whole series of tests in sequence on each file you hand it, trying to figure out what tf it is. like a vibe check but for files. here's the order, no skipping 🔥

  1. if file does not exist, cannot be read, or its file status could not be determined, the output shall indicate that the file was processed, but that its type could not be determined. (translation: "i looked, bestie, i just don't know her" 😭)
  2. if the file is not a regular file, its file type shall be identified. the file types directory, FIFO, socket, block special, and character special shall be identified as such. other implementation-defined file types may also be identified. if file is a symbolic link, by default the link shall be resolved and file shall test the type of file referenced by the symbolic link. (see the -h and -i options below 👇)
  3. if the length of file is zero, it shall be identified as an empty file. nothing going on in there. empty. void. she's got nothing to say 🫥
  4. the file utility shall examine an initial segment of file and shall make a guess at identifying its contents based on position-sensitive tests. (the answer is not guaranteed to be correct — see the -d, -M, and -m options below ⚠️)
  5. the file utility shall examine file and shall make a guess at identifying its contents based on context-sensitive default system tests. (again, the answer is not guaranteed to be correct 🙈)
  6. the file shall be identified as a data file. the catch-all. the "she's just data, idk" ending 🍓

if file does not exist, cannot be read, or its file status could not be determined, the output shall indicate that the file was processed, but that its type could not be determined. (yes this is repeated. the manpage said it twice and so do i. periodt.)

if file is a symbolic link, by default the link shall be resolved and file shall test the type of file referenced by the symbolic link. 🔗

💅 OPTIONS 💅

the file utility shall conform to the Base Definitions volume of POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines — EXCEPT that the order of the -m, -d, and -M options shall be significant. yes, order matters here. no cap. that's the whole plot twist 📢

the following options shall be supported by the implementation:

  • -d — apply any position-sensitive default system tests and context-sensitive default system tests to the file. this is the default if no -M or -m option is specified. she's the baseline, the standard, the no-notes choice ✨
  • -h — when a symbolic link is encountered, identify the file as a symbolic link. and listen: if -h is not specified and file is a symbolic link that refers to a nonexistent file, file shall identify the file as a symbolic link, as if -h had been specified. so the broken-link case behaves like -h anyway, iykyk 💀
  • -i — if a file is a regular file, do not attempt to classify the type of the file further, but identify the file as specified in the STDOUT section. she's stopping early. no further questions 🛑
  • -M file — specify the name of a file containing position-sensitive tests that shall be applied to a file in order to classify it (see the EXTENDED DESCRIPTION). no position-sensitive default system tests nor context-sensitive default system tests shall be applied unless the -d option is also specified. big "custom rules only" energy 🧚
  • -m file — specify the name of a file containing position-sensitive tests that shall be applied to a file in order to classify it (see the EXTENDED DESCRIPTION).

okay so here's the combo logic, and it's giving ✨choreography✨:

  • if the -m option is specified without specifying the -d option or the -M option, position-sensitive default system tests shall be applied after the position-sensitive tests specified by the -m option.
  • if the -M option is specified with the -d option, the -m option, or both, or the -m option is specified with the -d option, the concatenation of the position-sensitive tests specified by these options shall be applied in the order specified by the appearance of these options. (told you the order was significant 👑)
  • if a -M or -m file option-argument is -, the results are unspecified. 🚨 don't do it, bestie, nobody knows what happens.

🌈 OPERANDS 🌈

the following operand shall be supported:

  • file — a pathname of a file to be tested. that's her. the one we're investigating 🔎

⭐ STDIN ⭐

the standard input shall be used if a file operand is '-' and the implementation treats the '-' as meaning standard input. otherwise, the standard input shall not be used. simple as that 🎯

🧚 INPUT FILES 🧚

the file can be any file type. no discrimination here, we test everybody 💖

🌸 ENVIRONMENT VARIABLES 🌸

the following environment variables shall affect the execution of file:

  • LANG — provide a default value for the internationalization variables that are unset or null. (see the Base Definitions volume of POSIX.1‐2017, Section 8.2, Internationalization Variables for the precedence of internationalization variables used to determine the values of locale categories.)
  • LC_ALL — if set to a non-empty string value, override the values of all the other internationalization variables. she overrides everything. main character behavior 👑
  • LC_CTYPE — determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as opposed to multi-byte characters in arguments and input files).
  • LC_MESSAGES — determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output.
  • NLSPATH — determine the location of message catalogs for the processing of LC_MESSAGES.

💀 ASYNCHRONOUS EVENTS 💀

Default. that's it. that's the whole section. we love a low-effort icon 🫶

✨ STDOUT ✨

in the POSIX locale, the following format shall be used to identify each operand, file specified:

"%s: %s\n", <file>, <type>

the values for <type> are unspecified, except that in the POSIX locale, if file is identified as one of the types listed in the following table, <type> shall contain (but is not limited to) the corresponding string, unless the file is identified by a position-sensitive test specified by a -M or -m option. also, each <space> shown in the strings shall be exactly one <space>. one. singular. don't get cute with it 🚨

💖 Table 4-9: File Utility Output Strings 💖

so here's the tea, translated out of table format into something you can actually read:

  • if file is Nonexistent → <type> shall contain the string: cannot open
  • if file is Block special → <type> shall contain the string: block special — Notes: 1
  • if file is Character special → <type> shall contain the string: character special — Notes: 1
  • if file is Directory → <type> shall contain the string: directory — Notes: 1
  • if file is FIFO → <type> shall contain the string: fifo — Notes: 1
  • if file is Socket → <type> shall contain the string: socket — Notes: 1
  • if file is Symbolic link → <type> shall contain the string: symbolic link to — Notes: 1
  • if file is Regular file → <type> shall contain the string: regular file — Notes: 1,2
  • if file is Empty regular file → <type> shall contain the string: empty — Notes: 3
  • if file is Regular file that cannot be read → <type> shall contain the string: cannot open — Notes: 3
  • if file is Executable binary → <type> shall contain the string: executable — Notes: 3,4,6
  • if file is ar archive library (see ar) → <type> shall contain the string: archive — Notes: 3,4,6
  • if file is Extended cpio format (see pax) → <type> shall contain the string: cpio archive — Notes: 3,4,6
  • if file is Extended tar format (see ustar in pax) → <type> shall contain the string: tar archive — Notes: 3,4,6
  • if file is Shell script → <type> shall contain the string: commands text — Notes: 3,5,6
  • if file is C-language source → <type> shall contain the string: c program text — Notes: 3,5,6
  • if file is FORTRAN source → <type> shall contain the string: fortran program text — Notes: 3,5,6
  • if file is Regular file whose type cannot be determined → <type> shall contain the string: data — Notes: 3

🦋 Notes 🦋

  1. this is a file type test.
  2. this test is applied only if the -i option is specified.
  3. this test is applied only if the -i option is not specified.
  4. this is a position-sensitive default system test.
  5. this is a context-sensitive default system test.
  6. position-sensitive default system tests and context-sensitive default system tests are not applied if the -M option is specified unless the -d option is also specified.

in the POSIX locale, if file is identified as a symbolic link (see the -h option), the following alternative output format shall be used:

"%s: %s %s\n", <file>, <type>, <contents of link>"
⚠️ and this next bit is important, bestie: if the file named by the file operand does not exist, cannot be read, or the type of the file named by the file operand cannot be determined, this shall not be considered an error that affects the exit status. so she'll be like "couldn't open her 🤷" and still walk away with a clean exit status. no drama, no error code 💅

🎀 STDERR 🎀

the standard error shall be used only for diagnostic messages. that's her only job. don't ask her for more 🫶

🍓 OUTPUT FILES 🍓

None. nothing gets written. she only reads and tells you what she thinks. iconic 🌟

🦋 EXTENDED DESCRIPTION 🦋

okay so bestie, if you hand a file to -m or -M, that file has to contain one position-sensitive test per line, and each one gets applied to the file you're checking. If a test succeeds, the message field of that line gets printed and then we're done — no further tests get applied. The one exception? Tests on the lines immediately following, as long as those lines start with a single > character. Those still get applied. iykyk.

Each line is made of these four <tab>-separated fields. (Real talk: implementations may allow any combination of one or more whitespace characters other than <newline> to act as field separators. generous of them fr fr.)

  • offset — an unsigned number (optionally preceded by a single > character) that says the offset, in bytes, of the value in the file that's getting compared against the value field of the line. If the file is shorter than the specified offset, the test fails. 💀

If the offset starts with the character >, the test on that line shall not be applied to the file unless the test on the last line whose offset did not begin with a > was successful. By default the offset is read as an unsigned decimal number. With a leading 0x or 0X, it's read as a hexadecimal number; otherwise, if it leads with 0, it's read as an octal number.

  • type — the type of the value in the file being tested. The type consists of the type specification characters d, s, and u, meaning signed decimal, string, and unsigned decimal respectively. slay.

The type string gets interpreted as the bytes from the file starting at the specified offset, including the same number of bytes specified by the value field. If not enough bytes remain in the file past the offset to match the value field, the test fails.

The type specification characters d and u can be followed by an optional unsigned decimal integer that says how many bytes the type represents. They can also be followed by an optional C, S, I, or L, meaning the value is of type char, short, int, or long, respectively.

The default number of bytes represented by the type specifiers d, f, and u corresponds to their respective C-language types, like this: if the system claims conformance to the C-Language Development Utilities option, those specifiers correspond to the default sizes used in the c99 utility. Otherwise, the default sizes are implementation-defined (mysterious, we love that for them).

For the type specifier characters d and u, the default number of bytes corresponds to the size of a basic integer type of the implementation. For these specifier characters, the implementation shall support values of the optional number of bytes to be converted corresponding to the number of bytes in the C-language types char, short, int, or long. These numbers can also be specified by an application as the characters C, S, I, and L, respectively. The byte order used when interpreting numeric values is implementation-defined, but it shall correspond to the order in which a constant of the corresponding type is stored in memory on the system.

Every type specifier except s can be followed by a mask specifier of the form &number. The mask value gets AND'ed with the value of the input file before the comparison with the value field of the line is made. By default the mask is read as an unsigned decimal number. With a leading 0x or 0X, the mask is read as an unsigned hexadecimal number; otherwise, with a leading 0, the mask is read as an unsigned octal number.

The strings byte, short, long, and string are also supported as type fields, and they're interpreted as dC, dS, dL, and s, respectively. 🫶

  • value — the value to be compared with the value from the file.

If the specifier from the type field is s or string, interpret the value as a string. Otherwise, interpret it as a number. If the value is a string, the test succeeds only when a string value exactly matches the bytes from the file. no wiggle room bestie.

If the value is a string, it can contain the following sequences:

  • \character — the <backslash>-escape sequences as specified in the Base Definitions volume of POSIX.1‐2017, Table 5-1, Escape Sequences and Associated Actions ('\\', '\a', '\b', '\f', '\n', '\r', '\t', '\v'). On top of that, the escape sequence '\ ' (the <backslash> character followed by a <space> character) shall be recognized to represent a <space> character. The results of using any other character, other than an octal digit, following the <backslash> are unspecified. ⚠️
  • \octal — octal sequences, used to represent characters with specific coded values. An octal sequence is a <backslash> followed by the longest sequence of one, two, or three octal-digit characters (01234567).

By default, any value that isn't a string gets interpreted as a signed decimal number. Any such value with a leading 0x or 0X gets interpreted as an unsigned hexadecimal number; otherwise, with a leading zero, the value gets interpreted as an unsigned octal number.

If the value isn't a string, it can be preceded by a character that says which comparison to perform. The permissible characters and the comparisons they specify are:

  • = — the test succeeds if the value from the file equals the value field.
  • < — the test succeeds if the value from the file is less than the value field.
  • > — the test succeeds if the value from the file is greater than the value field.
  • & — the test succeeds if all of the set bits in the value field are set in the value from the file.
  • ^ — the test succeeds if at least one of the set bits in the value field is not set in the value from the file.
  • x — the test succeeds if the file is large enough to contain a value of the type specified starting at the offset specified.
  • message — the message to be printed if the test succeeds. The message gets interpreted using the notation for the printf formatting specification; see printf. If the value field was a string, then the value from the file shall be the argument for the printf formatting specification; otherwise, the value from the file shall be the argument.

✨ EXIT STATUS ✨

these are the exit values you might get back, bestie:

  • 0 — successful completion. 🎉
  • >0 — an error occurred. 😭

🫠 CONSEQUENCES OF ERRORS 🫠

Default.

The following sections are informative.

🌸 APPLICATION USAGE 🌸

The file utility can only be required to guess at many of the file types, because only exhaustive testing can determine some types with certainty. Like, for example, binary data on some implementations might match the initial segment of an executable or a tar archive. it's giving "close enough" 😭

Also note that the table indicates that the output contains the stated string. Systems may add text before or after the string. For executables, as an example, the machine architecture and various facts about how the file was link-edited may be included. Note also that on systems that recognize shell script files starting with "#!" as executable files, these may be identified as executable binary files rather than as shell scripts. 🙈

👑 EXAMPLES 👑

Determine whether an argument is a binary executable file:

file -- "$1" | grep -q ':.*executable' &&
    printf "%s is executable.\n$1"

⭐ go off, honestly.

💖 RATIONALE 💖

Okay so first thing's first: the -f option was omitted because the same effect can (and should) be obtained using the xargs utility. Periodt. 💅

Historical versions of the file utility attempt to identify the following types of files: symbolic link, directory, character special, block special, socket, tar archive, cpio archive, SCCS archive, archive library, empty, compress output, pack output, binary data, C source, FORTRAN source, assembler source, nroff/troff/eqn/tbl source troff output, shell script, C shell script, English text, ASCII text, various executables, APL workspace, compiled terminfo entries, and CURSES screen images. Only those types that are reasonably well specified in POSIX or are directly related to POSIX utilities are listed in the table.

Historical systems have used a “magic file” named /etc/magic to help identify file types. Because it is generally useful for users and scripts to be able to identify special file types, the -m flag and a portable format for user-created magic files has been specified. No requirement is made that an implementation of file use this method of identifying files, only that users be permitted to add their own classifying tests.

In addition, three options have been added to historical practice. The -d flag has been added to permit users to cause their tests to follow any default system tests. The -i flag has been added to permit users to test portably for regular files in shell scripts. The -M flag has been added to permit users to ignore any default system tests. Lowkey iconic. ✨

The POSIX.1-2008 description of default system tests and the interaction between the -d, -M, and -m options did not clearly indicate that there were two types of “default system tests”. The “position-sensitive tests” determine file types by looking for certain string or binary values at specific offsets in the file being examined. These position-sensitive tests were implemented in historical systems using the magic file described above. Some of these tests are now built into the file utility itself on some implementations so the output can provide more detail than can be provided by magic files. For example, a magic file can easily identify a core file on most implementations, but cannot name the program file that dropped the core. A magic file could produce output such as:

/home/dwc/core: ELF 32-bit MSB core file SPARC Version 1

but by building the test into the file utility, you could get output such as:

/home/dwc/core: ELF 32-bit MSB core file SPARC Version 1, from 'testprog'

These extended built-in tests are still to be treated as position-sensitive default system tests even if they are not listed in /etc/magic or any other magic file.

The context-sensitive default system tests were always built into the file utility. These tests looked for language constructs in text files trying to identify shell scripts, C, FORTRAN, and other computer language source files, and even plain text files. With the addition of the -m and -M options the distinction between position-sensitive and context-sensitive default system tests became important because the order of testing is important. The context-sensitive system default tests should never be applied before any position-sensitive tests even if the -d option is specified before a -m option or -M option due to the high probability that the context-sensitive system default tests will incorrectly identify arbitrary text files as text files before position-sensitive tests specified by the -m or -M option would be applied to give a more accurate identification.

Leaving the meaning of -M - and -m - unspecified allows an existing prototype of these options to continue to work in a backwards-compatible manner. (In that implementation, -M - was roughly equivalent to -d in POSIX.1-2008.)

The historical -c option was omitted as not particularly useful to users or portable shell scripts. In addition, a reasonable implementation of the file utility would report any errors found each time the magic file is read.

The historical format of the magic file was the same as that specified by the Rationale in the ISO POSIX-2:1993 standard for the offset, value, and message fields; however, it used less precise type fields than the format specified by the current normative text. The new type field values are a superset of the historical ones.

The following is an example magic file:

0  short     070707              cpio archive
0  short     0143561             Byte-swapped cpio archive
0  string    070707              ASCII cpio archive
0  long      0177555             Very old archive
0  short     0177545             Old archive
0  short     017437              Old packed data
0  string    \037\036            Packed data
0  string    \377\037            Compacted data
0  string    \037\235            Compressed data
>2 byte&0x80 >0                  Block compressed
>2 byte&0x1f x                   %d bits
0  string    \032\001            Compiled Terminfo Entry
0  short     0433                Curses screen image
0  short     0434                Curses screen image
0  string    <ar>                System V Release 1 archive
0  string    !<arch>\n__.SYMDEF  Archive random library
0  string    !<arch>             Archive
0  string    ARF_BEGARF          PHIGS clear text archive
0  long      0x137A2950          Scalable OpenFont binary
0  long      0x137A2951          Encrypted scalable OpenFont binary

The use of a basic integer data type is intended to allow the implementation to choose a word size commonly used by applications on that architecture.

Earlier versions of this standard allowed for implementations with bytes other than eight bits, but this has been modified in this version.

🔮 FUTURE DIRECTIONS 🔮

None. Not a single one. The future is a blank canvas bestie. 🦋

👀 SEE ALSO 👀

  • ar
  • ls
  • pax
  • printf

The Base Definitions volume of POSIX.1-2017, Table 5-1, Escape Sequences and Associated Actions, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines.

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

And that's the whole vibe check! Source/version: IEEE/The Open Group, 2017, FILE(1POSIX). Bye bestie, stay iconic! 💅✨

📦 where this page comes from