head — Display the first part of a file

Format

head [–B] [-W option[,option]...] [–b|–c|–k|–l|–m|–n num] [file …file …]
head [–B] [-W option[,option]...] [–num] [file …file …]

Description

By default, head displays the first 10 lines of each file given on the command line. If you do not specify file, head reads standard input (stdin).

Options

–B

Disables the automatic conversion of tagged files. This option is ignored if the filecodeset or pgmcodeset options (-W option) are specified.

–b num

Displays the first num blocks (a block is 512 bytes) of each file.

–c num

Displays the first num bytes of each file.

–k num

Displays the first num kilobytes (1024 bytes) of each file.

–l num

Displays the first num lines of each file.

–m num

Displays the first num megabytes of each file.

–n num

Displays the first num lines of each file.

–num

Displays the first num lines of each file.

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

Restriction: The only supported values for pgmcodeset are IBM-1047 and 1047.

Examples

To display the first 10 lines of a text file to the standard output (stdout):
```
head myTextFile
```
To display the first 400 bytes of a text file to the standard output (stdout):
```
head -c 400 myTextFile
```
To display the first 50 lines of a text file containing UTF-8 characters to the standard output (stdout), 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 displaying an untagged public text file or a read-only text file):
```
head -n 50 -W filecodeset=UTF-8,pgmcodeset=IBM-1047 myUtf8File
```
To display the first 10 lines of two text files containing EBCDIC characters to the standard output (stdout), assuming that automatic conversion has been enabled but the text files are incorrectly tagged as ASCII:
```
head -B myMisTaggedFile01 myMisTaggedFile02
```

Localization

head uses the following localization environment variables:

LANG
LC_ALL
LC_CTYPE
LC_MESSAGES
NLSPATH

See Localization for more information.

Environment variables

head uses the following environment variable:

_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.

Exit values

0

Successful completion

1

Failure due to any of the following:

Inability to open an input file
Read error on standard input (stdin)
Write error on standard output (stdout)
The code set is not valid
Could not turn off automatic conversion
Could not perform requested text conversion

2

Failure due to any of the following:

Unknown command-line option
Missing or incorrect num in an –n option

Messages

Possible error messages include:

Badly formed line or character count num: The value num, following a –b, –c, –k, –l, –m, or –n option, was not a valid number.

Portability

POSIX.2, X/Open Portability Guide.

This program originated with Berkeley Software Distribution (BSD) and is a frequent add-on to UNIX systems.

The POSIX standard included only the –n num and –num options, though it considers the latter obsolete.

Related information

cat, sed, tail