]> git.saurik.com Git - apple/libc.git/blob - gen/FreeBSD/dirname.3
Libc-1272.250.1.tar.gz
[apple/libc.git] / gen / FreeBSD / dirname.3
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>
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.
8 .\"
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 .\"
17 .\" $FreeBSD: src/lib/libc/gen/dirname.3,v 1.10 2008/11/03 05:19:45 delphij Exp $
18 .\"
19 .Dd October 12, 2006
20 .Dt DIRNAME 3
21 .Os
22 .Sh NAME
23 .Nm dirname
24 .Nd extract the directory part of a pathname
25 .Sh SYNOPSIS
26 .In libgen.h
27 .Ft char *
28 .Fo dirname
29 .Fa "char *path"
30 .Fc
31 .Ft char *
32 .Fo dirname_r
33 .Fa "const char *path" "char *dname"
34 .Fc
35 .Sh DESCRIPTION
36 The
37 .Fn dirname
38 function is the converse of
39 .Xr basename 3 ;
40 it returns a pointer to the parent directory of the pathname pointed to by
41 .Fa path .
42 Any trailing
43 .Sq \&/
44 characters are not counted as part of the directory
45 name.
46 If
47 .Fa path
48 is a null pointer, the empty string, or contains no
49 .Sq \&/
50 characters,
51 .Fn dirname
52 returns a pointer to the string
53 .Qq \&. ,
54 signifying the current directory.
55 .Sh IMPLEMENTATION NOTES
56 The
57 .Fn dirname
58 function
59 returns a pointer to internal storage space allocated on the first call
60 that will be overwritten
61 by subsequent calls.
62 .Fn dirname_r
63 is therefore preferred for threaded applications.
64 .Pp
65 Other vendor implementations of
66 .Fn dirname
67 may modify the contents of the string passed to
68 .Fn dirname ;
69 if portability is desired,
70 this should be taken into account when writing code which calls this function.
71 .Sh LEGACY SYNOPSIS
72 .Fd #include <libgen.h>
73 .Pp
74 .Ft char *
75 .br
76 .Fo dirname
77 .Fa "const char *path"
78 .Fc ;
79 .Pp
80 In legacy mode,
81 .Fa path
82 will not be changed.
83 .Sh RETURN VALUES
84 On successful completion,
85 .Fn dirname
86 returns a pointer to the parent directory of
87 .Fa path .
88 .Pp
89 If
90 .Fn dirname
91 fails, a null pointer is returned and the global variable
92 .Va errno
93 is set to indicate the error.
94 .Sh ERRORS
95 The following error codes may be set in
96 .Va errno :
97 .Bl -tag -width Er
98 .It Bq Er ENAMETOOLONG
99 The path component to be returned was larger than
100 .Dv MAXPATHLEN .
101 .It Bq Er ENOMEM
102 The static buffer used for storing the path in
103 .Fn dirname
104 could not be allocated.
105 .El
106 .Sh SEE ALSO
107 .Xr basename 1 ,
108 .Xr dirname 1 ,
109 .Xr basename 3 ,
110 .Xr compat 5
111 .Sh STANDARDS
112 The
113 .Fn dirname
114 function conforms to
115 .St -xpg4.2 .
116 .Sh HISTORY
117 The
118 .Fn dirname
119 function first appeared in
120 .Ox 2.2
121 and
122 .Fx 4.2 .
123 The
124 .Fn dirname_r
125 function first appeared in OS X 10.12.
126 .Sh AUTHORS
127 .An "Todd C. Miller"