freebsd-skq/usr.bin/basename/basename.1

.\" Copyright (c) 1990, 1993, 1994
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the Institute of Electrical and Electronics Engineers, Inc.
.\"
.\" 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.
.\"
.\"     @(#)basename.1	8.2 (Berkeley) 4/18/94
.\" $FreeBSD$
.\"
.Dd May 26, 2020
.Dt BASENAME 1
.Os
.Sh NAME
.Nm basename , dirname
.Nd return filename or directory portion of pathname
.Sh SYNOPSIS
.Nm
.Ar string
.Op Ar suffix
.Nm
.Op Fl a
.Op Fl s Ar suffix
.Ar string
.Op Ar ...
.Nm dirname
.Ar string
.Op Ar ...
.Sh DESCRIPTION
The
.Nm
utility deletes any prefix ending with the last slash
.Ql \&/
character present in
.Ar string
(after first stripping trailing slashes),
and a
.Ar suffix ,
if given.
The
.Ar suffix
is not stripped if it is identical to the remaining characters in
.Ar string .
The resulting filename is written to the standard output.
A non-existent suffix is ignored.
If
.Fl a
is specified, then every argument is treated as a
.Ar string
as if
.Nm
were invoked with just one argument.
If
.Fl s
is specified, then the
.Ar suffix
is taken as its argument, and all other arguments are treated as a
.Ar string .
.Pp
The
.Nm dirname
utility deletes the filename portion, beginning
with the last slash
.Ql \&/
character to the end of
.Ar string
(after first stripping trailing slashes),
and writes the result to the standard output.
.Sh EXIT STATUS
.Ex -std basename dirname
.Sh EXAMPLES
The following line sets the shell variable
.Ev FOO
to
.Pa /usr/bin .
.Pp
.Dl FOO=`dirname /usr/bin/trail`
.Sh SEE ALSO
.Xr csh 1 ,
.Xr sh 1 ,
.Xr basename 3 ,
.Xr dirname 3
.Sh STANDARDS
The
.Nm
and
.Nm dirname
utilities are expected to be
.St -p1003.2
compatible.
.Sh HISTORY
The
.Nm
and
.Nm dirname
utilities first appeared in
.Bx 4.4 .
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.\" Copyright (c) 1990, 1993, 1994`
			`.\" The Regents of the University of California. All rights reserved.`
			`.\"`
			`.\" This code is derived from software contributed to Berkeley by`
			`.\" the Institute of Electrical and Electronics Engineers, Inc.`
			`.\"`
			`.\" 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.`
			`.\"`
			`.\" @(#)basename.1 8.2 (Berkeley) 4/18/94`
$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			`.\"`
Add HISTORY sections to banner(6), basename(1), limits(1) and vmstat(8) Reviewed by: bcr (mentor) Approved by: bcr (mentor) MFC after: 7 days Differential Revision: https://reviews.freebsd.org/D25019 2020-06-18 13:19:56 +00:00			`.Dd May 26, 2020`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.Dt BASENAME 1`
			`.Os`
			`.Sh NAME`
			`.Nm basename , dirname`
			`.Nd return filename or directory portion of pathname`
			`.Sh SYNOPSIS`
mdoc(7) police: use the new features of the Nm macro. 2000-11-20 19:21:22 +00:00			`.Nm`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.Ar string`
			`.Op Ar suffix`
Make it possible to have this (basename(1)) perform basename(3) on multiple files. The traditional behaviour, 'basename string .suffix', is preserved, however a suffix may now also be specified via a getopt(3) option, -s, such that if it is specified in that way, all string arguments follow. There is also a new flag, -a, which allows a user to say "yes, please basename(3) on all arguments". Update manual to reflect this unobtrusively. Reviewed by: obrien 2002-06-30 13:40:35 +00:00			`.Nm`
			`.Op Fl a`
			`.Op Fl s Ar suffix`
			`.Ar string`
			`.Op Ar ...`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.Nm dirname`
			`.Ar string`
Alow dirname(1) to accept multiple arguments in the same way that basename(1) does. (Two different PRs contained identical patches, both cited below) PR: 121520, 86148 Submitted by: Ighighi <ighighi at gmail dot com> Submitted by: Leif Neland <leif at neland dot dk> MFC after: 3 days 2009-02-02 11:19:56 +00:00			`.Op Ar ...`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.Sh DESCRIPTION`
Use `The .Nm utility' 2002-04-19 23:44:58 +00:00			`The`
			`.Nm`
			`utility deletes any prefix ending with the last slash`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.Ql \&/`
			`character present in`
PR: 4866 Submitted by: fenner Make man page reflect reality. 1998-04-14 22:08:48 +00:00			`.Ar string`
			`(after first stripping trailing slashes),`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`and a`
			`.Ar suffix ,`
			`if given.`
PR: 4866 Submitted by: fenner Make man page reflect reality. 1998-04-14 22:08:48 +00:00			`The`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.Ar suffix`
PR: 4866 Submitted by: fenner Make man page reflect reality. 1998-04-14 22:08:48 +00:00			`is not stripped if it is identical to the remaining characters in`
			`.Ar string .`
			`The resulting filename is written to the standard output.`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`A non-existent suffix is ignored.`
Make it possible to have this (basename(1)) perform basename(3) on multiple files. The traditional behaviour, 'basename string .suffix', is preserved, however a suffix may now also be specified via a getopt(3) option, -s, such that if it is specified in that way, all string arguments follow. There is also a new flag, -a, which allows a user to say "yes, please basename(3) on all arguments". Update manual to reflect this unobtrusively. Reviewed by: obrien 2002-06-30 13:40:35 +00:00			`If`
			`.Fl a`
			`is specified, then every argument is treated as a`
			`.Ar string`
			`as if`
			`.Nm`
			`were invoked with just one argument.`
			`If`
			`.Fl s`
			`is specified, then the`
			`.Ar suffix`
			`is taken as its argument, and all other arguments are treated as a`
			`.Ar string .`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.Pp`
Use `The .Nm utility' 2002-04-19 23:44:58 +00:00			`The`
			`.Nm dirname`
			`utility deletes the filename portion, beginning`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`with the last slash`
			`.Ql \&/`
			`character to the end of`
PR: 4866 Submitted by: fenner Make man page reflect reality. 1998-04-14 22:08:48 +00:00			`.Ar string`
Remove whitespace at EOL. 2001-07-15 08:06:20 +00:00			`(after first stripping trailing slashes),`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`and writes the result to the standard output.`
Sort sections. 2005-01-18 13:43:56 +00:00			`.Sh EXIT STATUS`
			`.Ex -std basename dirname`
Remove whitespace at EOL. 2001-07-15 08:06:20 +00:00			`.Sh EXAMPLES`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`The following line sets the shell variable`
			`.Ev FOO`
			`to`
			`.Pa /usr/bin .`
			`.Pp`
			.Dl FOO=`dirname /usr/bin/trail`
			`.Sh SEE ALSO`
add missing comma(s) in .Xr macros 1996-09-23 22:24:39 +00:00			`.Xr csh 1 ,`
Cross-reference basename(3) and dirname(3). 2006-03-16 17:21:52 +00:00			`.Xr sh 1 ,`
			`.Xr basename 3 ,`
			`.Xr dirname 3`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`.Sh STANDARDS`
			`The`
Add DIAGNOSTICS section name 2000-03-26 14:42:14 +00:00			`.Nm`
BSD 4.4 Lite Usr.bin Sources 1994-05-27 12:33:43 +00:00			`and`
			`.Nm dirname`
Use `The .Nm utility' 2002-04-19 23:44:58 +00:00			`utilities are expected to be`
mdoc(7) police: utilize .St macro. 2001-02-26 15:55:52 +00:00			`.St -p1003.2`
			`compatible.`
Add HISTORY sections to banner(6), basename(1), limits(1) and vmstat(8) Reviewed by: bcr (mentor) Approved by: bcr (mentor) MFC after: 7 days Differential Revision: https://reviews.freebsd.org/D25019 2020-06-18 13:19:56 +00:00			`.Sh HISTORY`
			`The`
			`.Nm`
			`and`
			`.Nm dirname`
			`utilities first appeared in`
			`.Bx 4.4 .`