dirname.3 (7b1fac00358d75b00a83566efb93372101958cdd) dirname.3 (1250db81390606572908abd88d78c1f2fa5a1832)
1.\" $OpenBSD: dirname.3,v 1.17 2007/05/31 19:19:28 jmc Exp $
2.\"
3.\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com>
1.\"
2.\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com>
3.\" All rights reserved.
4.\"
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
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.
8.\"
15.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
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.
16.\"
26.\"
27.\" $OpenBSD: dirname.3,v 1.9 2000/04/18 03:01:25 aaron Exp $
17.\" $FreeBSD$
18.\"
28.\" $FreeBSD$
29.\"
19.Dd October 12, 2006
30.Dd August 17, 1997
20.Dt DIRNAME 3
21.Os
22.Sh NAME
23.Nm dirname
31.Dt DIRNAME 3
32.Os
33.Sh NAME
34.Nm dirname
24.Nd extract the directory part of a pathname
35.Nd extract the directory portition of a pathname
25.Sh SYNOPSIS
36.Sh SYNOPSIS
26.In libgen.h
37.Fd #include <libgen.h>
27.Ft char *
28.Fn dirname "const char *path"
29.Sh DESCRIPTION
30The
31.Fn dirname
38.Ft char *
39.Fn dirname "const char *path"
40.Sh DESCRIPTION
41The
42.Fn dirname
32function is the converse of
43function
44is the converse of
33.Xr basename 3 ;
34it returns a pointer to the parent directory of the pathname pointed to by
45.Xr basename 3 ;
46it returns a pointer to the parent directory of the pathname pointed to by
35.Fa path .
47.Ar path .
36Any trailing
37.Sq \&/
38characters are not counted as part of the directory
39name.
40If
48Any trailing
49.Sq \&/
50characters are not counted as part of the directory
51name.
52If
41.Fa path
53.Ar path
42is a null pointer, the empty string, or contains no
43.Sq \&/
44characters,
45.Fn dirname
46returns a pointer to the string
47.Qq \&. ,
48signifying the current directory.
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.
49.Sh IMPLEMENTATION NOTES
50The
51.Fn dirname
52function
53returns a pointer to internal storage space allocated on the first call
54that will be overwritten
55by subsequent calls.
56.Pp
57Other vendor implementations of
58.Fn dirname
59may modify the contents of the string passed to
60.Fn dirname ;
61this should be taken into account when writing code which calls this function
62if portability is desired.
63.Sh RETURN VALUES
64On successful completion,
65.Fn dirname
66returns a pointer to the parent directory of
61.Sh RETURN VALUES
62On successful completion,
63.Fn dirname
64returns a pointer to the parent directory of
67.Fa path .
65.Ar path .
68.Pp
69If
70.Fn dirname
71fails, a null pointer is returned and the global variable
72.Va errno
73is set to indicate the error.
74.Sh ERRORS
75The following error codes may be set in
76.Va errno :
77.Bl -tag -width Er
78.It Bq Er ENAMETOOLONG
79The path component to be returned was larger than
80.Dv MAXPATHLEN .
81.El
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.
82.Sh SEE ALSO
83.Xr basename 1 ,
84.Xr dirname 1 ,
85.Xr basename 3
86.Sh STANDARDS
87The
88.Fn dirname
89function conforms to
90.St -xpg4.2 .
91.Sh HISTORY
92The
93.Fn dirname
94function first appeared in
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
95.Ox 2.2
96and
97.Fx 4.2 .
98.Sh AUTHORS
99.An "Todd C. Miller"
104.Ox 2.2 .
105.Sh AUTHOR
106Todd C. Miller <Todd.Miller@courtesan.com>