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.Dd $Mdocdate: May 31 2007 $ 18.Dt DIRNAME 3 19.Os 20.Sh NAME 21.Nm dirname 22.Nd extract the directory portion of a pathname 23.Sh SYNOPSIS 24.Fd #include <libgen.h> 25.Ft char * 26.Fn dirname "const char *path" 27.Sh DESCRIPTION 28The 29.Fn dirname 30function is the converse of 31.Xr basename 3 ; 32it returns a pointer to the parent directory of the pathname pointed to by 33.Ar path . 34Any trailing 35.Sq \&/ 36characters are not counted as part of the directory 37name. 38If 39.Ar path 40is a null pointer, the empty string, or contains no 41.Sq \&/ 42characters, 43.Fn dirname 44returns a pointer to the string 45.Qq \&. , 46signifying the current directory. 47.Sh RETURN VALUES 48On successful completion, 49.Fn dirname 50returns a pointer to the parent directory of 51.Ar path . 52.Pp 53If 54.Fn dirname 55fails, a null pointer is returned and the global variable 56.Va errno 57is set to indicate the error. 58.Sh ERRORS 59The following error codes may be set in 60.Va errno : 61.Bl -tag -width Er 62.It Bq Er ENAMETOOLONG 63The path component to be returned was larger than 64.Dv MAXPATHLEN . 65.El 66.Sh WARNINGS 67.Fn dirname 68returns a pointer to internal static storage space that will be overwritten 69by subsequent calls (each function has its own separate storage). 70.Pp 71Other vendor implementations of 72.Fn dirname 73may modify the contents of the string passed to 74.Fn dirname ; 75this should be taken into account when writing code which calls this function 76if portability is desired. 77.Sh SEE ALSO 78.Xr basename 1 , 79.Xr dirname 1 , 80.Xr basename 3 81.Sh STANDARDS 82The 83.Fn dirname 84function conforms to 85.St -xpg4.2 . 86.Sh HISTORY 87The 88.Fn dirname 89function first appeared in 90.Ox 2.2 . 91.Sh AUTHORS 92.An Todd C. Miller 93