table of contents
- bookworm 1:4.18.1-1
- bookworm-backports 1:4.24.0-2~bpo12+1
- testing 1:4.24.0-2
- unstable 1:4.25.0-1
getcwd(3) | Library Functions Manual | 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(char buf[.size], size_t size); char *get_current_dir_name(void);
[[przestarzałe]] 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¶
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 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¶
Autorami polskiego tłumaczenia niniejszej strony podręcznika są: 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 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.
2 maja 2024 r. | Linux man-pages 6.8 |