NAZWA¶

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

SKŁADNIA¶

#include <unistd.h>

char *getcwd(char *buf, size_t size);

char *getwd(char *buf);

char *get_current_dir_name(void);

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

get_current_dir_name():

getwd():

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.

If the current directory is not below the root directory of the current process (e.g., because the process set a new filesystem root using chroot(2) without changing its current directory into the new root), then, since Linux 2.6.36, the returned path will be prefixed with the string "(unreachable)". Such behavior can also be caused by an unprivileged user by changing the current directory into another mount namespace. When dealing with paths from untrusted sources, callers of these functions should consider checking whether the returned path starts with '/' or '(' to avoid misinterpreting an unreachable path as a relative path. This is no longer true under some C libraries; see NOTES.

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

ZGODNE Z¶

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¶

Under Linux, the function getcwd() is a system call (since 2.1.92). On older systems it would query /proc/self/cwd. If both system call and proc filesystem are missing, a generic implementation is called. Only in that case can these calls fail under Linux with EACCES.

Since a Linux 2.6.36 change that added "(unreachable)", the glibc getcwd() has failed to conform to POSIX and returned a relative path when the API contract requires an absolute path. With glibc 2.27 onwards this is corrected; calling getcwd() from such a path will now result in failure with ENOENT.

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.

ZOBACZ TAKŻE¶

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

O STRONIE¶

Angielska wersja tej strony pochodzi z wydania 4.16 projektu Linux man-pages. Opis projektu, informacje dotyczące zgłaszania błędów oraz najnowszą wersję oryginału można znaleźć pod adresem https://www.kernel.org/doc/man-pages/.

TŁUMACZENIE¶

Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Andrzej Krzysztofowicz <ankry@green.mf.pg.gda.pl> i Robert Luberda <robert@debian.org>

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.