getcwd

NAZWA

getcwd, getwd, get_current_dir_name - odczytanie bieżącego katalogu roboczego

BIBLIOTEKA

Standardowa biblioteka C ( libc, -lc)

SKŁADNIA

#include <unistd.h>

char *getcwd(char buf[.size], size_t size);
char *get_current_dir_name(void);

[[deprecated]] char *getwd(char buf[PATH_MAX]);

get_current_dir_name():

    _GNU_SOURCE

getwd():

    Od glibc 2.12:
        (_XOPEN_SOURCE >= 500) && ! (_POSIX_C_SOURCE >= 200809L)
            || /* glibc >= 2.19: */ _DEFAULT_SOURCE
            || /* glibc <= 2.19: */ _BSD_SOURCE
    Przed glibc 2.12:
        _BSD_SOURCE || _XOPEN_SOURCE >= 500

OPIS

Te funkcje zwracają zakończony bajtem null łańcuch znaków zawierający nazwę bezwzględnej ścieżki do bieżącego katalogu roboczego procesu wywołującego. Nazwa ścieżki jest zwracana jako wynik funkcji i poprzez argument buf, jeśli jest obecny. Funkcja getcwd() kopiuje nazwę bezwzględnej ścieżki dostępu bieżącego katalogu roboczego do tablicy wskazywanej przez buf, która to tablica ma długość size. Jeśli nazwa bieżącej bezwzględnej ścieżki dostępu wymaga bufora dłuższego niż size elementów, to zwracane jest NULL, a errno jest ustawiane na ERANGE; aplikacja powinna sprawdzać, czy nie wystąpił ten błąd, i przydzielać większy bufor, jeżeli jest to potrzebne. Jako rozszerzenie standardu POSIX.1-2001, wersja glibc funkcji getcwd() przydziela bufor dynamicznie korzystając z malloc(3), jeśli buf jest równe NULL. W tym przypadku przydzielony bufor ma długość size, chyba że size jest równe zero, co oznacza że buforowi buf jest przydzielane tyle pamięci, ile potrzeba. Program wywołujący powinien zwolnić zwrócony bufor, wywołując free(3). get_current_dir_name() przydzieli za pomocą malloc(3) tablicę dostatecznie dużą, aby przechować bezwzględną nazwę bieżącego katalogu. Jeśli zmienna środowiskowa PWD jest ustawiona, a jej wartość prawidłowa, to zostanie zwrócona ta wartość. Program wywołujący powinien zwolnić zwrócony bufor, wywołując free(3). getwd() nie przydziela żadnej pamięci za pomocą malloc(3). Argument buf powinien być wskaźnikiem do tablicy o długości co najmniej PATH_MAX bajtów. Jeśli długość bezwzględnej ścieżki do bieżącego katalogu roboczego łącznie z końcowym bajtem null przekracza PATH_MAX bajtów, to zwracany jest NULL i errno jest ustawiane na ENAMETOOLONG. (Należy zwrócić uwagę, że PATH_MAX nie musi być stałą określaną podczas kompilacji; co więcej może ona zależeć od systemu plików, patrz pathconf(3)). Ze względu na przenośność i bezpieczeństwo używanie getwd() nie jest zalecane.

WARTOŚĆ ZWRACANA

On success, these functions return a pointer to a string containing the pathname of the current working directory. In the case of getcwd() and getwd() this is the same value as buf. W przypadku błędu funkcje te zwracają NULL, jednocześnie ustawiając errno, wskazujące na rodzaj błędu. Zawartość tablicy wskazywanej przez buf w przypadku błędu jest nieokreślona.

BŁĘDY

EACCES

Brak praw do odczytu lub przeszukiwania składnika nazwy pliku.

EFAULT

buf wskazuje na niewłaściwy adres.

EINVAL

Argument size jest zerowy, a buf nie jest wskaźnikiem NULL.

EINVAL

getwd(): buf jest równy NULL.

ENAMETOOLONG

getwd(): Rozmiar zakończonej znakiem null pełnej nazwy katalogu roboczego przekracza PATH_MAX bajtów.

ENOENT

Bieżący katalog roboczy został skasowany.

ENOMEM

Brak pamięci.

ERANGE

Argument size jest mniejszy od długości pełnej nazwy katalogu roboczego, włączając w to końcowy bajt null. Należy przydzielić większą tablicę i spróbować ponownie.

ATRYBUTY

Informacje o pojęciach używanych w tym rozdziale można znaleźć w podręczniku attributes(7).

Interfejs	Atrybut	Wartość
getcwd(), getwd()	Bezpieczeństwo wątkowe	MT-Safe
get_current_dir_name()	Bezpieczeństwo wątkowe	MT-Safe env

STANDARDY

getcwd() jest zgodna z POSIX.1-2001. Należy jednak zauważyć, że POSIX.1-2001 nie określa zachowania funkcji getcwd(), jeśli buf jest równy NULL. getwd() jest oznaczona jako przestarzała w POSIX.1-2001. POSIX.1-2008 usuwa definicję getwd(). Zamiast niej należy używać getcwd(). POSIX.1-2001 nie określa żadnych błędów dla getwd(). get_current_dir_name() jest rozszerzeniem GNU.

UWAGI

Pod Linuksem funkcje te używają wywołania systemowego getcwd() (dostępnego od wersji 2.1.92 Linuksa). W starszych systemach mogły odpytywać /proc/self/cwd. Gdy nie ma ani funkcji systemowej, ani systemu plików proc, wywoływana jest implementacja ogólna. Jedynie w takiej sytuacji wywołanie tych funkcji może pod Linuksem zwrócić w razie niepomyślnego zakończenia błąd EACCES. Funkcje te są często używane do zapamiętywania położenia bieżącego katalogu roboczego w celu późniejszego powrotu do niego. Gdy dostępnych jest dostatecznie wiele deskryptorów plików, otwarcie bieżącego katalogu (".") i wywołanie fchdir(2), aby do niego wrócić, jest zazwyczaj szybszą i bardziej niezawodną alternatywą, zwłaszcza na platformach innych niż Linux.

Różnice biblioteki C/jądra

Jądro Linuksa dostarcza wywołania systemowego getcwd, które jeśli jest to możliwe, będzie używane przez funkcje opisane w tym podręczniku. Wywołanie to przyjmuje takie same argumenty, jak funkcja biblioteczna o tej samej nazwie, ale długość zwracanej wartości jest ograniczona do PATH_MAX bajtów. (Przed wersją 3.12 Linuksa, ograniczeniem długości zwracane wartości był rozmiar strony systemowej. W przypadku wielu architektur sprzętowych PATH_MAX i rozmiar strony są sobie równe i wynoszą 4096, ale jest kilka architektur, które mają większy rozmiar strony). Jeśli długość ścieżki bieżącego katalogu roboczego przekracza ten limit, to wywołanie systemowe zwraca błąd ENAMETOOLONG. W takim przypadku funkcje biblioteczne przechodzą do alternatywnej (wolniejszej) implementacji zwracającej pełną nazwę ścieżki. Jeśli bieżący katalog roboczy nie znajduje się poniżej głównego katalogu bieżącego procesu (na przykład ponieważ ustawił nowy katalog główny systemu plików za pomocą chroot(2), ale nie zmienił swojego katalogu bieżącego na ten nowy katalog główny), to od Linuksa 2.6.36 zwrócona ścieżka zostanie poprzedzona napisem "(unreachable)". Takie zachowanie może być także spowodowane przez użytkownika nieuprzywilejowanego zmieniającego bieżący katalog do innej przestrzeni nazw montowania. Podczas pracy z ścieżkami pochodzącymi z niezaufanych źródeł programy wywołujące te funkcje powinny rozważyć sprawdzanie, czy zwrócona ścieżka zaczyna się od znaku "/", czy od znaku "(", aby uniknąć interpretowania niedostępnych ścieżek jako ścieżek względnych.

BŁĘDY

Poacząwszy od tej zmiany w Linuksie 2.6.36, która w przypadkach powyżej opisanych dodawała prefiks "(unreachable)", implementacja glibc funkcji getcwd() stała się niezgodna ze standardem POSIX i zwracała względną ścieżkę, mimo że API wymagało ścieżki bezwzględnej. Zostało to naprawione w glibc 2.27: wywołanie getcwd() z takiego katalogu bieżącego zwróci błąd ENONET.

ZOBACZ TAKŻE

pwd(1), chdir(2), fchdir(2), open(2), unlink(2), free(3), malloc(3)

TŁUMACZENIE

Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Andrzej Krzysztofowicz <[email protected]> i Robert Luberda <[email protected]> Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji można uzyskać zapoznając się z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI. Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej [email protected]