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 July 29, 2016 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 "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.Pp 65Other vendor implementations of 66.Fn basename 67may store their result in the input buffer, 68making it safe to use in multithreaded applications. 69Future versions of 70.Fx 71will follow this approach as well. 72.Fn basename_r 73will then become obsolete. 74.Sh RETURN VALUES 75On successful completion, 76.Fn basename 77and 78.Fn basename_r 79return pointers to the last component of 80.Fa path . 81.Pp 82If they fail, a null pointer is returned and the global variable 83.Va errno 84is set to indicate the error. 85.Sh ERRORS 86The following error codes may be set in 87.Va errno : 88.Bl -tag -width Er 89.It Bq Er ENAMETOOLONG 90The path component to be returned was larger than 91.Dv MAXPATHLEN . 92.El 93.Sh SEE ALSO 94.Xr basename 1 , 95.Xr dirname 1 , 96.Xr dirname 3 97.Sh STANDARDS 98The 99.Fn basename 100function conforms to 101.St -xpg4.2 . 102.Sh HISTORY 103The 104.Fn basename 105function first appeared in 106.Ox 2.2 107and 108.Fx 4.2 . 109.Sh AUTHORS 110.An Todd C. Miller 111.Sh CAVEATS 112.Fn basename 113returns a pointer to internal static storage space that will be overwritten 114by subsequent calls. 115.Pp 116Other vendor implementations of 117.Fn basename 118may modify the contents of the string passed to 119.Fn basename ; 120this should be taken into account when writing code which calls this function 121if portability is desired. 122