HEAD(1) General Commands Manual HEAD(1)

head — copy the first part of files

head [-n number] [file ...]

Obsolescent version:

head [-number] [file ...]

The head utility shall copy its input files to the standard output, ending the output for each file at a designated point. Copying shall end at the point in each input file indicated by the −n number option (or the obsolescent version’s −number argument). The option-argument number shall be counted in units of lines.

The head utility shall conform to the utility argument syntax guidelines described in standard described in 2.10.2, except that the obsolescent version accepts multicharacter numeric options. The following option shall be supported by the implementation in the nonobsolescent version:

number

The first number lines of each input file shall be copied to standard output. The number option argument shall be a positive decimal integer. If no options are specified, head shall act as if -n 10 had been specified. In the obsolescent version, the following option shall be supported by the implementation: −number The number argument is a positive decimal integer with the same effect as the −nnumber option in the nonobsolescent version.

The following operand shall be supported by the implementation:

file

A pathname of an input file. If no file operands are specified, the standard input shall be used.

The standard input shall be used only if no file operands are specified. See Input Files.

Input files shall be text files, but the line length shall not be restricted to bytes.

The following environment variables shall affect the execution of head:

This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_ ) do not specify a locale. See 2.6.

This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_.

This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments and input files).

This variable shall determine the language in which messages should be written.

Default.

The standard output shall contain designated portions of the input file(s). If multiple file operands are specified, head shall precede the output for each with the header: "\n==> %s <==\n", <pathname> except that the first header written shall not include the initial <newline>.

Used only for diagnostic messages.

None.

None.

The head utility shall exit with one of the following values:

Successful completion.

An error occurred.

Default.

Usage, Examples

The nonobsolescent version of head was created to allow conformance to the Utility Syntax Guidelines. The −n option was added to this new interface so that head and tail would be more logically related. To write the first ten lines of all files (except those with a leading period) in the directory:

head ∗

The head utility was not in early drafts. It was felt that head, and its frequent companion, tail, were useful mostly to interactive users, and not application programs. However, balloting input suggested that these utilities actually do find significant use in scripts, such as to write out portions of log files. Although it is possible to simulate head with sed 10q for a single file, the working group decided that the popularity of head on historical systems warranted its inclusion alongside tail. An earlier draft had the synopsis line:

head [ −c | −l ] [−n number] [file . . . ] This was changed to the current form based on comments and objections noting that −c has not been provided by historical versions of head and other utilities in . 2 provide similar functionality. Also, −l was changed to −n to match a similar change in tail.

September 1991 posix.fail