[apple/libc.git] / gen / FreeBSD / dirname.3

.\" $OpenBSD: dirname.3,v 1.17 2007/05/31 19:19:28 jmc Exp $
.\"
.\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com>
.\"
.\" 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.
.\"
.\" 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.
.\"
.\" $FreeBSD: src/lib/libc/gen/dirname.3,v 1.10 2008/11/03 05:19:45 delphij Exp $
.\"
.Dd October 12, 2006
.Dt DIRNAME 3
.Os
.Sh NAME
.Nm dirname
.Nd extract the directory part of a pathname
.Sh SYNOPSIS
.In libgen.h
.Ft char *
.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
.Xr basename 3 ;
it returns a pointer to the parent directory of the pathname pointed to by
.Fa path .
Any trailing
.Sq \&/
characters are not counted as part of the directory
name.
If
.Fa path
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.
.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
returns a pointer to the parent directory of
.Fa path .
.Pp
If
.Fn dirname
fails, a null pointer is returned and the global variable
.Va errno
is set to indicate the error.
.Sh ERRORS
The following error codes may be set in
.Va errno :
.Bl -tag -width Er
.It Bq Er ENAMETOOLONG
The path component to be returned was larger than
.Dv MAXPATHLEN .
.It Bq Er ENOMEM
The static buffer used for storing the path in
.Fn dirname
could not be allocated.
.El
.Sh SEE ALSO
.Xr basename 1 ,
.Xr dirname 1 ,
.Xr basename 3 ,
.Xr compat 5
.Sh STANDARDS
The
.Fn dirname
function conforms to
.St -xpg4.2 .
.Sh HISTORY
The
.Fn dirname
function first appeared in
.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"
Commit	Line	Data
1f2f436a	1	.\" $OpenBSD: dirname.3,v 1.17 2007/05/31 19:19:28 jmc Exp $
5b2abdfb A	2	.\"
5b2abdfb A	3	.\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com>
5b2abdfb	4	.\"
1f2f436a A	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.
5b2abdfb	8	.\"
1f2f436a A	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.
5b2abdfb	16	.\"
1f2f436a	17	.\" $FreeBSD: src/lib/libc/gen/dirname.3,v 1.10 2008/11/03 05:19:45 delphij Exp $
5b2abdfb	18	.\"
1f2f436a	19	.Dd October 12, 2006
5b2abdfb A	20	.Dt DIRNAME 3
	21	.Os
	22	.Sh NAME
	23	.Nm dirname
9385eb3d	24	.Nd extract the directory part of a pathname
5b2abdfb A	25	.Sh SYNOPSIS
	26	.In libgen.h
	27	.Ft char *
ad3c9f2a A	28	.Fo dirname
	29	.Fa "char *path"
	30	.Fc
974e3884 A	31	.Ft char *
	32	.Fo dirname_r
	33	.Fa "const char path" "char dname"
	34	.Fc
5b2abdfb A	35	.Sh DESCRIPTION
	36	The
	37	.Fn dirname
1f2f436a	38	function is the converse of
5b2abdfb A	39	.Xr basename 3 ;
5b2abdfb A	40	it returns a pointer to the parent directory of the pathname pointed to by
9385eb3d	41	.Fa path .
5b2abdfb A	42	Any trailing
	43	.Sq \&/
	44	characters are not counted as part of the directory
	45	name.
	46	If
9385eb3d	47	.Fa path
5b2abdfb A	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.
1f2f436a A	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.
974e3884 A	62	.Fn dirname_r
974e3884 A	63	is therefore preferred for threaded applications.
1f2f436a A	64	.Pp
	65	Other vendor implementations of
	66	.Fn dirname
	67	may modify the contents of the string passed to
	68	.Fn dirname ;
ad3c9f2a A	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.
5b2abdfb A	83	.Sh RETURN VALUES
	84	On successful completion,
	85	.Fn dirname
	86	returns a pointer to the parent directory of
9385eb3d	87	.Fa path .
5b2abdfb A	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 .
974e3884 A	101	.It Bq Er ENOMEM
	102	The static buffer used for storing the path in
	103	.Fn dirname
	104	could not be allocated.
5b2abdfb	105	.El
5b2abdfb A	106	.Sh SEE ALSO
	107	.Xr basename 1 ,
	108	.Xr dirname 1 ,
ad3c9f2a A	109	.Xr basename 3 ,
ad3c9f2a A	110	.Xr compat 5
5b2abdfb A	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 .
974e3884 A	123	The
	124	.Fn dirname_r
	125	function first appeared in OS X 10.12.
5b2abdfb	126	.Sh AUTHORS
1f2f436a	127	.An "Todd C. Miller"