man getcwd (3): das aktuelle Verzeichnis abfragen

Other Alias

getwd, get_current_dir_name

ÜBERSICHT

#include <unistd.h>

char *getcwd(char *Puffer, size_t Größe);

char *getwd(char *Puffer);

char *get_current_dir_name(void);

Mit Glibc erforderliche Makros (siehe feature_test_macros(7)):

get_current_dir_name():

: _GNU_SOURCE

getwd():

Seit Glibc 2.12:

(_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
    || /* Glibc seit 2.19: */ _DEFAULT_SOURCE
    || /* Glibc-Versionen <= 2.19: */ _BSD_SOURCE

Vor Glibc 2.12: _BSD_SOURCE || _XOPEN_SOURCE >= 500

BESCHREIBUNG

Diese Funktionen geben eine Zeichenkette mit abschließender Null zurück, die einen absoluten Pfadnamen enthält, der dem aktuellen Arbeitsverzeichnis des aufrufenden Prozesses entspricht. Der Pfadname wird als das Funktionsergebnis und, falls vorhanden, über das Argument Puffer zurückgegeben.

Falls das aktuelle Verzeichnis nicht unterhalb des Wurzelverzeichnisses des aktuellen Prozesses ist (z.B. da der Prozess eine neue Dateisystemwurzel mit chroot(2) gesetzt hat, ohne sein aktuelles Verzeichnis in die neue Wurzel zu ändern), dann wird seit 2.6.36 dem zurückgelieferten Pfad die Zeichenkette »(unreachable)« vorangestellt. Ein solches Verhalten kann auch durch unprivilegierte Benutzer, die das aktuelle Verzeichnis in einen anderen mount-Namensraum ändern, hervorgerufen werden. Beim Umgang mit Pfaden von unvertrauenswürdigen Quellen sollten Aufrufende dieser Funktion überlegen, zu prüfen, ob der zurückgelieferte Pfad mit »/« oder mit »(« anfängt, um zu vermeiden, dass ein nicht erreichbarer Pfad als relativer Pfad misinterpretiert wird.

Die Funktion getcwd() kopiert den absoluten Pfadnamen des aktuellen Arbeitsverzeichnisses in das Feld, auf das Puffer zeigt und das Größe Byte lang ist.

Falls die Länge des absoluten Pfadnamens des Arbeitsverzeichnisses, einschließlich abschließender Null Größe Byte überschreitet, wird NULL zurückgegeben und errno auf ERANGE gesetzt. Eine Anwendung sollte prüfen, ob dieser Fehler auftrat und falls nötig einen größeren Puffer reservieren.

Als eine Erweiterung des POSIX.1-2001-Standards reserviert getcwd() der Linux-Glibc den Puffer dynamisch durch Verwendung von malloc(3), wenn Puffer NULL ist. In diesem Fall hat der reservierte Puffer die Länge Größe, sofern Gräße nicht Null ist, wenn die für Puffer nötige Größe reserviert ist. Der Aufrufende sollte den zurückgegebenen Puffer mit free(3) freigeben.

get_current_dir_name() wird mit malloc(3) ein Feld reservieren, das groß genug ist, um den absoluten Pfadnamen des aktuellen Arbeitsverzeichnisses aufzunehmen. Wenn die Umgebungsvariable PWD gesetzt ist und ihr Wert stimmt, dann wird dieser Wert zurückgegeben. Der Aufrufende sollte den zurückgegebenen Puffer mit free(3) freigeben.

getwd() reserviert keinen Speicher mit malloc(3). Das Argument Puffer sollte ein Zeiger auf ein Feld mit einer Mindestlänge von PATH_MAX Byte sein. Falls die Länge des absoluten Pfadnamens des aktuellen Arbeitsverzeichnisses einschließlich des abschließenden Null-Bytes PATH_MAX Byte überschreitet, wird NULL zurückgegeben und errno auf ENAMETOOLONG gesetzt. (Beachten Sie, dass PATH_MAX auf einigen Systemen zur Kompilierzeit möglicherweise keine Konstante ist; außerdem hängt ihr Wert vom Dateisystem ab – siehe pathconf(3).) Aus Gründen der Portierbarkeit und Sicherheit ist die Benutzung von getwd() missbilligt.

RÜCKGABEWERT

Bei Erfolg geben diese Funktionen einen Zeiger auf eine Zeichenkette zurück, die den Pfadnamen des aktuellen Arbeitsverzeichnisses enthält. Im Fall von getcwd() und getwd() ist dies der gleiche Wert wie Puffer.

Bei einem Fehlschlag geben diese Funktionen Null zurück und errno wird so gesetzt, dass es den Fehler anzeigt. Der Inhalt des Feldes, auf den Puffer zeigt, ist bei einem Fehler nicht definiert.

FEHLER

EACCES: Lese- oder Suchberechtigung für einen Bestandteil des Dateinamens wurde verweigert.
EFAULT: Puffer zeigt auf eine falsche Adresse.
EINVAL: Das Argument Größe ist Null und Puffer ist kein Null-Zeiger.
EINVAL: getwd(): Puffer ist NULL.
ENAMETOOLONG: getwd(): Die Größe des absoluten Pfadnamens mit abschließender Null überschreitet PATH_MAX Byte.
ENOMEM: Speicher aufgebraucht.
ENOENT: Der Link auf das aktuelle Arbeitsverzeichnis wurde gelöst.
ERANGE: Das Argument Größe ist kleiner als die Länge des absoluten Pfadnamens des aktuellen Arbeitsverzeichnisses einschließlich abschließendem Null-Byte. Sie müssen ein größeres Feld reservieren und es erneut versuchen.

ATTRIBUTE

Siehe attributes(7) für eine Erläuterung der in diesem Abschnitt verwandten Ausdrücke.

Schnittstelle	Attribut	Wert
getcwd(), getwd()	Multithread-Fähigkeit	MT-Safe
get_current_dir_name()	Multithread-Fähigkeit	MT-Safe env

KONFORM ZU

getcwd() ist konform zu POSIX.1-2001. Beachten Sie jedoch, dass das Verhalten von getcwd() unter POSIX.1-2001 nicht spezifiziert ist, wenn Puffer NULL ist.

getwd() ist in POSIX.1-2001 vorhanden, aber als VERALTET markiert. POSIX.1-2008 entfernt die Spezifikation von getwd(). Benutzen Sie stattdessen getcwd(). POSIX.1-2001 definiert keine Fehler für getwd().

get_current_dir_name() ist eine GNU-Erweiterung.

ANMERKUNGEN

Unter Linux ist die Funktion getcwd() ein Systemaufruf (seit 2.1.92). Auf älteren Systemen würde es /proc/self/cwd abfragen. Falls sowohl der Systemaufruf, als auch das »proc«-Dateisystem fehlen, wird eine allgemeine Implementierung aufgerufen. Nur in diesem Fall können diese Systemaufrufe unter Linux mit EACCES fehlschlagen.

Diese Funktionen werden oft benutzt, um den Ort des aktuellen Arbeitsverzeichnisses zum Zweck der späteren Rückkehr zu speichern. Das aktuelle Verzeichnis ».« zu öffnen und fchdir(2) zur Rückkehr aufzurufen ist normalerweise schneller und eine zuverlässigere Alternative, wenn ausreichend viele Dateideskriptoren zur Verfügung stehen, besonders auf anderen Plattformen als Linux.

KOLOPHON

Diese Seite ist Teil der Veröffentlichung 4.06 des Projekts Linux-man-pages. Eine Beschreibung des Projekts, Informationen, wie Fehler gemeldet werden können sowie die aktuelle Version dieser Seite finden sich unter https://www.kernel.org/doc/man-pages/.

ÜBERSETZUNG

Die deutsche Übersetzung dieser Handbuchseite wurde von Martin Schulze <[email protected]>, Chris Leick <[email protected]>, Mario Blättermann <[email protected]> und Helge Kreutzmann <[email protected]> erstellt.

Diese Übersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezüglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen.

Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an <[email protected]>.