git.saurik.com Git - apple/libc.git/blame_incremental

... / ...

Commit	Line	Data
	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"