1HEAD(P)                    POSIX Programmer's Manual                   HEAD(P)
2
3
4

NAME

6       head - copy the first part of files
7

SYNOPSIS

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

DESCRIPTION

12       The  head  utility  shall  copy its input files to the standard output,
13       ending the output for each file at a designated point.
14
15       Copying shall end at the point in each input file indicated by  the  -n
16       number  option. The option-argument number shall be counted in units of
17       lines.
18

OPTIONS

20       The head utility shall  conform  to  the  Base  Definitions  volume  of
21       IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
22
23       The following option shall be supported:
24
25       -n  number
26              The  first  number  lines  of each input file shall be copied to
27              standard output. The application shall ensure  that  the  number
28              option-argument is a positive decimal integer.
29
30
31       When  a  file  contains  less  than number lines, it shall be copied to
32       standard output in its entirety. This shall not be an error.
33
34       If no options are specified, head shall act as if -n 10 had been speci‐
35       fied.
36

OPERANDS

38       The following operand shall be supported:
39
40       file   A  pathname of an input file. If no file operands are specified,
41              the standard input shall be used.
42
43

STDIN

45       The standard input shall be used only if no file  operands  are  speci‐
46       fied. See the INPUT FILES section.
47

INPUT FILES

49       Input  files shall be text files, but the line length is not restricted
50       to {LINE_MAX} bytes.
51

ENVIRONMENT VARIABLES

53       The following environment variables shall affect the execution of head:
54
55       LANG   Provide a default value for the  internationalization  variables
56              that  are  unset  or  null.  (See the Base Definitions volume of
57              IEEE Std 1003.1-2001, Section  8.2,  Internationalization  Vari‐
58              ables  for the precedence of internationalization variables used
59              to determine the values of locale categories.)
60
61       LC_ALL If set to a non-empty string value, override the values  of  all
62              the other internationalization variables.
63
64       LC_CTYPE
65              Determine  the  locale  for  the  interpretation of sequences of
66              bytes of text data as characters (for  example,  single-byte  as
67              opposed to multi-byte characters in arguments and input files).
68
69       LC_MESSAGES
70              Determine  the  locale  that should be used to affect the format
71              and contents of diagnostic messages written to standard error.
72
73       NLSPATH
74              Determine the location of message catalogs for the processing of
75              LC_MESSAGES .
76
77

ASYNCHRONOUS EVENTS

79       Default.
80

STDOUT

82       The  standard  output  shall  contain  designated portions of the input
83       files.
84
85       If multiple file operands are specified, head shall precede the  output
86       for each with the header:
87
88
89              "\n==> %s <==\n", <pathname>
90
91       except  that  the  first  header  written shall not include the initial
92       <newline>.
93

STDERR

95       The standard error shall be used only for diagnostic messages.
96

OUTPUT FILES

98       None.
99

EXTENDED DESCRIPTION

101       None.
102

EXIT STATUS

104       The following exit values shall be returned:
105
106        0     Successful completion.
107
108       >0     An error occurred.
109
110

CONSEQUENCES OF ERRORS

112       Default.
113
114       The following sections are informative.
115

APPLICATION USAGE

117       The obsolescent - number form is withdrawn in this  version.   Applica‐
118       tions should use the -n number option.
119

EXAMPLES

121       To  write the first ten lines of all files (except those with a leading
122       period) in the directory:
123
124
125              head *
126

RATIONALE

128       Although it is possible to simulate head with  sed  10q  for  a  single
129       file,  the  standard  developers decided that the popularity of head on
130       historical BSD systems warranted its inclusion alongside tail.
131
132       This standard version of head follows the  Utility  Syntax  Guidelines.
133       The  -n  option  was  added to this new interface so that head and tail
134       would be more logically related.
135
136       There is no -c option (as there is in tail) because it is not  histori‐
137       cal   practice   and   because   other  utilities  in  this  volume  of
138       IEEE Std 1003.1-2001 provide similar functionality.
139

FUTURE DIRECTIONS

141       None.
142

SEE ALSO

144       sed , tail
145

COPYRIGHT

147       Portions of this text are reprinted and reproduced in  electronic  form
148       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
149       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
150       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
151       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
152       event of any discrepancy between this version and the original IEEE and
153       The Open Group Standard, the original IEEE and The Open Group  Standard
154       is  the  referee document. The original Standard can be obtained online
155       at http://www.opengroup.org/unix/online.html .
156
157
158
159IEEE/The Open Group                  2003                              HEAD(P)