lib/libc/gen/dirname.3

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