usr.bin/head/head.1

   1 .\" Copyright (c) 1980, 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)head.1      8.1 (Berkeley) 6/6/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd June 12, 2022
  32 .Dt HEAD 1
  33 .Os
  34 .Sh NAME
  35 .Nm head
  36 .Nd display first lines of a file
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl qv
  40 .Op Fl n Ar count | Fl c Ar bytes
  41 .Op Ar
  42 .Sh DESCRIPTION
  43 This filter displays the first
  44 .Ar count
  45 lines or
  46 .Ar bytes
  47 of each of the specified files, or of the standard input if no
  48 files are specified.
  49 If
  50 .Ar count
  51 is omitted it defaults to 10.
  52 .Pp
  53 The following options are available:
  54 .Bl -tag -width indent
  55 .It Fl c Ar bytes , Fl -bytes Ns = Ns Ar bytes
  56 Print
  57 .Ar bytes
  58 of each of the specified files.
  59 .It Fl n Ar count , Fl -lines Ns = Ns Ar count
  60 Print
  61 .Ar count
  62 lines of each of the specified files.
  63 .Pp
  64 Both
  65 .Ar count
  66 and
  67 .Ar bytes
  68 may also be specified with size suffixes supported by
  69 .Xr expand_number 3 .
  70 .It Fl q , Fl -quiet , Fl -silent
  71 Suppresses printing of headers when multiple files are being examined.
  72 .It Fl v , Fl -verbose
  73 Prepend each file with a header.
  74 .El
  75 .Pp
  76 If more than a single file is specified, or if the
  77 .Fl v
  78 option is used, each file is preceded by a
  79 header consisting of the string
  80 .Dq ==> XXX <==
  81 where
  82 .Dq XXX
  83 is the name of the file.
  84 The
  85 .Fl q
  86 flag disables the printing of the header in all cases.
  87 .Sh EXIT STATUS
  88 .Ex -std
  89 .Sh EXAMPLES
  90 To display the first 500 lines of the file
  91 .Ar foo :
  92 .Pp
  93 .Dl $ head -n 500 foo
  94 .Pp
  95 .Nm
  96 can be used in conjunction with
  97 .Xr tail 1
  98 in the following way to, for example, display only line 500 from the file
  99 .Ar foo :
 100 .Pp
 101 .Dl $ head -n 500 foo | tail -n 1
 102 .Sh SEE ALSO
 103 .Xr tail 1 ,
 104 .Xr expand_number 3
 105 .Sh HISTORY
 106 The
 107 .Nm
 108 command appeared in PWB UNIX.