path: root/man1p/file.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "FILE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" file 
.SH NAME
file \- determine file type
.SH SYNOPSIS
.LP
\fBfile\fP \fB[\fP\fB-dh\fP\fB][\fP\fB-M\fP \fIfile\fP\fB][\fP\fB-m\fP
\fIfile\fP\fB]\fP
\fIfile\fP \fB...
.br
.sp
file -i\fP \fB[\fP\fB-h\fP\fB]\fP \fIfile\fP \fB... \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIfile\fP utility shall perform a series of tests in sequence
on each specified \fIfile\fP in an attempt to classify
it:
.IP " 1." 4
If \fIfile\fP 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.
.LP
.IP " 2." 4
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 \fIfile\fP is a
symbolic link, by default the link shall be resolved and \fIfile\fP
shall test the type of file referenced by the symbolic link.
(See the \fB-h\fP and \fB-i\fP options below.)
.LP
.IP " 3." 4
If the length of \fIfile\fP is zero, it shall be identified as an
empty file.
.LP
.IP " 4." 4
The \fIfile\fP utility shall examine an initial segment of \fIfile\fP
and shall make a guess at identifying its contents based
on position-sensitive tests. (The answer is not guaranteed to be correct;
see the \fB-d\fP, \fB-M\fP, and \fB-m\fP options
below.)
.LP
.IP " 5." 4
The \fIfile\fP utility shall examine \fIfile\fP and make a guess at
identifying its contents based on context-sensitive
default system tests. (The answer is not guaranteed to be correct.)
.LP
.IP " 6." 4
The file shall be identified as a data file.
.LP
.LP
If \fIfile\fP 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.
.LP
If \fIfile\fP is a symbolic link, by default the link shall be resolved
and \fIfile\fP shall test the type of file referenced
by the symbolic link.
.SH OPTIONS
.LP
The \fIfile\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines,
except that the order of the \fB-m\fP,
\fB-d\fP, and \fB-M\fP options shall be significant.
.LP
The following options shall be supported by the implementation:
.TP 7
\fB-d\fP
Apply any position-sensitive default system tests and context-sensitive
default system tests to the file. This is the default
if no \fB-M\fP or \fB-m\fP option is specified.
.TP 7
\fB-h\fP
When a symbolic link is encountered, identify the file as a symbolic
link. If \fB-h\fP is not specified and \fIfile\fP is a
symbolic link that refers to a nonexistent file, \fIfile\fP shall
identify the file as a symbolic link, as if \fB-h\fP had been
specified.
.TP 7
\fB-i\fP
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.
.TP 7
\fB-M\ \fP \fIfile\fP
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 \fB-d\fP option is also specified.
.TP 7
\fB-m\ \fP \fIfile\fP
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).
.sp
.LP
If the \fB-m\fP option is specified without specifying the \fB-d\fP
option or the \fB-M\fP option, position-sensitive default
system tests shall be applied after the position-sensitive tests specified
by the \fB-m\fP option. If the \fB-M\fP option is
specified with the \fB-d\fP option, the \fB-m\fP option, or both,
or the \fB-m\fP option is specified with the \fB-d\fP 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 \fB-M\fP or \fB-m\fP \fIfile\fP
option-argument is \fB-\fP, the results are unspecified.
.SH OPERANDS
.LP
The following operand shall be supported:
.TP 7
\fIfile\fP
A pathname of a file to be tested.
.sp
.SH STDIN
.LP
Not used.
.SH INPUT FILES
.LP
The \fIfile\fP can be any file type.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIfile\fP:
.TP 7
\fILANG\fP
Provide a default value for the internationalization variables that
are unset or null. (See the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
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).
.TP 7
\fILC_MESSAGES\fP
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.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP 
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
In the POSIX locale, the following format shall be used to identify
each operand, \fIfile\fP specified:
.sp
.RS
.nf

\fB"%s: %s\\n", <\fP\fIfile\fP\fB>, <\fP\fItype\fP\fB>
\fP
.fi
.RE
.LP
The values for <\fItype\fP> are unspecified, except that in the POSIX
locale, if \fIfile\fP is identified as one of the
types listed in the following table, <\fItype\fP> shall contain (but
is not limited to) the corresponding string, unless the
file is identified by a position-sensitive test specified by a \fB-M\fP
or \fB-m\fP option. Each space shown in the strings shall
be exactly one <space>.
.br
.sp
.ce 1
\fBTable: File Utility Output Strings\fP
.TS C
center; lw(40)1 lw(25)1 l.
T{
.na
\fBIf \fIfile\fP is:\fP
.ad
T}	T{
.na
\fB<\fItype\fP> shall contain the string:\fP
.ad
T}	\fBNotes\fP
T{
.na
Nonexistent
.ad
T}	T{
.na
cannot open
.ad
T}	\ 
T{
.na
Block special
.ad
T}	T{
.na
block special
.ad
T}	1
T{
.na
Character special
.ad
T}	T{
.na
character special
.ad
T}	1
T{
.na
Directory
.ad
T}	T{
.na
directory
.ad
T}	1
T{
.na
FIFO
.ad
T}	T{
.na
fifo
.ad
T}	1
T{
.na
Socket
.ad
T}	T{
.na
socket
.ad
T}	1
T{
.na
Symbolic link
.ad
T}	T{
.na
symbolic link to
.ad
T}	1
T{
.na
Regular file
.ad
T}	T{
.na
regular file
.ad
T}	1,2
T{
.na
Empty regular file
.ad
T}	T{
.na
empty
.ad
T}	3
T{
.na
Regular file that cannot be read
.ad
T}	T{
.na
cannot open
.ad
T}	3
T{
.na
Executable binary
.ad
T}	T{
.na
executable
.ad
T}	4,6
T{
.na
\fIar\fP archive library (see \fIar\fP)
.ad
T}	T{
.na
archive
.ad
T}	4,6
T{
.na
Extended \fIcpio\fP format (see \fIpax\fP)
.ad
T}	T{
.na
cpio archive
.ad
T}	4,6
T{
.na
Extended \fItar\fP format (see \fBustar\fP in \fIpax\fP)
.ad
T}	T{
.na
tar archive
.ad
T}	4,6
T{
.na
Shell script
.ad
T}	T{
.na
commands text
.ad
T}	5,6
T{
.na
C-language source
.ad
T}	T{
.na
c program text
.ad
T}	5,6
T{
.na
FORTRAN source
.ad
T}	T{
.na
fortran program text
.ad
T}	5,6
T{
.na
Regular file whose type cannot be determined
.ad
T}	T{
.na
data
.ad
T}	\ 
.TE
.TP 7
\fBNotes:\fP
.RS
.IP " 1." 4
This is a file type test.
.LP
.IP " 2." 4
This test is applied only if the \fB-i\fP option is specified.
.LP
.IP " 3." 4
This test is applied only if the \fB-i\fP option is not specified.
.LP
.IP " 4." 4
This is a position-sensitive default system test.
.LP
.IP " 5." 4
This is a context-sensitive default system test.
.LP
.IP " 6." 4
Position-sensitive default system tests and context-sensitive default
system tests are not applied if the \fB-M\fP option is
specified unless the \fB-d\fP option is also specified.
.LP
.RE
.sp
.LP
In the POSIX locale, if \fIfile\fP is identified as a symbolic link
(see the \fB-h\fP option), the following alternative
output format shall be used:
.sp
.RS
.nf

\fB"%s: %s %s\\n", <\fP\fIfile\fP\fB>, <\fP\fItype\fP\fB>, <\fP\fIcontents of link\fP\fB>"
\fP
.fi
.RE
.LP
If the file named by the \fIfile\fP operand does not exist, cannot
be read, or the type of the file named by the \fIfile\fP
operand cannot be determined, this shall not be considered an error
that affects the exit status.
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
None.
.SH EXTENDED DESCRIPTION
.LP
A file specified as an option-argument to the \fB-m\fP or \fB-M\fP
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 \fB'>'\fP character shall be
applied.
.LP
Each line shall be composed of the following four <blank>-separated
fields:
.TP 7
\fIoffset\fP
An unsigned number (optionally preceded by a single \fB'>'\fP character)
specifying the \fIoffset\fP, in bytes, of the
value in the file that is to be compared against the \fIvalue\fP field
of the line. If the file is shorter than the specified
offset, the test shall fail. 
.LP
If the \fIoffset\fP begins with the character \fB'>'\fP , the test
contained in the line shall not be applied to the file
unless the test on the last line for which the \fIoffset\fP did not
begin with a \fB'>'\fP was successful. By default, the
\fIoffset\fP shall be interpreted as an unsigned decimal number. With
a leading 0x or 0X, the \fIoffset\fP shall be interpreted
as a hexadecimal number; otherwise, with a leading 0, the \fIoffset\fP
shall be interpreted as an octal number.
.TP 7
\fItype\fP
The type of the value in the file to be tested. The type shall consist
of the type specification characters \fBc\fP ,
\fBd\fP , \fBf\fP , \fBs\fP , and \fBu\fP , specifying character,
signed decimal, floating point, string, and unsigned
decimal, respectively. 
.LP
The \fItype\fP string shall be interpreted as the bytes from the file
starting at the specified \fIoffset\fP and including the
same number of bytes specified by the \fIvalue\fP field. If insufficient
bytes remain in the file past the \fIoffset\fP to match
the \fIvalue\fP field, the test shall fail.
.LP
The type specification characters \fBd\fP , \fBf\fP , and \fBu\fP
can be followed by an optional unsigned decimal
integer that specifies the number of bytes represented by the type.
The type specification character \fBf\fP can be followed by
an optional \fBF\fP , \fBD\fP , or \fBL\fP , indicating that the value
is of type \fBfloat\fP, \fBdouble\fP, or \fBlong
double\fP, respectively. The type specification characters \fBd\fP
and \fBu\fP can be followed by an optional \fBC\fP ,
\fBS\fP , \fBI\fP , or \fBL\fP , indicating that the value is of type
\fBchar\fP, \fBshort\fP, \fBint\fP, or
\fBlong\fP, respectively.
.LP
The default number of bytes represented by the type specifiers \fBd\fP
, \fBf\fP , and \fBu\fP 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
\fIc99\fP utility.
Otherwise, the default sizes shall be implementation-defined.
.LP
For the type specifier characters \fBd\fP and \fBu\fP , 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 \fBchar\fP, \fBshort\fP, \fBint\fP,
or \fBlong\fP. These numbers can also be specified by an application
as the characters \fBC\fP , \fBS\fP , \fBI\fP , and
\fBL\fP , 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.
.LP
For the type specifier \fBf\fP , the default number of bytes shall
correspond to the number of bytes in the basic double
precision floating-point data type of the underlying implementation.
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 \fBfloat\fP, \fBdouble\fP, and \fBlong
double\fP. These numbers can also be specified by an application as
the characters \fBF\fP , \fBD\fP , and \fBL\fP ,
respectively.
.LP
All type specifiers, except for \fBs\fP , can be followed by a mask
specifier of the form &\fInumber\fP. The mask value
shall be AND'ed with the value of the input file before the comparison
with the \fIvalue\fP 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.
.LP
The strings \fBbyte\fP, \fBshort\fP, \fBlong\fP, and \fBstring\fP
shall also be supported as type fields, being interpreted
as \fBdC\fP , \fBdS\fP , \fBdL\fP , and \fBs\fP , respectively.
.TP 7
\fIvalue\fP
The \fIvalue\fP to be compared with the value from the file. 
.LP
If the specifier from the type field is \fBs\fP or \fBstring\fP, 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.
.LP
If the \fIvalue\fP is a string, it can contain the following sequences:
.TP 7
\\\fIcharacter\fP
.RS
The backslash-escape sequences as specified in the Base Definitions
volume of IEEE\ Std\ 1003.1-2001, Table 5-1, Escape
Sequences and Associated Actions ( \fB'\\\\'\fP , \fB'\\a'\fP , \fB'\\b'\fP
, \fB'\\f'\fP , \fB'\\n'\fP , \fB'\\r'\fP ,
\fB'\\t'\fP , \fB'\\v'\fP ). The results of using any other character,
other than an octal digit, following the backslash are
unspecified.
.RE
.TP 7
\\\fIoctal\fP
.RS
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). If the size of a byte on the
system is greater than 9 bits, the valid escape sequence used to represent
a byte is implementation-defined.
.RE
.sp
.LP
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.
.LP
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:
.TP 7
\fB=\fP
.RS
The test shall succeed if the value from the file equals the \fIvalue\fP
field.
.RE
.TP 7
\fB<\fP
.RS
The test shall succeed if the value from the file is less than the
\fIvalue\fP field.
.RE
.TP 7
\fB>\fP
.RS
The test shall succeed if the value from the file is greater than
the \fIvalue\fP field.
.RE
.TP 7
\fB&\fP
.RS
The test shall succeed if all of the set bits in the \fIvalue\fP field
are set in the value from the file.
.RE
.TP 7
\fB^\fP
.RS
The test shall succeed if at least one of the set bits in the \fIvalue\fP
field is not set in the value from the file.
.RE
.TP 7
\fBx\fP
.RS
The test shall succeed if the file is large enough to contain a value
of the type specified starting at the offset
specified.
.RE
.sp
.TP 7
\fImessage\fP
The \fImessage\fP to be printed if the test succeeds. The \fImessage\fP
shall be interpreted using the notation for the \fIprintf\fP formatting
specification; see \fIprintf\fP() . If the
\fIvalue\fP field was a string, then the value from the file shall
be the argument for the \fIprintf\fP formatting specification; otherwise,
the value from the file shall be the
argument.
.sp
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
Successful completion.
.TP 7
>0
An error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
Default.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
The \fIfile\fP 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
\fItar\fP archive.
.LP
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
\fB"#!"\fP as executable files, these may be identified as
executable binary files rather than as shell scripts.
.SH EXAMPLES
.LP
Determine whether an argument is a binary executable file:
.sp
.RS
.nf

\fBfile "$1" | grep -Fq executable &&
    printf "%s is executable.\\n" "$1"
\fP
.fi
.RE
.SH RATIONALE
.LP
The \fB-f\fP option was omitted because the same effect can (and should)
be obtained using the \fIxargs\fP utility.
.LP
Historical versions of the \fIfile\fP utility attempt to identify
the following types of files: symbolic link, directory,
character special, block special, socket, \fItar\fP archive, \fIcpio\fP
archive, SCCS archive, archive library, empty, \fIcompress\fP output,
\fIpack\fP output, binary data, C source, FORTRAN source, assembler
source, \fInroff\fP/ \fItroff\fP/ \fIeqn\fP/ \fItbl\fP source \fItroff\fP
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.
.LP
Historical systems have used a "magic file" named \fB/etc/magic\fP
to help identify file types. Because it is generally
useful for users and scripts to be able to identify special file types,
the \fB-m\fP flag and a portable format for user-created
magic files has been specified. No requirement is made that an implementation
of \fIfile\fP use this method of identifying files,
only that users be permitted to add their own classifying tests.
.LP
In addition, three options have been added to historical practice.
The \fB-d\fP flag has been added to permit users to cause
their tests to follow any default system tests. The \fB-i\fP flag
has been added to permit users to test portably for regular
files in shell scripts. The \fB-M\fP flag has been added to permit
users to ignore any default system tests.
.LP
The IEEE\ Std\ 1003.1-2001 description of default system tests and
the interaction between the \fB-d\fP, \fB-M\fP, and
\fB-m\fP 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 \fIfile\fP 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 \fBcore\fP
file on most implementations, but cannot name the program
file that dropped the core. A magic file could produce output such
as:
.sp
.RS
.nf

\fB/home/dwc/core: ELF 32-bit MSB core file SPARC Version 1
\fP
.fi
.RE
.LP
but by building the test into the \fIfile\fP utility, you could get
output such as:
.sp
.RS
.nf

\fB/home/dwc/core: ELF 32-bit MSB core file SPARC Version 1, from 'testprog'
\fP
.fi
.RE
.LP
These extended built-in tests are still to be treated as position-sensitive
default system tests even if they are not listed in
\fB/etc/magic\fP or any other magic file.
.LP
The context-sensitive default system tests were always built into
the \fIfile\fP 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 \fB-m\fP and \fB-M\fP 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 \fB-d\fP option is specified before a
\fB-m\fP option or \fB-M\fP 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 \fB-m\fP or \fB-M\fP option would be
applied to give a more accurate identification.
.LP
Leaving the meaning of \fB-M -\fP and \fB-m -\fP unspecified allows
an existing prototype of these options to continue to work
in a backwards-compatible manner. (In that implementation, \fB-M -\fP
was roughly equivalent to \fB-d\fP in
IEEE\ Std\ 1003.1-2001.)
.LP
The historical \fB-c\fP option was omitted as not particularly useful
to users or portable shell scripts. In addition, a
reasonable implementation of the \fIfile\fP utility would report any
errors found each time the magic file is read.
.LP
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 \fIoffset\fP, \fIvalue\fP, and \fImessage\fP 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.
.LP
The following is an example magic file:
.sp
.RS
.nf

\fB0  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
\fP
.fi
.RE
.LP
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.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIar\fP , \fIls\fP , \fIpax\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 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 .