Provided by: manpages-posix_2017a-2_all 
PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of
this interface may differ (consult the corresponding Linux manual page for details of
Linux behavior), or the interface may not be implemented on Linux.
NAME
file — determine file type
SYNOPSIS
file [-dh] [-M file] [-m file] file...
file -i [-h] file...
DESCRIPTION
The file utility shall perform a series of tests in sequence on each specified file in an
attempt to classify it:
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.
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.
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 make a guess at identifying its contents based
on context-sensitive default system tests. (The answer is not guaranteed to be
correct.)
6. The file shall be identified as a data file.
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.
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.
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.
-h When a symbolic link is encountered, identify the file as a symbolic link. 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.
-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.
-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.
-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).
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. If a -M or -m file option-argument is -, the
results are unspecified.
OPERANDS
The following operand shall be supported:
file A pathname of a file to be tested.
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.
INPUT FILES
The file can be any file type.
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.
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.
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. Each <space> shown in the strings shall be
exactly one <space>.
Table 4-9: File Utility Output Strings
┌─────────────────────────────────────────────┬──────────────────────────────────┬───────┐
│ If file is: │ <type> shall contain the string: │ Notes │
├─────────────────────────────────────────────┼──────────────────────────────────┼───────┤
│Nonexistent │ cannot open │ │
│ │ │ │
│Block special │ block special │ 1 │
│Character special │ character special │ 1 │
│Directory │ directory │ 1 │
│FIFO │ fifo │ 1 │
│Socket │ socket │ 1 │
│Symbolic link │ symbolic link to │ 1 │
│Regular file │ regular file │ 1,2 │
│Empty regular file │ empty │ 3 │
│Regular file that cannot be read │ cannot open │ 3 │
│ │ │ │
│Executable binary │ executable │ 3,4,6 │
│ar archive library (see ar) │ archive │ 3,4,6 │
│Extended cpio format (see pax) │ cpio archive │ 3,4,6 │
│Extended tar format (see ustar in pax) │ tar archive │ 3,4,6 │
│ │ │ │
│Shell script │ commands text │ 3,5,6 │
│C-language source │ c program text │ 3,5,6 │
│FORTRAN source │ fortran program text │ 3,5,6 │
│ │ │ │
│Regular file whose type cannot be determined │ data │ 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>"
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.
STDERR
The standard error shall be used only for diagnostic messages.
OUTPUT FILES
None.
EXTENDED DESCRIPTION
A file specified as an option-argument to the -m or -M options shall contain one position-
sensitive test per line, which shall be applied to the file. If the test succeeds, the
message field of the line shall be printed and no further tests shall be applied, with the
exception that tests on immediately following lines beginning with a single '>' character
shall be applied.
Each line shall be composed of the following four <tab>-separated fields. (Implementations
may allow any combination of one or more white-space characters other than <newline> to
act as field separators.)
offset An unsigned number (optionally preceded by a single '>' character) specifying
the offset, in bytes, of the value in the file that is to be compared against
the value field of the line. If the file is shorter than the specified offset,
the test shall fail.
If the offset begins with the character '>', the test contained in the line
shall not be applied to the file unless the test on the last line for which the
offset did not begin with a '>' was successful. By default, the offset shall be
interpreted as an unsigned decimal number. With a leading 0x or 0X, the offset
shall be interpreted as a hexadecimal number; otherwise, with a leading 0, the
offset shall be interpreted as an octal number.
type The type of the value in the file to be tested. The type shall consist of the
type specification characters d, s, and u, specifying signed decimal, string,
and unsigned decimal, respectively.
The type string shall be interpreted as the bytes from the file starting at the
specified offset and including the same number of bytes specified by the value
field. If insufficient bytes remain in the file past the offset to match the
value field, the test shall fail.
The type specification characters d and u can be followed by an optional
unsigned decimal integer that specifies the number of bytes represented by the
type. The type specification characters d and u can be followed by an optional
C, S, I, or L, indicating that 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 shall
correspond to their respective C-language types as follows. If the system claims
conformance to the C-Language Development Utilities option, those specifiers
shall correspond to the default sizes used in the c99 utility. Otherwise, the
default sizes shall be implementation-defined.
For the type specifier characters d and u, the default number of bytes shall
correspond 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 shall
correspond to the order in which a constant of the corresponding type is stored
in memory on the system.
All type specifiers, except for s, can be followed by a mask specifier of the
form &number. The mask value shall be 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 shall be interpreted as an unsigned decimal number. With a leading 0x or
0X, the mask shall be interpreted as an unsigned hexadecimal number; otherwise,
with a leading 0, the mask shall be interpreted as an unsigned octal number.
The strings byte, short, long, and string shall also be supported as type
fields, being 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, then interpret the value as
a string. Otherwise, interpret it as a number. If the value is a string, then
the test shall succeed only when a string value exactly matches the bytes from
the file.
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').
In addition, 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 that can be used to represent characters with
specific coded values. An octal sequence shall consist of a
<backslash> followed by the longest sequence of one, two, or three
octal-digit characters (01234567).
By default, any value that is not a string shall be interpreted as a signed
decimal number. Any such value, with a leading 0x or 0X, shall be interpreted as
an unsigned hexadecimal number; otherwise, with a leading zero, the value shall
be interpreted as an unsigned octal number.
If the value is not a string, it can be preceded by a character indicating the
comparison to be performed. Permissible characters and the comparisons they
specify are as follows:
= The test shall succeed if the value from the file equals the value field.
< The test shall succeed if the value from the file is less than the value
field.
> The test shall succeed if the value from the file is greater than the
value field.
& The test shall succeed if all of the set bits in the value field are set
in the value from the file.
^ The test shall succeed if at least one of the set bits in the value field
is not set in the value from the file.
x The test shall succeed 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 shall be 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
The following exit values shall be returned:
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. For example, binary data on
some implementations might match the initial segment of an executable or a tar archive.
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"
RATIONALE
The -f option was omitted because the same effect can (and should) be obtained using the
xargs utility.
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.
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.
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
COPYRIGHT
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 .