diff options
Diffstat (limited to 'man1p/file.1p')
| -rw-r--r-- | man1p/file.1p | 786 |
1 files changed, 786 insertions, 0 deletions
diff --git a/man1p/file.1p b/man1p/file.1p new file mode 100644 index 000000000..4a33fab19 --- /dev/null +++ b/man1p/file.1p @@ -0,0 +1,786 @@ +.\" 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 . |