Format
file [–BcdEh]
[–f filelist]
[-M magic] [–m magic] [-W option[,option]...] file …file …
file -i [-h]
[–f filelist] file …file …
Description
file determines
the format of each file by inspecting the
attributes and (for a regular file) reading the contents of the file.
If the file is an executable, its addressing
mode is determined for output. If file is
not an executable, file compares each file to
entries found in one or more magic files
to determine their file type. If you specify - as a file name, file reads
from the standard input (stdin).
file then
divides files that do not match a template in the magic file
into text files and binary data. Then, by reading
the text files and making an informed guess based on the contents, file further
divides text files into various types such as C programs, assembler
programs, files of commands to the shell, and yacc or lex programs.
file displays
the name of each file along with the file type.
- If the variable _UNIX03=YES is set, a space is used to separate
the file name and the type.
- If the variable _UNIX03 is unset or is not set to YES, a tab is
used to separate the file name and the file type.
The
file utility
uses three types of tests to determine the file type: the file attribute
tests, the position-sensitive tests and the context-sensitive tests.
- The "file attribute tests" determine file types such as directory,
character special, FIFO, socket, symbolic link, and external link.
- The "position-sensitive tests" determine file types by looking
for certain string or binary values at specific offsets in the file
being examined. The "default position-sensitive tests" are defined
by:
- The/etc/magic file
- The AMODE test built into the file
utility
If a magic file test succeeds, the message field of the line
will be printed and no further tests will be applied, except for tests
on immediately following lines beginning with a single '>' character.
- The "default context-sensitive tests" are built into the file utility.
These tests look for language constructs in text files trying to identify
shell scripts, C, FORTRAN, and other computer language source files,
and even plain text files. The "default context-sensitive tests" will
never be applied before any "position-sensitive tests" even if the -d option
is specified before an -m magic option or -M
magic option.
Options
- –B
- Disables the automatic conversion of tagged files. This option
is ignored if the filecodeset or pgmcodeset options
(-W option) are specified.
- –c
- Only checks the file magic (specified
by -m or -M) and /etc/magic.
If the semantics imply it, see the usage notes for the validity of
the format.
- -d
- Apply any default position-sensitive tests and default context-sensitive
tests to the file. This option is the default if no -M or -m option
is specified. See the usage notes for more information.
- -E
- Uses the magic file and bypasses the
checking of regular files for executables.
- –f filelist
- Examines the files listed in the file filelist.
- -h
- When a symbolic link is encountered, identify file as
a symbolic link instead of following the link.
If
-h is
not specified and
- file is an external link or file is
a symbolic link referring to a nonexistent file:
- If the variable _UNIX03=YES is set
- The type will be reported as if -h was
specified.
- If the variable _UNIX03 is unset or is not set to YES
- The type will be reported as if -h was
not specified.
- -i
- If file is a regular file, does not
attempt to classify the type of the file further. This option can
only be used with -h and -f options.
"Usage Note" for the file types that file command
does not attempt to classify.
- –M magic
- Uses the file magic to classify the
file type. No default position-sensitive tests, default context-sensitive
tests, nor AMODE tests shall be applied, unless the -d option
is also specified. See the usage notes for more information.
- –m magic
- Alters the classification of regular files when examining the
file content.
- If the variable _UNIX03=YES is set
- Then file attempts to classify the file
type using the following tests, in order:
- Using the file magic.
- Using the default position-sensitive tests (/etc/magic ).
- Using the default context-sensitive tests built into the file command.
- If the variable _UNIX03 is unset or is not set to YES
- Then file attempts to classify the file
type using the following tests, in order:
- Using the file magic rather than /etc/magic.
- Using the default context-sensitive built into the file command.
- -W option[,option]...
- Specifies z/OS-specific options. The option keywords are case-sensitive. Possible
options are:
- filecodeset=codeset
- Performs text conversion from one code set to another when reading
from the file. The coded character set of the file is codeset. codeset can
be a code set name known to the system or a numeric coded character
set identifier (CCSID). Note that the command iconv -l lists
existing CCSIDs along with their corresponding code set names. The filecodeset and pgmcodeset options
can be used on files with any file tag.
If pgmcodeset is
specified but filecodeset is omitted, then
the default file code set is ISO8859-1 even if the file is tagged
with a different code set. If neither filecodeset nor pgmcodeset is
specified, text conversion will not occur unless automatic conversion
is enabled or the _TEXT_CONV environment variable indicates text conversion.
For more information about text conversion, see Controlling text conversion for z/OS UNIX shell commands.
If filecodeset or pgmcodeset is
specified, then automatic conversion is disabled for this command
invocation and the -B option is ignored
if it is also specified. See z/OS UNIX System Services Planning for
more information about automatic conversion.
When
specifying values for filecodeset, use the
values that Unicode Service supports. For more information about supported
code sets, see z/OS Unicode Services User's Guide and Reference.
- pgmcodeset=codeset
- Performs text conversion from one code set to another when reading
from the file. The coded character set of the program (command) is codeset. codeset can
be a code set name known to the system or a numeric coded character
set identifier (CCSID). Note that the command iconv -l lists
existing CCSIDs along with their corresponding code set names. The filecodeset and pgmcodeset options
can be used on files with any file tag.
If filecodeset is
specified but pgmcodeset is omitted, then
the default program code set is IBM-1047. If neither filecodeset nor pgmcodeset is
specified, text conversion will not occur unless automatic conversion
is enabled or the _TEXT_CONV environment variable indicates text conversion.
For more information about text conversion, see Controlling text conversion for z/OS UNIX shell commands.
If filecodeset or pgmcodeset is
specified, then automatic conversion is disabled for this command
invocation and the -B option is ignored
if it is also specified. See z/OS UNIX System Services Planning for
more information about automatic conversion.
Restriction: The
only supported values for pgmcodeset are
IBM-1047 and 1047.
Examples
- To display the type of a file:
file myFile
- To display the type of a file, without attempting to classify
regular files:
file -i myFile
- To display the type of a text file containing UTF-8 characters,
assuming that:
- The text file is untagged and you do not want to tag it or enable
automatic conversion, and
- You cannot alter the tag (for example, you are checking an untagged
public text file or a read-only text file)
file -W filecodeset=UTF-8,pgmcodeset=IBM-1047 myUtf8File
- To display the type of a text file containing EBCDIC characters,
assuming that automatic conversion has been enabled but the text file
is incorrectly tagged as ASCII:
file -B myMisTaggedFile
Localization
file uses
the following localization environment variables:
- LANG
- LC_ALL
- LC_MESSAGES
- LC_SYNTAX
- NLSPATH
See Localization for more
information.
Environment variables
file uses
the following environment variables:
- _UNIX03
- See Shell commands changed for UNIX03 for more information about
the effect of the _UNIX03 environment variable on this command.
- _TEXT_CONV
- Contains text conversion information for the command. The text
conversion information is not used when either the -B option
or the filecodeset or pgmcodeset option
(-W option) is specified. For more information
about text conversion, see Controlling text conversion for z/OS UNIX shell commands.
Usage notes
- LC_SYNTAX only affects the interpretation of the input file that
did not match any magic file template. It
does not affect the interpretation of the magic file.
Because
of this, an input file that contains characters from a code page other
than IBM-1047 cannot match the magic file,
which contains IBM-1047 characters. If you need to match character
in different code pages, you can use the -m or -M option
to specify a magic file created with the desired code page.
- The tests applying to a file when running the command follow the
rules outlined in Table 1.
Table 1. Rules for testing filesIf the following options are specified... |
Then the position-sensitive tests are applied
in the following sequence... |
Default context-sensitive tests applied? |
None |
AMODE > /etc/magic |
Yes |
-d |
AMODE > /etc/magic |
Yes |
-M MAGIC |
MAGIC |
No |
-m magic |
- If the variable _UNIX03=YES is set,
- magic > AMODE > /etc/magic
- If the variable _UNIX03 is unset or
is not set to YES,
|
Yes |
-d -M MAGIC |
AMODE > /etc/magic > MAGIC |
Yes |
-M MAGIC -d |
MAGIC > AMODE > /etc/magic |
Yes |
-d -m magic |
AMODE > /etc/magic > magic |
Yes |
-m magic -d |
magic > AMODE > /etc/magic |
Yes |
-M MAGIC -m magic |
MAGIC > magic |
No |
-m magic -M MAGIC |
magic > MAGIC |
No |
-d -M MAGIC -m magic |
AMODE > /etc/magic > MAGIC > magic |
Yes |
-d -m magic -M MAGIC |
AMODE > /etc/magic > magic > MAGIC |
Yes |
-M MAGIC -d -m magic |
MAGIC > AMODE > /etc/magic > magic |
Yes |
-M MAGIC -m magic -d |
MAGIC > magic > AMODE > /etc/magic |
Yes |
-m magic -d -M MAGIC |
magic > AMODE > /etc/magic > MAGIC |
Yes |
-m magic -M MAGIC -d |
magic > MAGIC > AMODE > /etc/magic |
Yes |
Note: - The first column specifies the appearance of the -d, -M and -m
options in the command line.
- The second column gives what position-sensitive tests are applied
and in what sequence, given the options specified in the first column:
- AMODE is a default position-sensitive system test which is only
used on an executable file to determine the addressing mode.
- "/etc/magic" means the default position-sensitive tests in /etc/magic.
- "MAGIC" means the position-sensitive tests in the magic file specified
by "-M".
- "magic" means the position-sensitive tests in the magic file specified
by "-m".
- Tests not appearing in the cell are not applied.
- The third column gives whether the default context-sensitive tests
(built into the file command) are applied, given the options specified
in the first column.
- If -d option is specified together with -E option,
the AMODE tests will not be applied. If -M magic option
is specified alone, the AMODE tests will not be applied.
- The standard output messages of the file utility
will contain the specified strings, but not limited to, listed in Table 2.
Table 2. Output messages
of the file utilityIf file is: |
Will contain the string: |
See note |
Nonexistent |
Cannot open |
None |
Block special |
Block special |
a |
Character special |
Character special |
a |
Directory |
Directory |
a |
FIFO |
Fifo |
a |
Socket |
Socket |
a |
Symbolic link |
Symbolic link to |
a |
External symbolic link |
External link to |
a |
Regular file |
Regular file |
a,b |
Empty regular file |
Empty |
c |
Regular file that cannot be read |
Cannot open |
c |
Executable binary |
Executable |
d,f |
ar archive library (see ar ) |
Archive |
d,f |
Extended cpio format (see pax) |
cpio archive |
d,f |
Extended tar format (ustar in pax) |
tar archive |
d,f |
Shell script |
Commands text |
e,f |
C-language source |
C program text |
e,f |
FORTRAN source |
Fortran program text |
e,f |
Regular file whose type cannot be determined |
Data |
None |
Note: - This is a file attribute test.
- This test is applied only if the -i option
is specified.
- This test is applied only if the -i option
is not specified.
- This is a default position-sensitive test.
- This is a default context-sensitive test.
- Default position-sensitive tests and default context-sensitive
tests are not applied if the -M magic option
is specified unless the -d option is also
specified.
Exit values
- 0
- Successful completion
- 1
- Failure due to any of the following:
- A missing filelist after –f
- More than one –f option on the command
line
- Cannot find the magic file
- Incorrect command-line option
- Too few command-line arguments
- Cannot access a specified file
- Cannot open filelist
- Cannot open the magic file
- A format error in the magic file
- Out of memory for reading or magic entries
- A bad number in the magic file
- A misplaced > in the magic file.
- The code set is not valid
- Could not turn off automatic conversion
- Could not perform requested text conversion
Portability
POSIX.2 User Portability Extension, X/Open
Portability Guide, UNIX systems.
All
options are extensions of the POSIX standard.
The –B and -W options
are extensions of the POSIX standard.