getcwd(3) Library Functions Manual getcwd(3) NAZWA getcwd, getwd, get_current_dir_name - odczytanie biezacego katalogu roboczego BIBLIOTEKA Standardowa biblioteka C (libc, -lc) SKLADNIA #include char *getcwd(char buf[.size], size_t size); char *get_current_dir_name(void); [[deprecated]] 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 zwracaja zakonczony bajtem null lancuch znakow zawierajacy nazwe bezwzglednej sciezki do biezacego katalogu roboczego procesu wywolujacego. Nazwa sciezki jest zwracana jako wynik funkcji i poprzez argument buf, jesli jest obecny. Funkcja getcwd() kopiuje nazwe bezwzglednej sciezki dostepu biezacego katalogu roboczego do tablicy wskazywanej przez buf, ktora to tablica ma dlugosc size. Jesli nazwa biezacej bezwzglednej sciezki dostepu wymaga bufora dluzszego niz size elementow, to zwracane jest NULL, a errno jest ustawiane na ERANGE; aplikacja powinna sprawdzac, czy nie wystapil ten blad, i przydzielac wiekszy bufor, jezeli jest to potrzebne. Jako rozszerzenie standardu POSIX.1-2001, wersja glibc funkcji getcwd() przydziela bufor dynamicznie korzystajac z malloc(3), jesli buf jest rowne NULL. W tym przypadku przydzielony bufor ma dlugosc size, chyba ze size jest rowne zero, co oznacza ze buforowi buf jest przydzielane tyle pamieci, ile potrzeba. Program wywolujacy powinien zwolnic zwrocony bufor, wywolujac free(3). get_current_dir_name() przydzieli za pomoca malloc(3) tablice dostatecznie duza, aby przechowac bezwzgledna nazwe biezacego katalogu. Jesli zmienna srodowiskowa PWD jest ustawiona, a jej wartosc prawidlowa, to zostanie zwrocona ta wartosc. Program wywolujacy powinien zwolnic zwrocony bufor, wywolujac free(3). getwd() nie przydziela zadnej pamieci za pomoca malloc(3). Argument buf powinien byc wskaznikiem do tablicy o dlugosci co najmniej PATH_MAX bajtow. Jesli dlugosc bezwzglednej sciezki do biezacego katalogu roboczego lacznie z koncowym bajtem null przekracza PATH_MAX bajtow, to zwracany jest NULL i errno jest ustawiane na ENAMETOOLONG. (Nalezy zwrocic uwage, ze PATH_MAX nie musi byc stala okreslana podczas kompilacji; co wiecej moze ona zalezec od systemu plikow, patrz pathconf(3)). Ze wzgledu na przenosnosc i bezpieczenstwo uzywanie getwd() nie jest zalecane. WARTOSC 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 bledu funkcje te zwracaja NULL, jednoczesnie ustawiajac errno, wskazujace na rodzaj bledu. Zawartosc tablicy wskazywanej przez buf w przypadku bledu jest nieokreslona. BLEDY EACCES Brak praw do odczytu lub przeszukiwania skladnika nazwy pliku. EFAULT buf wskazuje na niewlasciwy adres. EINVAL Argument size jest zerowy, a buf nie jest wskaznikiem NULL. EINVAL getwd(): buf jest rowny NULL. ENAMETOOLONG getwd(): Rozmiar zakonczonej znakiem null pelnej nazwy katalogu roboczego przekracza PATH_MAX bajtow. ENOENT Biezacy katalog roboczy zostal skasowany. ENOMEM Brak pamieci. ERANGE Argument size jest mniejszy od dlugosci pelnej nazwy katalogu roboczego, wlaczajac w to koncowy bajt null. Nalezy przydzielic wieksza tablice i sprobowac ponownie. ATRYBUTY Informacje o pojeciach uzywanych w tym rozdziale mozna znalezc w podreczniku attributes(7). +-----------------------+--------------------------+-------------------+ |Interfejs | Atrybut | Wartosc | +-----------------------+--------------------------+-------------------+ |getcwd(), getwd() | Bezpieczenstwo watkowe | MT-bezpieczne | +-----------------------+--------------------------+-------------------+ |get_current_dir_name() | Bezpieczenstwo watkowe | MT-bezpieczne env | +-----------------------+--------------------------+-------------------+ WERSJE POSIX.1-2001 leaves the behavior of getcwd() unspecified if buf is NULL. POSIX.1-2001 does not define any errors for getwd(). WERSJE Roznice biblioteki C/jadra Jadro Linuksa dostarcza wywolania systemowego getcwd, ktore jesli jest to mozliwe, bedzie uzywane przez funkcje opisane w tym podreczniku. Wywolanie to przyjmuje takie same argumenty, jak funkcja biblioteczna o tej samej nazwie, ale dlugosc zwracanej wartosci jest ograniczona do PATH_MAX bajtow. (Przed wersja 3.12 Linuksa, ograniczeniem dlugosci zwracane wartosci byl rozmiar strony systemowej. W przypadku wielu architektur sprzetowych PATH_MAX i rozmiar strony sa sobie rowne i wynosza 4096, ale jest kilka architektur, ktore maja wiekszy rozmiar strony). Jesli dlugosc sciezki biezacego katalogu roboczego przekracza ten limit, to wywolanie systemowe zwraca blad ENAMETOOLONG. W takim przypadku funkcje biblioteczne przechodza do alternatywnej (wolniejszej) implementacji zwracajacej pelna nazwe sciezki. Jesli biezacy katalog roboczy nie znajduje sie ponizej glownego katalogu biezacego procesu (na przyklad poniewaz ustawil nowy katalog glowny systemu plikow za pomoca chroot(2), ale nie zmienil swojego katalogu biezacego na ten nowy katalog glowny), to od Linuksa 2.6.36 zwrocona sciezka zostanie poprzedzona napisem "(unreachable)". Takie zachowanie moze byc takze spowodowane przez uzytkownika nieuprzywilejowanego zmieniajacego biezacy katalog do innej przestrzeni nazw montowania. Podczas pracy z sciezkami pochodzacymi z niezaufanych zrodel programy wywolujace te funkcje powinny rozwazyc sprawdzanie, czy zwrocona sciezka zaczyna sie od znaku "/", czy od znaku "(", aby uniknac interpretowania niedostepnych sciezek jako sciezek wzglednych. STANDARDY getcwd() POSIX.1-2008. get_current_dir_name() GNU. getwd() None. HISTORIA getcwd() POSIX.1-2001. getwd() POSIX.1-2001, but marked LEGACY. Removed in POSIX.1-2008. Use getcwd() instead. Pod Linuksem funkcje te uzywaja wywolania systemowego getcwd() (dostepnego od wersji 2.1.92 Linuksa). W starszych systemach mogly odpytywac /proc/self/cwd. Gdy nie ma ani funkcji systemowej, ani systemu plikow proc, wywolywana jest implementacja ogolna. Jedynie w takiej sytuacji wywolanie tych funkcji moze pod Linuksem zwrocic w razie niepomyslnego zakonczenia blad EACCES. UWAGI Funkcje te sa czesto uzywane do zapamietywania polozenia biezacego katalogu roboczego w celu pozniejszego powrotu do niego. Gdy dostepnych jest dostatecznie wiele deskryptorow plikow, otwarcie biezacego katalogu (".") i wywolanie fchdir(2), aby do niego wrocic, jest zazwyczaj szybsza i bardziej niezawodna alternatywa, zwlaszcza na platformach innych niz Linux. USTERKI Poaczawszy od tej zmiany w Linuksie 2.6.36, ktora w przypadkach powyzej opisanych dodawala prefiks "(unreachable)", implementacja glibc funkcji getcwd() stala sie niezgodna ze standardem POSIX i zwracala wzgledna sciezke, mimo ze API wymagalo sciezki bezwzglednej. Zostalo to naprawione w glibc 2.27: wywolanie getcwd() z takiego katalogu biezacego zwroci blad ENONET. ZOBACZ TAKZE pwd(1), chdir(2), fchdir(2), open(2), unlink(2), free(3), malloc(3) TLUMACZENIE Autorami polskiego tlumaczenia niniejszej strony podrecznika sa: Andrzej Krzysztofowicz i Robert Luberda Niniejsze tlumaczenie jest wolna dokumentacja. Blizsze informacje o warunkach licencji mozna uzyskac zapoznajac sie z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje sie ZADNEJ ODPOWIEDZIALNOSCI. Bledy w tlumaczeniu strony podrecznika prosimy zglaszac na adres listy dyskusyjnej . Linux man-pages 6.06 31 pazdziernika 2023 r. getcwd(3)