getcwd(3)

NAZWA
getcwd, getwd, get_current_dir_name - odczytuje bieżący katalog roboczy

BIBLIOTEKA
Standardowa biblioteka C (libc, -lc)

SKŁADNIA
#include <unistd.h>

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

[[przestarzałe]] char *getwd(char buf[PATH_MAX]);

    Wymagane ustawienia makr biblioteki glibc (patrz feature_test_macros(7)):

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
Jeśli się zakończą pomyślnie, to te funkcje zwracają wskaźnik do łańcucha znaków zawierającego nazwę ścieżki do bieżącego katalogu roboczego, W przypadku getcwd() oraz getwd() jest to ten sam wskaźnik, co przekazany w argumencie 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-bezpieczne
get_current_dir_name() | Bezpieczeństwo wątkowe | MT-bezpieczne env

WERSJE
POSIX.1-2001 nie określa zachowania funkcji getcwd(), jeśli buf jest równy NULL.

POSIX.1-2001 nie definiuje żadnych błędów dla getwd().

WERSJE

  Różnice biblioteki C/jądra
Jądro Linux dostarcza wywołanie systemowe 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 zwracanej 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 ze ścieżkami pochodzącymi z niezaufanych źródeł, programy wywołujące te funkcje (przed glibc 2.27) lub surowe wywołanie systemowe getcwd() 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.

STANDARDY

getcwd()
    POSIX.1-2008.

get_current_dir_name()
    GNU.

getwd()
    Brak.

HISTORIA

getcwd()
    POSIX.1-2001.

getwd()
    POSIX.1-2001, lecz oznaczone jako LEGACY (przestarzałe). Usunięte w POSIX.1-2008. Należy używać w zamian getcwd().

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.

UWAGI
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.

USTERKI
Począ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
Tłumaczenie niniejszej strony podręcznika: Andrzej Krzysztofowicz <ankry@green.mf.pg.gda.pl>, Robert Luberda <robert@debian.org> i Michał Kułach <michal.kulach@gmail.com>

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 (https://www.gnu.org/licenses/gpl-3.0.html) lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.

Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej manpages-pl-list@lists.sourceforge.net.