huschi.net

DIRNAME(3P)                POSIX Programmer's Manual               DIRNAME(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
NAME
       dirname - report the parent directory name of a file pathname
SYNOPSIS
       #include <libgen.h>
       char *dirname(char *path);

DESCRIPTION
       The dirname() function shall take a pointer to a character string  that
       contains  a  pathname, and return a pointer to a string that is a path-
       name of the parent directory of that file. Trailing '/'  characters  in
       the path are not counted as part of the path.
       If  path  does not contain a '/', then dirname() shall return a pointer
       to the string "." . If path is a null pointer or  points  to  an  empty
       string, dirname() shall return a pointer to the string "."  .
       The  dirname()  function  need not be reentrant. A function that is not
       required to be reentrant is not required to be thread-safe.
RETURN VALUE
       The dirname() function shall return a pointer to a string that  is  the
       parent  directory  of  path.  If path is a null pointer or points to an
       empty string, a pointer to a string "." is returned.
       The dirname() function may modify the string pointed to  by  path,  and
       may  return a pointer to static storage that may then be overwritten by
       subsequent calls to dirname().
ERRORS
       No errors are defined.
       The following sections are informative.
EXAMPLES
       The following code fragment reads a pathname, changes the current work-
       ing directory to the parent directory, and opens the file.

              char path[PATH_MAX], *pathcopy;
              int fd;
              fgets(path, PATH_MAX, stdin);
              pathcopy = strdup(path);
              chdir(dirname(pathcopy));
              fd = open(basename(path), O_RDONLY);
   Sample Input and Output Strings for dirname()
       In  the  following  table,  the input string is the value pointed to by
       path, and the output string is the return value of the dirname()  func-
       tion.
                            Input String   Output String
                            "/usr/lib"     "/usr"
                            "/usr/"        "/"
                            "usr"          "."
                            "/"            "/"
                            "."            "."
                            ".."           "."
   Changing the Current Directory to the Parent Directory
       The  following  program  fragment reads a pathname, changes the current
       working directory to the parent directory, and opens the file.

              #include <unistd.h>
              #include <limits.h>
              #include <stdio.h>
              #include <fcntl.h>
              #include <string.h>
              #include <libgen.h>
              ...
              char path[PATH_MAX], *pathcopy;
              int fd;
              ...
              fgets(path, PATH_MAX, stdin);
              pathcopy = strdup(path);
              chdir(dirname(pathcopy));
              fd = open(basename(path), O_RDONLY);
APPLICATION USAGE
       The dirname() and basename() functions together yield a complete  path-
       name.  The  expression dirname(path) obtains the pathname of the direc-
       tory where basename(path) is found.
       Since the  meaning  of  the  leading  "//"  is  implementation-defined,
       dirname(" //foo) may return either "//" or '/' (but nothing else).
RATIONALE
       None.
FUTURE DIRECTIONS
       None.
SEE ALSO
       basename(),  the Base Definitions volume of IEEE Std 1003.1-2001, <lib-
       gen.h>
COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                          DIRNAME(3P)