freebsd-dev/usr.bin/look/look.1

.\" Copyright (c) 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)look.1	8.1 (Berkeley) 6/14/93
.\" $FreeBSD$
.\"
.Dd December 29, 2020
.Dt LOOK 1
.Os
.Sh NAME
.Nm look
.Nd display lines beginning with a given string
.Sh SYNOPSIS
.Nm
.Op Fl df
.Op Fl t Ar termchar
.Ar string
.Op Ar
.Sh DESCRIPTION
The
.Nm
utility displays any lines in
.Ar file
which contain
.Ar string
as a prefix.
As
.Nm
performs a binary search, the lines in
.Ar file
must be sorted.
.Pp
If
.Ar file
is not specified, the file
.Pa /usr/share/dict/words
is used, only alphanumeric characters are compared and the case of
alphabetic characters is ignored.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl d , -alphanum
Dictionary character set and order, i.e., only alphanumeric characters
are compared.
.It Fl f , -ignore-case
Ignore the case of alphabetic characters.
.It Fl t , -terminate Ar termchar
Specify a string termination character, i.e., only the characters
in
.Ar string
up to and including the first occurrence of
.Ar termchar
are compared.
.El
.Sh ENVIRONMENT
The
.Ev LANG , LC_ALL
and
.Ev LC_CTYPE
environment variables affect the execution of the
.Nm
utility.
Their effect is described in
.Xr environ 7 .
.Sh FILES
.Bl -tag -width /usr/share/dict/words -compact
.It Pa /usr/share/dict/words
the dictionary
.El
.Sh EXIT STATUS
The
.Nm
utility exits 0 if one or more lines were found and displayed,
1 if no lines were found, and >1 if an error occurred.
.Sh EXAMPLES
Look for lines starting with
.Ql xylene
in the file
.Pa /usr/share/dict/words :
.Bd -literal -offset indent
$ look xylen
xylene
xylenol
xylenyl
.Ed
.Pp
Same as above, but do not consider any characters in
.Ar string
beyond the first
.Ql e .
Note that
.Fl f
is implicit since we are searching the default file
.Pa /usr/share/dict/words :
.Bd -literal -offset indent
$ look -t e xylen
Xyleborus
xylem
xylene
xylenol
xylenyl
xyletic
.Ed
.Sh COMPATIBILITY
The original manual page stated that tabs and blank characters participated
in comparisons when the
.Fl d
option was specified.
This was incorrect and the current man page matches the historic
implementation.
.Pp
The
.Fl a
and
.Fl -alternative
flags are ignored for compatibility.
.Sh SEE ALSO
.Xr grep 1 ,
.Xr sort 1
.Sh HISTORY
A
.Nm
utility appeared in
.At v7 .
.Sh BUGS
Lines are not compared according to the current locale's collating
order.
Input files must be sorted with
.Ev LC_COLLATE
set to
.Ql C .
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.\" Copyright (c) 1990, 1993`
			`.\" The Regents of the University of California. All rights reserved.`
			`.\"`
			`.\" Redistribution and use in source and binary forms, with or without`
			`.\" modification, are permitted provided that the following conditions`
			`.\" are met:`
			`.\" 1. Redistributions of source code must retain the above copyright`
			`.\" notice, this list of conditions and the following disclaimer.`
			`.\" 2. Redistributions in binary form must reproduce the above copyright`
			`.\" notice, this list of conditions and the following disclaimer in the`
			`.\" documentation and/or other materials provided with the distribution.`
Renumber copyright clause 4 Renumber cluase 4 to 3, per what everybody else did when BSD granted them permission to remove clause 3. My insistance on keeping the same numbering for legal reasons is too pedantic, so give up on that point. Submitted by: Jan Schaumann <jschauma@stevens.edu> Pull Request: https://github.com/freebsd/freebsd/pull/96 2017-02-28 23:42:47 +00:00			`.\" 3. Neither the name of the University nor the names of its contributors`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.\" may be used to endorse or promote products derived from this software`
			`.\" without specific prior written permission.`
			`.\"`
			.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
			`.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE`
			`.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE`
			`.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE`
			`.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL`
			`.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS`
			`.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)`
			`.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT`
			`.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY`
			`.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF`
			`.\" SUCH DAMAGE.`
			`.\"`
			`.\" @(#)look.1 8.1 (Berkeley) 6/14/93`
$Id$ -> $FreeBSD$ 1999-08-28 01:08:13 +00:00			`.\" $FreeBSD$`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.\"`
look(1): Add EXAMPLES section Add two simple examples. In this case I opted to show a small portion of the output since it helps to understand what the tool does. It shows the use of the -t flag too. PR: Submitted by: Reported by: Reviewed by: gbe@ Approved by: manpages (bcr@) Obtained from: MFC after: MFH: Relnotes: Security: Sponsored by: Differential Revision: https://reviews.freebsd.org/D27543 2020-12-29 20:48:12 +00:00			`.Dd December 29, 2020`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.Dt LOOK 1`
			`.Os`
			`.Sh NAME`
			`.Nm look`
			`.Nd display lines beginning with a given string`
			`.Sh SYNOPSIS`
Use err(3) instead of local redefinition. 1997-07-23 06:46:10 +00:00			`.Nm`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.Op Fl df`
			`.Op Fl t Ar termchar`
			`.Ar string`
mdoc(7) police: use the default ``file ...'' feature of the .Ar macro. 2001-02-13 09:56:35 +00:00			`.Op Ar`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.Sh DESCRIPTION`
Remove whitespace at EOL. 2001-07-15 08:06:20 +00:00			`The`
Use err(3) instead of local redefinition. 1997-07-23 06:46:10 +00:00			`.Nm`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`utility displays any lines in`
			`.Ar file`
			`which contain`
			`.Ar string`
			`as a prefix.`
			`As`
Use err(3) instead of local redefinition. 1997-07-23 06:46:10 +00:00			`.Nm`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`performs a binary search, the lines in`
			`.Ar file`
			`must be sorted.`
			`.Pp`
			`If`
			`.Ar file`
			`is not specified, the file`
			`.Pa /usr/share/dict/words`
			`is used, only alphanumeric characters are compared and the case of`
			`alphabetic characters is ignored.`
			`.Pp`
Introduce options definition the standard way. 2003-06-09 19:32:02 +00:00			`The following options are available:`
			`.Bl -tag -width indent`
look: implement long options gentoo has "util-linux 2.24.1" with long options. Other distributions have similar. usage() is intentionally unchanged to keep it short and sweet Reviewed by: jmg Discussed with: adrian, jilles 2014-07-04 04:47:29 +00:00			`.It Fl d , -alphanum`
Mechanically kill hard sentence breaks. 2004-07-02 22:22:35 +00:00			`Dictionary character set and order, i.e., only alphanumeric characters`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`are compared.`
look: implement long options gentoo has "util-linux 2.24.1" with long options. Other distributions have similar. usage() is intentionally unchanged to keep it short and sweet Reviewed by: jmg Discussed with: adrian, jilles 2014-07-04 04:47:29 +00:00			`.It Fl f , -ignore-case`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`Ignore the case of alphabetic characters.`
look: implement long options gentoo has "util-linux 2.24.1" with long options. Other distributions have similar. usage() is intentionally unchanged to keep it short and sweet Reviewed by: jmg Discussed with: adrian, jilles 2014-07-04 04:47:29 +00:00			`.It Fl t , -terminate Ar termchar`
Mechanically kill hard sentence breaks. 2004-07-02 22:22:35 +00:00			`Specify a string termination character, i.e., only the characters`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`in`
			`.Ar string`
			`up to and including the first occurrence of`
			`.Ar termchar`
			`are compared.`
			`.El`
Move exit status information into a DIAGNOSTICS section. Add an ENVIRONMENT section. Re-add a sentence from the BUGS section that went missing in the previous commit. 2004-07-19 11:18:56 +00:00			`.Sh ENVIRONMENT`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`The`
Move exit status information into a DIAGNOSTICS section. Add an ENVIRONMENT section. Re-add a sentence from the BUGS section that went missing in the previous commit. 2004-07-19 11:18:56 +00:00			`.Ev LANG , LC_ALL`
			`and`
			`.Ev LC_CTYPE`
			`environment variables affect the execution of the`
Use err(3) instead of local redefinition. 1997-07-23 06:46:10 +00:00			`.Nm`
Move exit status information into a DIAGNOSTICS section. Add an ENVIRONMENT section. Re-add a sentence from the BUGS section that went missing in the previous commit. 2004-07-19 11:18:56 +00:00			`utility.`
			`Their effect is described in`
			`.Xr environ 7 .`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.Sh FILES`
			`.Bl -tag -width /usr/share/dict/words -compact`
			`.It Pa /usr/share/dict/words`
			`the dictionary`
			`.El`
Added the EXIT STATUS section where appropriate. 2005-01-17 07:44:44 +00:00			`.Sh EXIT STATUS`
Move exit status information into a DIAGNOSTICS section. Add an ENVIRONMENT section. Re-add a sentence from the BUGS section that went missing in the previous commit. 2004-07-19 11:18:56 +00:00			`The`
			`.Nm`
			`utility exits 0 if one or more lines were found and displayed,`
			`1 if no lines were found, and >1 if an error occurred.`
look(1): Add EXAMPLES section Add two simple examples. In this case I opted to show a small portion of the output since it helps to understand what the tool does. It shows the use of the -t flag too. PR: Submitted by: Reported by: Reviewed by: gbe@ Approved by: manpages (bcr@) Obtained from: MFC after: MFH: Relnotes: Security: Sponsored by: Differential Revision: https://reviews.freebsd.org/D27543 2020-12-29 20:48:12 +00:00			`.Sh EXAMPLES`
			`Look for lines starting with`
			`.Ql xylene`
			`in the file`
			`.Pa /usr/share/dict/words :`
			`.Bd -literal -offset indent`
			`$ look xylen`
			`xylene`
			`xylenol`
			`xylenyl`
			`.Ed`
			`.Pp`
			`Same as above, but do not consider any characters in`
			`.Ar string`
			`beyond the first`
			`.Ql e .`
			`Note that`
			`.Fl f`
			`is implicit since we are searching the default file`
			`.Pa /usr/share/dict/words :`
			`.Bd -literal -offset indent`
			`$ look -t e xylen`
			`Xyleborus`
			`xylem`
			`xylene`
			`xylenol`
			`xylenyl`
			`xyletic`
			`.Ed`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.Sh COMPATIBILITY`
			`The original manual page stated that tabs and blank characters participated`
			`in comparisons when the`
			`.Fl d`
			`option was specified.`
			`This was incorrect and the current man page matches the historic`
			`implementation.`
look(1): add compability with other implementations. On other implementations 'look -a' uses an alternate dictionary. Since we don't have one, just ignore it. 2014-05-11 02:00:48 +00:00			`.Pp`
			`The`
			`.Fl a`
look: implement long options gentoo has "util-linux 2.24.1" with long options. Other distributions have similar. usage() is intentionally unchanged to keep it short and sweet Reviewed by: jmg Discussed with: adrian, jilles 2014-07-04 04:47:29 +00:00			`and`
			`.Fl -alternative`
Fix a ton of speelling errors arc lint is helpful Reviewed By: allanjude, wblock, #manpages, chris@bsdjunk.com Differential Revision: https://reviews.freebsd.org/D3337 2015-10-21 05:37:09 +00:00			`flags are ignored for compatibility.`
Sort sections. 2004-07-19 11:21:34 +00:00			`.Sh SEE ALSO`
			`.Xr grep 1 ,`
			`.Xr sort 1`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.Sh HISTORY`
Use `The .Nm utility' 2002-04-20 12:18:28 +00:00			`A`
			`.Nm`
			`utility appeared in`
Use the .At macro where appropriate. 1996-08-23 01:06:24 +00:00			`.At v7 .`
Document incorrect handling of multibyte characters. 2004-07-17 04:04:30 +00:00			`.Sh BUGS`
Move exit status information into a DIAGNOSTICS section. Add an ENVIRONMENT section. Re-add a sentence from the BUGS section that went missing in the previous commit. 2004-07-19 11:18:56 +00:00			`Lines are not compared according to the current locale's collating`
			`order.`
Point out in the BUGS section that look expects input files to have been sorted with LC_COLLATE=C. 2004-07-19 10:03:38 +00:00			`Input files must be sorted with`
			`.Ev LC_COLLATE`
			`set to`
			`.Ql C .`