FILE(1)                    POSIX Programmer's Manual                   FILE(1)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       file -- determine file type

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

       file -i [[-h]] _f_i_l_e...

DDEESSCCRRIIPPTTIIOONN
       The _f_i_l_e utility shall perform a series of tests in sequence on each
       specified _f_i_l_e in an attempt to classify it:

        1. If _f_i_l_e 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 _f_i_l_e
           is a symbolic link, by default the link shall be resolved and _f_i_l_e
           shall test the type of file referenced by the symbolic link. (See
           the --hh and --ii options below.)

        3. If the length of _f_i_l_e is zero, it shall be identified as an empty
           file.

        4. The _f_i_l_e utility shall examine an initial segment of _f_i_l_e and shall
           make a guess at identifying its contents based on position-
           sensitive tests. (The answer is not guaranteed to be correct; see
           the --dd, --MM, and --mm options below.)

        5. The _f_i_l_e utility shall examine _f_i_l_e 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 _f_i_l_e 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 _f_i_l_e is a symbolic link, by default the link shall be resolved and
       _f_i_l_e shall test the type of file referenced by the symbolic link.

OOPPTTIIOONNSS
       The _f_i_l_e utility shall conform to the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s, except that the
       order of the --mm, --dd, and --MM options shall be significant.

       The following options shall be supported by the implementation:

       --dd        Apply any position-sensitive default system tests and
                 context-sensitive default system tests to the file. This is
                 the default if no --MM or --mm option is specified.

       --hh        When a symbolic link is encountered, identify the file as a
                 symbolic link. If --hh is not specified and _f_i_l_e is a symbolic
                 link that refers to a nonexistent file, _f_i_l_e shall identify
                 the file as a symbolic link, as if --hh had been specified.

       --ii        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.

       --MM _f_i_l_e   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 --dd option is also specified.

       --mm _f_i_l_e   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 --mm option is specified without specifying the --dd option or the
       --MM option, position-sensitive default system tests shall be applied
       after the position-sensitive tests specified by the --mm option. If the
       --MM option is specified with the --dd option, the --mm option, or both, or
       the --mm option is specified with the --dd 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 --MM or --mm
       _f_i_l_e option-argument is --, the results are unspecified.

OOPPEERRAANNDDSS
       The following operand shall be supported:

       _f_i_l_e      A pathname of a file to be tested.

SSTTDDIINN
       The standard input shall be used if a _f_i_l_e operand is ''--'' and the
       implementation treats the ''--'' as meaning standard input.  Otherwise,
       the standard input shall not be used.

IINNPPUUTT FFIILLEESS
       The _f_i_l_e can be any file type.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _f_i_l_e:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

       _L_C___A_L_L    If set to a non-empty string value, override the values of
                 all the other internationalization variables.

       _L_C___C_T_Y_P_E  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).

       _L_C___M_E_S_S_A_G_E_S
                 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.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       In the POSIX locale, the following format shall be used to identify
       each operand, _f_i_l_e specified:


           "%s: %s\n", <_f_i_l_e>, <_t_y_p_e>

       The values for <_t_y_p_e> are unspecified, except that in the POSIX locale,
       if _f_i_l_e is identified as one of the types listed in the following
       table, <_t_y_p_e> shall contain (but is not limited to) the corresponding
       string, unless the file is identified by a position-sensitive test
       specified by a --MM or --mm option. Each <space> shown in the strings shall
       be exactly one <space>.

                       TTaabbllee 44--99:: FFiillee UUttiilliittyy OOuuttppuutt SSttrriinnggss

-------+---------------------------------------------+----------------------------------+-      |
       |         IIff _f_i_l_e iiss::                    <<_t_y_p_e|>> sshhaallll ccoonnttaaiinn tthhee ssttrriinngg::   NNootteess|       |
-------+---------------------------------------------+----------------------------------+-      |
 Nonexi|stent                                    canno|t 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 |
       |_a_r archive library (see _a_r)                  | archive                          | 3,4,6 |
       |Extended _c_p_i_o format (see _p_a_x)               | cpio archive                     | 3,4,6 |
       |Extended _t_a_r format (see uussttaarr in _p_a_x)       | 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     |
       +---------------------------------------------+----------------------------------+-------+
       NNootteess::

                  1. This is a file type test.

                  2. This test is applied only if the --ii option is specified.

                  3. This test is applied only if the --ii 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 --MM
                     option is specified unless the --dd option is also
                     specified.

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


           "%s: %s %s\n", <_f_i_l_e>, <_t_y_p_e>, <_c_o_n_t_e_n_t_s _o_f _l_i_n_k>"

       If the file named by the _f_i_l_e operand does not exist, cannot be read,
       or the type of the file named by the _f_i_l_e operand cannot be determined,
       this shall not be considered an error that affects the exit status.

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       A file specified as an option-argument to the --mm or --MM 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.)

       _o_f_f_s_e_t    An unsigned number (optionally preceded by a single ''>>''
                 character) specifying the _o_f_f_s_e_t, in bytes, of the value in
                 the file that is to be compared against the _v_a_l_u_e field of
                 the line. If the file is shorter than the specified offset,
                 the test shall fail.

                 If the _o_f_f_s_e_t 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 _o_f_f_s_e_t did not begin
                 with a ''>>'' was successful. By default, the _o_f_f_s_e_t shall be
                 interpreted as an unsigned decimal number. With a leading 0x
                 or 0X, the _o_f_f_s_e_t shall be interpreted as a hexadecimal
                 number; otherwise, with a leading 0, the _o_f_f_s_e_t shall be
                 interpreted as an octal number.

       _t_y_p_e      The type of the value in the file to be tested. The type
                 shall consist of the type specification characters dd, ss, and
                 uu, specifying signed decimal, string, and unsigned decimal,
                 respectively.

                 The _t_y_p_e string shall be interpreted as the bytes from the
                 file starting at the specified _o_f_f_s_e_t and including the same
                 number of bytes specified by the _v_a_l_u_e field. If insufficient
                 bytes remain in the file past the _o_f_f_s_e_t to match the _v_a_l_u_e
                 field, the test shall fail.

                 The type specification characters dd and uu can be followed by
                 an optional unsigned decimal integer that specifies the
                 number of bytes represented by the type. The type
                 specification characters dd and uu can be followed by an
                 optional CC, SS, II, or LL, indicating that the value is of type
                 cchhaarr, sshhoorrtt, iinntt, or lloonngg, respectively.

                 The default number of bytes represented by the type
                 specifiers dd, ff, and uu 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
                 _c_9_9 utility. Otherwise, the default sizes shall be
                 implementation-defined.

                 For the type specifier characters dd and uu, 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 cchhaarr, sshhoorrtt, iinntt, or lloonngg.  These
                 numbers can also be specified by an application as the
                 characters CC, SS, II, and LL, 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 ss, can be followed by a mask
                 specifier of the form &_n_u_m_b_e_r. The mask value shall be AND'ed
                 with the value of the input file before the comparison with
                 the _v_a_l_u_e 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 bbyyttee, sshhoorrtt, lloonngg, and ssttrriinngg shall also be
                 supported as type fields, being interpreted as ddCC, ddSS, ddLL,
                 and ss, respectively.

       _v_a_l_u_e     The _v_a_l_u_e to be compared with the value from the file.

                 If the specifier from the type field is ss or ssttrriinngg, 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 _v_a_l_u_e is a string, it can contain the following
                 sequences:

                 \_c_h_a_r_a_c_t_e_r  The <backslash>-escape sequences as specified in
                             the Base Definitions volume of POSIX.1-2017,
                             _T_a_b_l_e _5_-_1, _E_s_c_a_p_e _S_e_q_u_e_n_c_e_s _a_n_d _A_s_s_o_c_i_a_t_e_d
                             _A_c_t_i_o_n_s (''\\\\'', ''\\aa'', ''\\bb'', ''\\ff'', ''\\nn'', ''\\rr'',
                             ''\\tt'', ''\\vv'').  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.

                 \_o_c_t_a_l      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 _v_a_l_u_e field.

                 <     The test shall succeed if the value from the file is
                       less than the _v_a_l_u_e field.

                 >     The test shall succeed if the value from the file is
                       greater than the _v_a_l_u_e field.

                 &     The test shall succeed if all of the set bits in the
                       _v_a_l_u_e field are set in the value from the file.

                 ^     The test shall succeed if at least one of the set bits
                       in the _v_a_l_u_e 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.

       _m_e_s_s_a_g_e   The _m_e_s_s_a_g_e to be printed if the test succeeds. The _m_e_s_s_a_g_e
                 shall be interpreted using the notation for the _p_r_i_n_t_f
                 formatting specification; see _p_r_i_n_t_f.  If the _v_a_l_u_e field was
                 a string, then the value from the file shall be the argument
                 for the _p_r_i_n_t_f formatting specification; otherwise, the value
                 from the file shall be the argument.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The _f_i_l_e 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 _t_a_r 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.

EEXXAAMMPPLLEESS
       Determine whether an argument is a binary executable file:


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

RRAATTIIOONNAALLEE
       The --ff option was omitted because the same effect can (and should) be
       obtained using the _x_a_r_g_s utility.

       Historical versions of the _f_i_l_e utility attempt to identify the
       following types of files: symbolic link, directory, character special,
       block special, socket, _t_a_r archive, _c_p_i_o archive, SCCS archive, archive
       library, empty, _c_o_m_p_r_e_s_s output, _p_a_c_k output, binary data, C source,
       FORTRAN source, assembler source, _n_r_o_f_f/_t_r_o_f_f/_e_q_n/_t_b_l source _t_r_o_f_f
       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 //eettcc//mmaaggiicc to help
       identify file types. Because it is generally useful for users and
       scripts to be able to identify special file types, the --mm flag and a
       portable format for user-created magic files has been specified. No
       requirement is made that an implementation of _f_i_l_e 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
       --dd flag has been added to permit users to cause their tests to follow
       any default system tests. The --ii flag has been added to permit users to
       test portably for regular files in shell scripts. The --MM 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 --dd, --MM, and --mm 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 _f_i_l_e 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 ccoorree 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 _f_i_l_e 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
       //eettcc//mmaaggiicc or any other magic file.

       The context-sensitive default system tests were always built into the
       _f_i_l_e 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 --mm and --MM 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 --dd option is specified before a --mm option or --MM 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 --mm or --MM option would be
       applied to give a more accurate identification.

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

       The historical --cc option was omitted as not particularly useful to
       users or portable shell scripts. In addition, a reasonable
       implementation of the _f_i_l_e 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 _o_f_f_s_e_t,
       _v_a_l_u_e, and _m_e_s_s_a_g_e 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.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _a_r, _l_s, _p_a_x, _p_r_i_n_t_f

       The Base Definitions volume of POSIX.1-2017, _T_a_b_l_e _5_-_1, _E_s_c_a_p_e
       _S_e_q_u_e_n_c_e_s _a_n_d _A_s_s_o_c_i_a_t_e_d _A_c_t_i_o_n_s, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e_s,
       _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

CCOOPPYYRRIIGGHHTT
       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 .



IEEE/The Open Group                  2017                              FILE(1)
