xref: /freebsd/lib/libc/gen/dirname.3 (revision a220d00e74dd245b4fca59c5eca0c53963686325)
1.\"
2.\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com>
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\" 3. The name of the author may not be used to endorse or promote products
14.\"    derived from this software without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
17.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
18.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
19.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
20.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
22.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
23.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
24.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
25.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26.\"
27.\" $OpenBSD: dirname.3,v 1.9 2000/04/18 03:01:25 aaron Exp $
28.\" $FreeBSD$
29.\"
30.Dd August 17, 1997
31.Dt DIRNAME 3
32.Os
33.Sh NAME
34.Nm dirname
35.Nd extract the directory portition of a pathname
36.Sh SYNOPSIS
37.In libgen.h
38.Ft char *
39.Fn dirname "const char *path"
40.Sh DESCRIPTION
41The
42.Fn dirname
43function
44is the converse of
45.Xr basename 3 ;
46it returns a pointer to the parent directory of the pathname pointed to by
47.Ar path .
48Any trailing
49.Sq \&/
50characters are not counted as part of the directory
51name.
52If
53.Ar path
54is a null pointer, the empty string, or contains no
55.Sq \&/
56characters,
57.Fn dirname
58returns a pointer to the string
59.Qq \&. ,
60signifying the current directory.
61.Sh RETURN VALUES
62On successful completion,
63.Fn dirname
64returns a pointer to the parent directory of
65.Ar path .
66.Pp
67If
68.Fn dirname
69fails, a null pointer is returned and the global variable
70.Va errno
71is set to indicate the error.
72.Sh ERRORS
73The following error codes may be set in
74.Va errno :
75.Bl -tag -width Er
76.It Bq Er ENAMETOOLONG
77The path component to be returned was larger than
78.Dv MAXPATHLEN .
79.El
80.Sh WARNINGS
81.Fn dirname
82returns a pointer to internal static storage space that will be overwritten
83by subsequent calls (each function has its own separate storage).
84.Pp
85Other vendor implementations of
86.Fn dirname
87may modify the contents of the string passed to
88.Fn dirname ;
89this should be taken into account when writing code which calls this function
90if portability is desired.
91.Sh SEE ALSO
92.Xr basename 1 ,
93.Xr dirname 1 ,
94.Xr basename 3
95.Sh STANDARDS
96The
97.Fn dirname
98function conforms to
99.St -xpg4.2 .
100.Sh HISTORY
101The
102.Fn dirname
103function first appeared in
104.Ox 2.2
105and
106.Fx 4.2 .
107.Sh AUTHORS
108Todd C. Miller <Todd.Miller@courtesan.com>
109