+.\" $OpenBSD: dirname.3,v 1.17 2007/05/31 19:19:28 jmc Exp $
.\"
.\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com>
-.\" 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. The name of the author may not be used to endorse or promote products
-.\" derived from this software without specific prior written permission.
+.\" 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.
.\"
-.\" THIS SOFTWARE IS PROVIDED ``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 AUTHOR 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.
+.\" 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.
.\"
-.\" $OpenBSD: dirname.3,v 1.9 2000/04/18 03:01:25 aaron Exp $
-.\" $FreeBSD: src/lib/libc/gen/dirname.3,v 1.8 2004/07/02 23:52:10 ru Exp $
+.\" $FreeBSD: src/lib/libc/gen/dirname.3,v 1.10 2008/11/03 05:19:45 delphij Exp $
.\"
-.Dd August 17, 1997
+.Dd October 12, 2006
.Dt DIRNAME 3
.Os
.Sh NAME
.Sh SYNOPSIS
.In libgen.h
.Ft char *
-.Fn dirname "const char *path"
+.Fo dirname
+.Fa "char *path"
+.Fc
+.Ft char *
+.Fo dirname_r
+.Fa "const char *path" "char *dname"
+.Fc
.Sh DESCRIPTION
The
.Fn dirname
-function
-is the converse of
+function is the converse of
.Xr basename 3 ;
it returns a pointer to the parent directory of the pathname pointed to by
.Fa path .
returns a pointer to the string
.Qq \&. ,
signifying the current directory.
+.Sh IMPLEMENTATION NOTES
+The
+.Fn dirname
+function
+returns a pointer to internal storage space allocated on the first call
+that will be overwritten
+by subsequent calls.
+.Fn dirname_r
+is therefore preferred for threaded applications.
+.Pp
+Other vendor implementations of
+.Fn dirname
+may modify the contents of the string passed to
+.Fn dirname ;
+if portability is desired,
+this should be taken into account when writing code which calls this function.
+.Sh LEGACY SYNOPSIS
+.Fd #include <libgen.h>
+.Pp
+.Ft char *
+.br
+.Fo dirname
+.Fa "const char *path"
+.Fc ;
+.Pp
+In legacy mode,
+.Fa path
+will not be changed.
.Sh RETURN VALUES
On successful completion,
.Fn dirname
.It Bq Er ENAMETOOLONG
The path component to be returned was larger than
.Dv MAXPATHLEN .
-.El
-.Sh WARNINGS
-The
-.Fn dirname
-function
-returns a pointer to internal static storage space that will be overwritten
-by subsequent calls (each function has its own separate storage).
-.Pp
-Other vendor implementations of
+.It Bq Er ENOMEM
+The static buffer used for storing the path in
.Fn dirname
-may modify the contents of the string passed to
-.Fn dirname ;
-this should be taken into account when writing code which calls this function
-if portability is desired.
+could not be allocated.
+.El
.Sh SEE ALSO
.Xr basename 1 ,
.Xr dirname 1 ,
-.Xr basename 3
+.Xr basename 3 ,
+.Xr compat 5
.Sh STANDARDS
The
.Fn dirname
.Ox 2.2
and
.Fx 4.2 .
+The
+.Fn dirname_r
+function first appeared in OS X 10.12.
.Sh AUTHORS
-.An "Todd C. Miller" Aq Todd.Miller@courtesan.com
+.An "Todd C. Miller"
projects / apple / libc.git / blobdiff