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