raw/man3/basename.3

   1 .\" (c) 2000 by Michael Kerrisk (michael.kerrisk@gmx.net)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.
  16 .\"
  17 .\" Formatted or processed versions of this manual, if unaccompanied by
  18 .\" the source, must acknowledge the copyright and authors of this work.
  19 .\" License.
  20 .\" Created, 14 Dec 2000 by Michael Kerrisk
  21 .\"
  22 .TH DIRNAME 3  2000-12-14 "GNU" "Linux Programmer's Manual"
  23 .SH NAME
  24 dirname, basename \- Parse pathname components
  25 .SH SYNOPSIS
  26 .nf
  27 .B #include <libgen.h>
  28 .sp
  29 .BI "char *dirname(char *" path );
  30 .nl
  31 .BI "char *basename(char *" path );
  32 .fi
  33 .SH DESCRIPTION
  34 The functions
  35 .B dirname
  36 and
  37 .B basename
  38 break a null-terminated pathname string into directory
  39 and filename components.
  40 In the usual case,
  41 .B dirname
  42 returns the string up to, but not including, the final '/', and
  43 .B basename
  44 returns the component following the final '/'.
  45 Trailing '/' characters are not counted as part of the pathname.
  46 .PP
  47 If
  48 .I path
  49 does not contain a slash,
  50 .B dirname
  51 returns the string "." while
  52 .B basename
  53 returns a copy of
  54 .IR path .
  55 If
  56 .I path
  57 is the string "/", then both
  58 .B dirname
  59 and
  60 .B basename
  61 return the string "/".
  62 If
  63 .I path
  64 is a NULL pointer or points to an empty string, then both
  65 .B dirname
  66 and
  67 .B basename
  68 return the string ".".
  69 .PP
  70 Concatenating the string returned by
  71 .BR dirname ,
  72 a "/", and the string returned by
  73 .B basename
  74 yields a complete pathname.
  75 .PP
  76 Both
  77 .B dirname
  78 and
  79 .B basename
  80 may modify the contents of
  81 .IR path ,
  82 so if you need to preserve the pathname string,
  83 copies should be passed to these functions.  Furthermore,
  84 .B dirname
  85 and
  86 .B basename
  87 may return pointers to statically allocated memory
  88 which may be overwritten by subsequent calls.
  89 .PP
  90 The following list of examples (taken from SUSv2)
  91 shows the strings returned by
  92 .B dirname
  93 and
  94 .B basename
  95 for different paths:
  96 .sp
  97 .nf
  98 .B
  99 path            dirname         basename
 100 "/usr/lib"      "/usr"          "lib"
 101 "/usr/"         "/"             "usr"
 102 "usr"           "."             "usr"
 103 "/"             "/"             "/"
 104 "."             "."             "."
 105 ".."            "."             ".."
 106 .fi
 107 .SH EXAMPLE
 108 .nf
 109 char *dirc, *basec, *bname, *dname;
 110 char *path = "/etc/passwd";
 111
 112 dirc = strdup(path);
 113 basec = strdup(path);
 114 dname = dirname(dirc);
 115 bname = basename(basec);
 116 printf("dirname=%s, basename=%s\\n", dname, bname);
 117 free(dirc);
 118 free(basec);
 119 .fi
 120 .SH "RETURN VALUE"
 121 Both
 122 .B dirname
 123 and
 124 .B basename
 125 return pointers to null-terminated strings.
 126 .SH BUGS
 127 In versions of glibc up to and including 2.2.1,
 128 .B dirname
 129 does not correctly handle pathnames with trailing '/' characters,
 130 and generates a segmentation violation if given a NULL argument.
 131 .SH "CONFORMING TO"
 132 SUSv2
 133 .SH "SEE ALSO"
 134 .BR dirname (1),
 135 .BR basename (1),