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

.\" $OpenBSD: basename.3,v 1.20 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$
.\"
.Dd March 31, 2010
.Dt BASENAME 3
.Os
.Sh NAME
.Nm basename
.Nd extract the base portion of a pathname
.Sh SYNOPSIS
.In libgen.h
.Ft char *
.Fn basename "char *path"
.Ft char *
.Fn basename_r "const char *path" "char *bname"
.Sh DESCRIPTION
The
.Fn basename
function returns the last component from the pathname pointed to by
.Fa path ,
deleting any trailing
.Sq \&/
characters.
If
.Fa path
consists entirely of
.Sq \&/
characters, a pointer to the string
.Qq \&/
is returned.
If
.Fa path
is a null pointer or the empty string, a pointer to the string
.Qq \&.
is returned.
.Pp
The
.Fn basename_r
variation accepts a buffer of at least
.Dv MAXPATHLEN
bytes in which to store the resulting component.
.Sh IMPLEMENTATION NOTES
The
.Fn basename
function
returns a pointer to internal storage space allocated on the first call
that will be overwritten
by subsequent calls.
.Fn basename_r
is therefore preferred for threaded applications.
.Sh RETURN VALUES
On successful completion,
.Fn basename
and
.Fn basename_r
return pointers to the last component of
.Fa path .
.Pp
If they fail, 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 .
.El
.Sh SEE ALSO
.Xr basename 1 ,
.Xr dirname 1 ,
.Xr dirname 3
.Sh STANDARDS
The
.Fn basename
function conforms to
.St -xpg4.2 .
.Sh HISTORY
The
.Fn basename
function first appeared in
.Ox 2.2
and
.Fx 4.2 .
The
.Fn basename_r
function first appeared in OS X 10.12.
.Sh AUTHORS
.An Todd C. Miller
.Sh CAVEATS
.Fn basename
returns a pointer to internal static storage space that will be overwritten
by subsequent calls.
.Pp
Other vendor implementations of
.Fn basename
may modify the contents of the string passed to
.Fn basename ;
this should be taken into account when writing code which calls this function
if portability is desired.
Commit	Line	Data
974e3884	1	.\" $OpenBSD: basename.3,v 1.20 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	.\"
974e3884 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	.\"
974e3884 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	.\"
974e3884	17	.\" $FreeBSD$
5b2abdfb	18	.\"
974e3884	19	.Dd March 31, 2010
5b2abdfb A	20	.Dt BASENAME 3
	21	.Os
	22	.Sh NAME
	23	.Nm basename
	24	.Nd extract the base portion of a pathname
	25	.Sh SYNOPSIS
	26	.In libgen.h
	27	.Ft char *
974e3884 A	28	.Fn basename "char *path"
	29	.Ft char *
	30	.Fn basename_r "const char path" "char bname"
5b2abdfb A	31	.Sh DESCRIPTION
	32	The
	33	.Fn basename
974e3884	34	function returns the last component from the pathname pointed to by
9385eb3d	35	.Fa path ,
5b2abdfb A	36	deleting any trailing
	37	.Sq \&/
	38	characters.
	39	If
9385eb3d	40	.Fa path
5b2abdfb A	41	consists entirely of
	42	.Sq \&/
	43	characters, a pointer to the string
	44	.Qq \&/
	45	is returned.
	46	If
9385eb3d	47	.Fa path
5b2abdfb A	48	is a null pointer or the empty string, a pointer to the string
	49	.Qq \&.
	50	is returned.
974e3884 A	51	.Pp
	52	The
	53	.Fn basename_r
	54	variation accepts a buffer of at least
	55	.Dv MAXPATHLEN
	56	bytes in which to store the resulting component.
	57	.Sh IMPLEMENTATION NOTES
	58	The
	59	.Fn basename
	60	function
	61	returns a pointer to internal storage space allocated on the first call
	62	that will be overwritten
	63	by subsequent calls.
	64	.Fn basename_r
	65	is therefore preferred for threaded applications.
5b2abdfb A	66	.Sh RETURN VALUES
	67	On successful completion,
	68	.Fn basename
974e3884 A	69	and
	70	.Fn basename_r
	71	return pointers to the last component of
9385eb3d	72	.Fa path .
5b2abdfb	73	.Pp
974e3884	74	If they fail, a null pointer is returned and the global variable
5b2abdfb A	75	.Va errno
	76	is set to indicate the error.
	77	.Sh ERRORS
	78	The following error codes may be set in
	79	.Va errno :
	80	.Bl -tag -width Er
	81	.It Bq Er ENAMETOOLONG
	82	The path component to be returned was larger than
	83	.Dv MAXPATHLEN .
	84	.El
5b2abdfb A	85	.Sh SEE ALSO
	86	.Xr basename 1 ,
	87	.Xr dirname 1 ,
974e3884	88	.Xr dirname 3
5b2abdfb A	89	.Sh STANDARDS
	90	The
	91	.Fn basename
	92	function conforms to
	93	.St -xpg4.2 .
	94	.Sh HISTORY
	95	The
	96	.Fn basename
	97	function first appeared in
	98	.Ox 2.2
	99	and
	100	.Fx 4.2 .
974e3884 A	101	The
	102	.Fn basename_r
	103	function first appeared in OS X 10.12.
5b2abdfb	104	.Sh AUTHORS
974e3884 A	105	.An Todd C. Miller
	106	.Sh CAVEATS
	107	.Fn basename
	108	returns a pointer to internal static storage space that will be overwritten
	109	by subsequent calls.
	110	.Pp
	111	Other vendor implementations of
	112	.Fn basename
	113	may modify the contents of the string passed to
	114	.Fn basename ;
	115	this should be taken into account when writing code which calls this function
	116	if portability is desired.