1.\" $NetBSD: dirname.3,v 1.14 2008/05/10 22:39:40 christos Exp $ 2.\" 3.\" Copyright (c) 1997, 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Klaus Klein and Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd May 10, 2008 31.Dt DIRNAME 3 32.Os 33.Sh NAME 34.Nm dirname 35.Nd report the parent directory name of a file pathname 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In libgen.h 40.Ft char * 41.Fn dirname "char *path" 42.Sh DESCRIPTION 43The 44.Fn dirname 45function takes a pointer to a character string that contains a pathname, 46.Ar path , 47and returns a pointer to a string that is a pathname of the parent directory of 48.Ar path . 49Trailing 50.Sq / 51characters in 52.Ar path 53are not counted as part of the path. 54.Pp 55If 56.Ar path 57does not contain a 58.Sq / , 59then 60.Fn dirname 61returns a pointer to the string 62.Dq \&. . 63.Pp 64If 65.Ar path 66is a null pointer or points to an empty string, 67.Fn dirname 68returns a pointer to the string 69.Dq \&. . 70.Sh RETURN VALUES 71The 72.Fn dirname 73function returns a pointer to a string that is the parent directory of 74.Ar path . 75.Sh SEE ALSO 76.Xr dirname 1 , 77.Xr basename 3 78.Sh STANDARDS 79.Bl -bullet -compact 80.It 81.St -xpg4.2 82.It 83.St -p1003.1-2001 84.El 85.Sh BUGS 86If the length of the result is longer than 87.Dv PATH_MAX 88bytes 89.Pq including the terminating nul , 90the result will be truncated. 91.Pp 92The 93.Fn dirname 94function returns a pointer to static storage that may be overwritten 95by subsequent calls to 96.Fn dirname . 97This is not strictly a bug; it is explicitly allowed by 98.St -p1003.1-2001 . 99