file.html

IEEE 1003.1-2003, Single Unix Specification v3

double</b>. These numbers can also be specified by an application as the characters <tt>F</tt> , <tt>D</tt> , and <tt>L</tt> ,
respectively.</p>

<p>All type specifiers, except for <tt>s</tt> , can be followed by a mask specifier of the form &amp;<i>number</i>. The mask value
shall be AND'ed with the value of the input file before the comparison with the <i>value</i> 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.</p>

<p>The strings <b>byte</b>, <b>short</b>, <b>long</b>, and <b>string</b> shall also be supported as type fields, being interpreted
as <tt>dC</tt> , <tt>dS</tt> , <tt>dL</tt> , and <tt>s</tt> , respectively.</p>
</dd>

<dt><i>value</i></dt>

<dd>The <i>value</i> to be compared with the value from the file. 

<p>If the specifier from the type field is <tt>s</tt> or <b>string</b>, 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.</p>

<p>If the <i>value</i> is a string, it can contain the following sequences:</p>

<dl compact>
<dt>\<i>character</i></dt>

<dd>The backslash-escape sequences as specified in the Base Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, Table 5-1, Escape
Sequences and Associated Actions ( <tt>'\\'</tt> , <tt>'\a'</tt> , <tt>'\b'</tt> , <tt>'\f'</tt> , <tt>'\n'</tt> , <tt>'\r'</tt> ,
<tt>'\t'</tt> , <tt>'\v'</tt> ). The results of using any other character, other than an octal digit, following the backslash are
unspecified.</dd>

<dt>\<i>octal</i></dt>

<dd>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.</dd>
</dl>

<p>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.</p>

<p>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:</p>

<dl compact>
<dt><tt>=</tt></dt>

<dd>The test shall succeed if the value from the file equals the <i>value</i> field.</dd>

<dt><tt>&lt;</tt></dt>

<dd>The test shall succeed if the value from the file is less than the <i>value</i> field.</dd>

<dt><tt>&gt;</tt></dt>

<dd>The test shall succeed if the value from the file is greater than the <i>value</i> field.</dd>

<dt><tt>&amp;</tt></dt>

<dd>The test shall succeed if all of the set bits in the <i>value</i> field are set in the value from the file.</dd>

<dt><tt>^</tt></dt>

<dd>The test shall succeed if at least one of the set bits in the <i>value</i> field is not set in the value from the file.</dd>

<dt><tt>x</tt></dt>

<dd>The test shall succeed if the file is large enough to contain a value of the type specified starting at the offset
specified.</dd>
</dl>
</dd>

<dt><i>message</i></dt>

<dd>The <i>message</i> to be printed if the test succeeds. The <i>message</i> shall be interpreted using the notation for the <a
href="../utilities/printf.html"><i>printf</i></a> formatting specification; see <a href="printf.html"><i>printf</i>()</a> . If the
<i>value</i> field was a string, then the value from the file shall be the argument for the <a href=
"../utilities/printf.html"><i>printf</i></a> formatting specification; otherwise, the value from the file shall be the
argument.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_54_14"></a>EXIT STATUS</h4>

<blockquote>
<p>The following exit values shall be returned:</p>

<dl compact>
<dt>&nbsp;0</dt>

<dd>Successful completion.</dd>

<dt>&gt;0</dt>

<dd>An error occurred.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_54_15"></a>CONSEQUENCES OF ERRORS</h4>

<blockquote>
<p>Default.</p>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_04_54_16"></a>APPLICATION USAGE</h4>

<blockquote>
<p>The <i>file</i> 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
<i>tar</i> archive.</p>

<p>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 <tt>"#!"</tt> as executable files, these may be identified as
executable binary files rather than as shell scripts.</p>
</blockquote>

<h4><a name="tag_04_54_17"></a>EXAMPLES</h4>

<blockquote>
<p>Determine whether an argument is a binary executable file:</p>

<pre>
<tt>file "$1" | grep -Fq executable &amp;&amp;
    printf "%s is executable.\n" "$1"
</tt>
</pre>
</blockquote>

<h4><a name="tag_04_54_18"></a>RATIONALE</h4>

<blockquote>
<p>The <b>-f</b> option was omitted because the same effect can (and should) be obtained using the <a href=
"../utilities/xargs.html"><i>xargs</i></a> utility.</p>

<p>Historical versions of the <i>file</i> utility attempt to identify the following types of files: symbolic link, directory,
character special, block special, socket, <i>tar</i> archive, <i>cpio</i> archive, SCCS archive, archive library, empty, <a href=
"../utilities/compress.html"><i>compress</i></a> output, <i>pack</i> output, binary data, C source, FORTRAN source, assembler
source, <i>nroff</i>/ <i>troff</i>/ <i>eqn</i>/ <i>tbl</i> source <i>troff</i> 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.</p>

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

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

<p>The IEEE&nbsp;Std&nbsp;1003.1-2001 description of default system tests and the interaction between the <b>-d</b>, <b>-M</b>, and
<b>-m</b> options did not clearly indicate that there were two types of &quot;default system tests&quot;. The &quot;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 <i>file</i> 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 <b>core</b> file on most implementations, but cannot name the program
file that dropped the core. A magic file could produce output such as:</p>

<pre>
<tt>/home/dwc/core: ELF 32-bit MSB core file SPARC Version 1
</tt>
</pre>

<p>but by building the test into the <i>file</i> utility, you could get output such as:</p>

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

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

<p>The context-sensitive default system tests were always built into the <i>file</i> 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 <b>-m</b> and <b>-M</b> 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 <b>-d</b> option is specified before a
<b>-m</b> option or <b>-M</b> 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 <b>-m</b> or <b>-M</b> option would be
applied to give a more accurate identification.</p>

<p>Leaving the meaning of <b>-M -</b> and <b>-m -</b> unspecified allows an existing prototype of these options to continue to work
in a backwards-compatible manner. (In that implementation, <b>-M -</b> was roughly equivalent to <b>-d</b> in
IEEE&nbsp;Std&nbsp;1003.1-2001.)</p>

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

<p>The historical format of the magic file was the same as that specified by the Rationale in the ISO&nbsp;POSIX-2:1993 standard
for the <i>offset</i>, <i>value</i>, and <i>message</i> 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.</p>

<p>The following is an example magic file:</p>

<pre>
<tt>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
&gt;2 byte&amp;0x80 &gt;0                  Block compressed
&gt;2 byte&amp;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    &lt;ar&gt;                System V Release 1 archive
0  string    !&lt;arch&gt;\n__.SYMDEF  Archive random library
0  string    !&lt;arch&gt;             Archive
0  string    ARF_BEGARF          PHIGS clear text archive
0  long      0x137A2950          Scalable OpenFont binary
0  long      0x137A2951          Encrypted scalable OpenFont binary
</tt>
</pre>

<p>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.</p>
</blockquote>

<h4><a name="tag_04_54_19"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_54_20"></a>SEE ALSO</h4>

<blockquote>
<p><a href="ar.html"><i>ar</i></a> , <a href="ls.html"><i>ls</i></a> , <a href="pax.html"><i>pax</i></a></p>
</blockquote>

<h4><a name="tag_04_54_21"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 4.</p>
</blockquote>

<h4><a name="tag_04_54_22"></a>Issue 6</h4>

<blockquote>
<p>This utility is marked as part of the User Portability Utilities option.</p>

<p>Options and an EXTENDED DESCRIPTION are added as specified in the IEEE&nbsp;P1003.2b draft standard.</p>

<p>IEEE PASC Interpretations 1003.2 #192 and #178 are applied.</p>

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XCU/TC1/D6/25 is applied, making major changes to address ambiguities raised in
defect reports.</p>

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XCU/TC1/D6/26 is applied, making it clear in the OPTIONS section that the
<b>-m</b>, <b>-d</b>, and <b>-M</b> options do not comply with Guideline 11 of the Utility Syntax Guidelines.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>