Annotation of src/lib/libc/gen/dirname.3, Revision 1.14
1.14 ! christos 1: .\" $NetBSD: dirname.3,v 1.13 2008/04/30 13:10:50 martin Exp $
1.1 kleink 2: .\"
1.8 thorpej 3: .\" Copyright (c) 1997, 2002 The NetBSD Foundation, Inc.
1.1 kleink 4: .\" All rights reserved.
5: .\"
6: .\" This code is derived from software contributed to The NetBSD Foundation
1.8 thorpej 7: .\" by Klaus Klein and Jason R. Thorpe.
1.1 kleink 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: .\"
1.14 ! christos 30: .Dd May 10, 2008
1.1 kleink 31: .Dt DIRNAME 3
1.3 garbled 32: .Os
1.1 kleink 33: .Sh NAME
34: .Nm dirname
35: .Nd report the parent directory name of a file pathname
1.2 perry 36: .Sh LIBRARY
37: .Lb libc
1.1 kleink 38: .Sh SYNOPSIS
1.10 wiz 39: .In libgen.h
1.1 kleink 40: .Ft char *
1.14 ! christos 41: .Fn dirname "char *path"
1.1 kleink 42: .Sh DESCRIPTION
43: The
44: .Fn dirname
45: function takes a pointer to a character string that contains a pathname,
46: .Ar path ,
47: and returns a pointer to a string that is a pathname of the parent directory of
48: .Ar path .
1.9 wiz 49: Trailing
50: .Sq /
51: characters in
1.1 kleink 52: .Ar path
53: are not counted as part of the path.
54: .Pp
55: If
56: .Ar path
1.9 wiz 57: does not contain a
58: .Sq / ,
59: then
1.1 kleink 60: .Fn dirname
1.9 wiz 61: returns a pointer to the string
62: .Dq \&. .
1.1 kleink 63: .Pp
64: If
65: .Ar path
66: is a null pointer or points to an empty string,
67: .Fn dirname
1.9 wiz 68: returns a pointer to the string
69: .Dq \&. .
1.1 kleink 70: .Sh RETURN VALUES
71: The
72: .Fn dirname
73: function returns a pointer to a string that is the parent directory of
74: .Ar path .
75: .Sh SEE ALSO
1.11 kleink 76: .Xr dirname 1 ,
1.1 kleink 77: .Xr basename 3
78: .Sh STANDARDS
79: .Bl -bullet -compact
1.5 wiz 80: .It
1.1 kleink 81: .St -xpg4.2
1.8 thorpej 82: .It
83: .St -p1003.1-2001
1.5 wiz 84: .El
1.1 kleink 85: .Sh BUGS
1.8 thorpej 86: If the length of the result is longer than
87: .Dv PATH_MAX
88: bytes
89: .Pq including the terminating nul ,
90: the result will be truncated.
91: .Pp
1.1 kleink 92: The
93: .Fn dirname
1.8 thorpej 94: function returns a pointer to static storage that may be overwritten
95: by subsequent calls to
96: .Fn dirname .
97: This is not strictly a bug; it is explicitly allowed by
98: .St -p1003.1-2001 .
CVSweb <webmaster@jp.NetBSD.org>