oracular (3) getcwd.3.gz

Provided by: manpages-pl-dev_4.23.1-1_all bug

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]);

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

       ┌───────────────────────────────────────────────────────────┬────────────────────────┬───────────────────┐
       │InterfejsAtrybutWartość           │
       ├───────────────────────────────────────────────────────────┼────────────────────────┼───────────────────┤
       │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  ⟨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⟩.