d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
8f932310ff
freebsd-nq/lib/libc/gen/dirname.3

86 lines
2.2 KiB
Groff
Raw Normal View History

Sync with OpenBSD's dirname(3) - license change, avoid strcpy() over string constant, use memcpy() instead of strncpy() and improve code readibility. No functional change.
2008-11-03 05:19:45 +00:00
.\" $OpenBSD: dirname.3,v 1.17 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's dirname(3) - license change, avoid strcpy() over string constant, use memcpy() instead of strncpy() and improve code readibility. No functional change.
2008-11-03 05:19:45 +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's dirname(3) - license change, avoid strcpy() over string constant, use memcpy() instead of strncpy() and improve code readibility. No functional change.
2008-11-03 05:19:45 +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 dirname(3) by a copy that complies to POSIX. It turns out that the path normalization that our brand new copy of dirname(3) does is actually not allowed by the draft version of the upcoming version of POSIX. It has to behave identically to the dirname(1) utility. This change replaces our new dirname(3) implementation by yet another version that doesn't implement the path normalization logic; it merely looks for the end of the directory name and overwrites that with a null byte. More details: See note #3370 at http://austingroupbugs.net/view.php?id=1073 PR: 212193 Reviewed by: emaste, jilles Differential Revision: https://reviews.freebsd.org/D7790
2016-09-18 20:47:55 +00:00
.Dd September 5, 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 DIRNAME 3
.Os
.Sh NAME
.Nm dirname
english(4) police.
2002-12-27 12:15:40 +00:00
.Nd extract the directory part of a 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 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 dirname "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 dirname
Sync with OpenBSD's dirname(3) - license change, avoid strcpy() over string constant, use memcpy() instead of strncpy() and improve code readibility. No functional change.
2008-11-03 05:19:45 +00:00
function is the converse of
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
.Xr basename 3 ;
it returns a pointer to the parent directory of 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
Any trailing
.Sq \&/
characters are not counted as part of the directory
name.
Reimplement dirname(3) to be thread-safe. Now that we've updated the prototypes of the basename(3) and dirname(3) functions to conform to POSIX, let's go ahead and reimplement dirname(3) in such a way that it's thread-safe, but also guaranteed to succeed. C libraries like glibc, musl and the one that's part of Solaris already follow such an approach. Move the existing implementation to another source file, freebsd11_dirname.c to keep existing users of the API that pass in a constant string happy, using symbol versioning. Put a new version of the function in dirname.c, obtained from CloudABI's C library. This version scans through the pathname string from left to right, normalizing it, while discarding the last pathname component. Reviewed by: emaste, jilles Differential Revision: https://reviews.freebsd.org/D7355
2016-08-12 07:03:58 +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
is a null pointer, the empty string, or contains no
.Sq \&/
characters,
.Fn dirname
returns a pointer to the string
.Qq \&. ,
signifying the current directory.
Reimplement dirname(3) to be thread-safe. Now that we've updated the prototypes of the basename(3) and dirname(3) functions to conform to POSIX, let's go ahead and reimplement dirname(3) in such a way that it's thread-safe, but also guaranteed to succeed. C libraries like glibc, musl and the one that's part of Solaris already follow such an approach. Move the existing implementation to another source file, freebsd11_dirname.c to keep existing users of the API that pass in a constant string happy, using symbol versioning. Put a new version of the function in dirname.c, obtained from CloudABI's C library. This version scans through the pathname string from left to right, normalizing it, while discarding the last pathname component. Reviewed by: emaste, jilles Differential Revision: https://reviews.freebsd.org/D7355
2016-08-12 07:03:58 +00:00
Otherwise,
it returns a pointer to the parent directory 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
Reimplement dirname(3) to be thread-safe. Now that we've updated the prototypes of the basename(3) and dirname(3) functions to conform to POSIX, let's go ahead and reimplement dirname(3) in such a way that it's thread-safe, but also guaranteed to succeed. C libraries like glibc, musl and the one that's part of Solaris already follow such an approach. Move the existing implementation to another source file, freebsd11_dirname.c to keep existing users of the API that pass in a constant string happy, using symbol versioning. Put a new version of the function in dirname.c, obtained from CloudABI's C library. This version scans through the pathname string from left to right, normalizing it, while discarding the last pathname component. Reviewed by: emaste, jilles Differential Revision: https://reviews.freebsd.org/D7355
2016-08-12 07:03:58 +00:00
This implementation of
More accurately document the implementation details of internal storage. PR: docs/82508
2006-10-12 14:31:17 +00:00
.Fn dirname
Reimplement dirname(3) to be thread-safe. Now that we've updated the prototypes of the basename(3) and dirname(3) functions to conform to POSIX, let's go ahead and reimplement dirname(3) in such a way that it's thread-safe, but also guaranteed to succeed. C libraries like glibc, musl and the one that's part of Solaris already follow such an approach. Move the existing implementation to another source file, freebsd11_dirname.c to keep existing users of the API that pass in a constant string happy, using symbol versioning. Put a new version of the function in dirname.c, obtained from CloudABI's C library. This version scans through the pathname string from left to right, normalizing it, while discarding the last pathname component. Reviewed by: emaste, jilles Differential Revision: https://reviews.freebsd.org/D7355
2016-08-12 07:03:58 +00:00
uses the buffer provided by the caller to store the resulting parent
directory.
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 basename 3
.Sh STANDARDS
The
.Fn dirname
function conforms to
.St -xpg4.2 .
.Sh HISTORY
The
.Fn dirname
function first appeared in
MFS: add the FreeBSD history.
2001-07-10 00:12:50 +00:00
.Ox 2.2
and
.Fx 4.2 .
Reimplement dirname(3) to be thread-safe. Now that we've updated the prototypes of the basename(3) and dirname(3) functions to conform to POSIX, let's go ahead and reimplement dirname(3) in such a way that it's thread-safe, but also guaranteed to succeed. C libraries like glibc, musl and the one that's part of Solaris already follow such an approach. Move the existing implementation to another source file, freebsd11_dirname.c to keep existing users of the API that pass in a constant string happy, using symbol versioning. Put a new version of the function in dirname.c, obtained from CloudABI's C library. This version scans through the pathname string from left to right, normalizing it, while discarding the last pathname component. Reviewed by: emaste, jilles Differential Revision: https://reviews.freebsd.org/D7355
2016-08-12 07:03:58 +00:00
.Pp
In
.Fx 12.0 ,
this function was reimplemented to store its result in the provided
input buffer.
mdoc(7) police: use certified section headers wherever possible.
2000-11-17 11:44:16 +00:00
.Sh AUTHORS
Reimplement dirname(3) to be thread-safe. Now that we've updated the prototypes of the basename(3) and dirname(3) functions to conform to POSIX, let's go ahead and reimplement dirname(3) in such a way that it's thread-safe, but also guaranteed to succeed. C libraries like glibc, musl and the one that's part of Solaris already follow such an approach. Move the existing implementation to another source file, freebsd11_dirname.c to keep existing users of the API that pass in a constant string happy, using symbol versioning. Put a new version of the function in dirname.c, obtained from CloudABI's C library. This version scans through the pathname string from left to right, normalizing it, while discarding the last pathname component. Reviewed by: emaste, jilles Differential Revision: https://reviews.freebsd.org/D7355
2016-08-12 07:03:58 +00:00
.An Nuxi, the Netherlands
Reference in New Issue Copy Permalink