d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ccac2ba7ec
freebsd-dev/lib/libc/gen/basename.3

89 lines
2.2 KiB
Groff
Raw Normal View History

Sync with OpenBSD, primarily make the code easier to read, and a license change to standard OpenBSD ISC license. Obtained from: OpenBSD MFC after: 2 weeks
2011-06-18 00:33:34 +00:00
.\" $OpenBSD: basename.3,v 1.20 2007/05/31 19:19:28 jmc Exp $
Import XPG4-compliant basename(3) and dirname(3) from OpenBSD. The man pages need some adjustments. PR: 12960, 12962 Submitted by: James Howard <howardjp@wam.umd.edu> Obtained from: OpenBSD
2000-08-31 15:56:15 +00:00
.\"
.\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com>
.\"
Sync with OpenBSD, primarily make the code easier to read, and a license change to standard OpenBSD ISC license. Obtained from: OpenBSD MFC after: 2 weeks
2011-06-18 00:33:34 +00:00
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
Import XPG4-compliant basename(3) and dirname(3) from OpenBSD. The man pages need some adjustments. PR: 12960, 12962 Submitted by: James Howard <howardjp@wam.umd.edu> Obtained from: OpenBSD
2000-08-31 15:56:15 +00:00
.\"
Sync with OpenBSD, primarily make the code easier to read, and a license change to standard OpenBSD ISC license. Obtained from: OpenBSD MFC after: 2 weeks
2011-06-18 00:33:34 +00:00
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
Import XPG4-compliant basename(3) and dirname(3) from OpenBSD. The man pages need some adjustments. PR: 12960, 12962 Submitted by: James Howard <howardjp@wam.umd.edu> Obtained from: OpenBSD
2000-08-31 15:56:15 +00:00
.\"
.\" $FreeBSD$
.\"
Replace basename(3) by a thread-safe implementation. Now that the changes to the dirname(3) function had some time to settle, let's go ahead and use the same approach for replacing basename(3) by a simple implementation that modifies the input string, thereby making it thread-safe and guaranteed to succeed. Unlike dirname(3), this function already had a thread-safe variant basename_r(3). This function had its own set of problems, like having an upper bound on the pathname length. Keep this function around for compatibility, but remove most references from the man page. Make the man page more similar to that of dirname(3). As the basename_r(3) function is only provided by FreeBSD (and Bionic), depending on its use is even more implementation defined than assuming that basename(3) is thread-safe. Reviewed by: emaste Differential Revision: https://reviews.freebsd.org/D8382
2016-11-03 20:21:34 +00:00
.Dd October 29, 2016
Import XPG4-compliant basename(3) and dirname(3) from OpenBSD. The man pages need some adjustments. PR: 12960, 12962 Submitted by: James Howard <howardjp@wam.umd.edu> Obtained from: OpenBSD
2000-08-31 15:56:15 +00:00
.Dt BASENAME 3
.Os
.Sh NAME
.Nm basename
.Nd extract the base portion of a pathname
.Sh SYNOPSIS
mdoc(7) police: Use the new .In macro for #include statements.
2001-10-01 16:09:29 +00:00
.In libgen.h
Import XPG4-compliant basename(3) and dirname(3) from OpenBSD. The man pages need some adjustments. PR: 12960, 12962 Submitted by: James Howard <howardjp@wam.umd.edu> Obtained from: OpenBSD
2000-08-31 15:56:15 +00:00
.Ft char *
Fix up prototypes of basename(3) and dirname(3) to comply to POSIX. POSIX allows these functions to be implemented in a way that the resulting string is stored in the input buffer. Though some may find this annoying, this has the advantage that it makes it possible to implement this function in a thread-safe way. It also means that they can be implemented in a way that they work for paths of arbitrary length, as the output string of these functions is never longer than max(1, len(input)). Portable code already needs to be written with this in mind, so in my opinion it makes very little sense to allow the existing behaviour. Prevent the base system from falling back to this by switching over to POSIX prototypes. I'm not going to bump the __FreeBSD_version for this. The reason is that it's possible to account for this change in a portable way, without depending on a specific version of FreeBSD. An exp-run was done some time ago. As far as I know, all regressions as a result of this have already been fixed. I'll give this change some time to settle. In the long run I want to replace our copies by ones that are thread-safe and don't depend on PATH_MAX/MAXPATHLEN.
2016-07-28 16:20:27 +00:00
.Fn basename "char *path"
Import XPG4-compliant basename(3) and dirname(3) from OpenBSD. The man pages need some adjustments. PR: 12960, 12962 Submitted by: James Howard <howardjp@wam.umd.edu> Obtained from: OpenBSD
2000-08-31 15:56:15 +00:00
.Sh DESCRIPTION
The
.Fn basename
Sync with OpenBSD, primarily make the code easier to read, and a license change to standard OpenBSD ISC license. Obtained from: OpenBSD MFC after: 2 weeks
2011-06-18 00:33:34 +00:00
function returns the last component from the pathname pointed to by
mdoc(7) police: Fixed abuses of the .Ar and .Em macros.
2002-12-18 13:33:04 +00:00
.Fa path ,
Import XPG4-compliant basename(3) and dirname(3) from OpenBSD. The man pages need some adjustments. PR: 12960, 12962 Submitted by: James Howard <howardjp@wam.umd.edu> Obtained from: OpenBSD
2000-08-31 15:56:15 +00:00
deleting any trailing
.Sq \&/
characters.
Replace basename(3) by a thread-safe implementation. Now that the changes to the dirname(3) function had some time to settle, let's go ahead and use the same approach for replacing basename(3) by a simple implementation that modifies the input string, thereby making it thread-safe and guaranteed to succeed. Unlike dirname(3), this function already had a thread-safe variant basename_r(3). This function had its own set of problems, like having an upper bound on the pathname length. Keep this function around for compatibility, but remove most references from the man page. Make the man page more similar to that of dirname(3). As the basename_r(3) function is only provided by FreeBSD (and Bionic), depending on its use is even more implementation defined than assuming that basename(3) is thread-safe. Reviewed by: emaste Differential Revision: https://reviews.freebsd.org/D8382
2016-11-03 20:21:34 +00:00
.Sh RETURN VALUES
Import XPG4-compliant basename(3) and dirname(3) from OpenBSD. The man pages need some adjustments. PR: 12960, 12962 Submitted by: James Howard <howardjp@wam.umd.edu> Obtained from: OpenBSD
2000-08-31 15:56:15 +00:00
If
mdoc(7) police: Fixed abuses of the .Ar and .Em macros.
2002-12-18 13:33:04 +00:00
.Fa path
Import XPG4-compliant basename(3) and dirname(3) from OpenBSD. The man pages need some adjustments. PR: 12960, 12962 Submitted by: James Howard <howardjp@wam.umd.edu> Obtained from: OpenBSD
2000-08-31 15:56:15 +00:00
consists entirely of
.Sq \&/
characters, a pointer to the string
.Qq \&/
is returned.
If
mdoc(7) police: Fixed abuses of the .Ar and .Em macros.
2002-12-18 13:33:04 +00:00
.Fa path
Import XPG4-compliant basename(3) and dirname(3) from OpenBSD. The man pages need some adjustments. PR: 12960, 12962 Submitted by: James Howard <howardjp@wam.umd.edu> Obtained from: OpenBSD
2000-08-31 15:56:15 +00:00
is a null pointer or the empty string, a pointer to the string
.Qq \&.
is returned.
Replace basename(3) by a thread-safe implementation. Now that the changes to the dirname(3) function had some time to settle, let's go ahead and use the same approach for replacing basename(3) by a simple implementation that modifies the input string, thereby making it thread-safe and guaranteed to succeed. Unlike dirname(3), this function already had a thread-safe variant basename_r(3). This function had its own set of problems, like having an upper bound on the pathname length. Keep this function around for compatibility, but remove most references from the man page. Make the man page more similar to that of dirname(3). As the basename_r(3) function is only provided by FreeBSD (and Bionic), depending on its use is even more implementation defined than assuming that basename(3) is thread-safe. Reviewed by: emaste Differential Revision: https://reviews.freebsd.org/D8382
2016-11-03 20:21:34 +00:00
Otherwise,
it returns a pointer to the last component of
.Fa path .
More accurately document the implementation details of internal storage. PR: docs/82508
2006-10-12 14:31:17 +00:00
.Sh IMPLEMENTATION NOTES
Replace basename(3) by a thread-safe implementation. Now that the changes to the dirname(3) function had some time to settle, let's go ahead and use the same approach for replacing basename(3) by a simple implementation that modifies the input string, thereby making it thread-safe and guaranteed to succeed. Unlike dirname(3), this function already had a thread-safe variant basename_r(3). This function had its own set of problems, like having an upper bound on the pathname length. Keep this function around for compatibility, but remove most references from the man page. Make the man page more similar to that of dirname(3). As the basename_r(3) function is only provided by FreeBSD (and Bionic), depending on its use is even more implementation defined than assuming that basename(3) is thread-safe. Reviewed by: emaste Differential Revision: https://reviews.freebsd.org/D8382
2016-11-03 20:21:34 +00:00
This implementation of
Mention that basename(3) and dirname(3) will change in the future. Update the existing manual pages for basename(3) and dirname(3) to mention that in future versions of FreeBSD, these functions will no longer use internal buffers for storing the results. MFC after: 1 week Differential Revision: https://reviews.freebsd.org/D7356
2016-07-29 16:25:09 +00:00
.Fn basename
Replace basename(3) by a thread-safe implementation. Now that the changes to the dirname(3) function had some time to settle, let's go ahead and use the same approach for replacing basename(3) by a simple implementation that modifies the input string, thereby making it thread-safe and guaranteed to succeed. Unlike dirname(3), this function already had a thread-safe variant basename_r(3). This function had its own set of problems, like having an upper bound on the pathname length. Keep this function around for compatibility, but remove most references from the man page. Make the man page more similar to that of dirname(3). As the basename_r(3) function is only provided by FreeBSD (and Bionic), depending on its use is even more implementation defined than assuming that basename(3) is thread-safe. Reviewed by: emaste Differential Revision: https://reviews.freebsd.org/D8382
2016-11-03 20:21:34 +00:00
uses the buffer provided by the caller to store the resulting pathname
component.
Other vendor implementations may return a pointer to internal storage
space instead.
The advantage of the former approach is that it ensures thread-safety,
while also placing no upper limit on the supported length of the
pathname.
Import XPG4-compliant basename(3) and dirname(3) from OpenBSD. The man pages need some adjustments. PR: 12960, 12962 Submitted by: James Howard <howardjp@wam.umd.edu> Obtained from: OpenBSD
2000-08-31 15:56:15 +00:00
.Sh SEE ALSO
.Xr basename 1 ,
.Xr dirname 1 ,
.Xr dirname 3
.Sh STANDARDS
The
.Fn basename
function conforms to
.St -xpg4.2 .
.Sh HISTORY
The
.Fn basename
function first appeared in
Give the FreeBSD history also.
2001-07-10 00:11:00 +00:00
.Ox 2.2
and
.Fx 4.2 .
Sync with OpenBSD, primarily make the code easier to read, and a license change to standard OpenBSD ISC license. Obtained from: OpenBSD MFC after: 2 weeks
2011-06-18 00:33:34 +00:00
.Pp
Replace basename(3) by a thread-safe implementation. Now that the changes to the dirname(3) function had some time to settle, let's go ahead and use the same approach for replacing basename(3) by a simple implementation that modifies the input string, thereby making it thread-safe and guaranteed to succeed. Unlike dirname(3), this function already had a thread-safe variant basename_r(3). This function had its own set of problems, like having an upper bound on the pathname length. Keep this function around for compatibility, but remove most references from the man page. Make the man page more similar to that of dirname(3). As the basename_r(3) function is only provided by FreeBSD (and Bionic), depending on its use is even more implementation defined than assuming that basename(3) is thread-safe. Reviewed by: emaste Differential Revision: https://reviews.freebsd.org/D8382
2016-11-03 20:21:34 +00:00
In
.Fx 12.0 ,
this function was reimplemented to store its result in the provided
input buffer.
There is no longer any need to use the
.Fn basename_r
function.
.Sh AUTHORS
.An Nuxi, the Netherlands
Reference in New Issue Copy Permalink