link(2)

NAZWA
link, linkat - tworzy kolejną nazwę pliku

BIBLIOTEKA
Standardowa biblioteka C (libc, -lc)

SKŁADNIA
#include <unistd.h>

int link(const char *oldpath, const char *newpath);

#include <fcntl.h>           /* Definicja stałych AT_* */
#include <unistd.h>

int linkat(int olddirfd, const char *oldpath,
           int newdirfd, const char *newpath, int flags);

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

linkat():
    Od glibc 2.10:
        _POSIX_C_SOURCE >= 200809L
    Przed glibc 2.10:
        _ATFILE_SOURCE

OPIS
link() tworzy nowe dowiązanie (nazywane też dowiązaniem zwykłym albo twardym) do istniejącego pliku.

Jeśli plik newpath już istnieje, to nie będzie nadpisany.

Ta nowa nazwa może być używana dokładnie tak samo jak stara, w dowolnych operacjach; obie nazwy odnoszą się do tego samego pliku (i w związku z tym mają te same uprawnienia i własność). Nie można też powiedzieć, która nazwa jest „oryginalna”.

  linkat()
Wywołanie systemowe linkat() operuje w dokładnie taki sam sposób jak link(), z wyjątkiem różnic opisanych tutaj.

Jeśli ścieżka podana w oldpath jest względna, jest ona interpretowana względem katalogu, do którego odnosi się deskryptor pliku olddirfd (zamiast względem bieżącego katalogu roboczego procesu wywołującego, jak ma to miejsce w link() w przypadku ścieżek względnych).

Jeśli oldpath jest względna, a olddirfd ma wartość specjalną AT_FDCWD, to oldpath jest interpretowana względem bieżącego katalogu roboczego procesu wywołującego (czyli tak jak robi to link()).

Jeśli oldpath jest bezwzględna, to olddirfd jest ignorowane.

Interpretacja newpath jest taka sama jak oldpath, z tym wyjątkiem, że ścieżka względna jest interpretowana względem katalogu, do którego odnosi się deskryptor pliku newdirfd.

Następujące wartości mogą być zsumowane bitowo (OR) we flags:

AT_EMPTY_PATH (od Linuksa 2.6.39)
    Jeśli oldpath jest pustym łańcuchem, tworzy dowiązanie do pliku, do którego odnosi się olddirfd (który mógł być pozyskany za pomocą znacznika O_PATH open(2)). W takim przypadku olddirfd może odnosić się do dowolnego typu pliku, z wyjątkiem katalogu. Zwykle nie zadziała to, gdy licznik dowiązań wskazuje zero (pliki utworzone z O_TMPFILE i bez O_EXCL są wyjątkiem). Wywołujący musi mieć przywilej CAP_DAC_READ_SEARCH (ang. capability), aby użyć tego znacznika. Niniejszy znacznik jest typowo linuksowy; należy zdefiniować _GNU_SOURCE, aby pozyskać jego definicję.

AT_SYMLINK_FOLLOW (od Linuksa 2.6.18)
    Domyślnie, linkat(), nie rozwija oldpath, jeśli jest ona dowiązaniem symbolicznym (jak link()). Można podać znacznik AT_SYMLINK_FOLLOW we flags, aby oldpath została rozwiązana, jeśli jest dowiązaniem symbolicznym. Jeśli zamontowano procfs, może posłużyć to za alternatywę do AT_EMPTY_PATH, podobnie do:

        linkat(AT_FDCWD, "/proc/self/fd/<fd>", newdirfd,
               newname, AT_SYMLINK_FOLLOW);

Przed Linuksem 2.6.18, argument flags nie był używany; wymagane było podanie jego wartości równej 0.

Więcej informacji o potrzebie wprowadzenia linkat() można znaleźć w podręczniku openat(2).

WARTOŚĆ ZWRACANA
Po pomyślnym zakończeniu zwracane jest zero. Po błędzie zwracane jest -1 i ustawiane errno, wskazując błąd.

BŁĘDY

EACCES
    Odmówiono zapisu do katalogu zawierającego newpath lub brak uprawnienia przeszukiwania dla jednego z katalogów w składowej ścieżek oldpath lub newpath (zob. też path_resolution(7)).

EDQUOT
    Przydział bloków dyskowych użytkownika dotyczący systemu plików został wyczerpany.

EEXIST
    newpath już istnieje.

EFAULT
    oldpath lub newpath wskazuje poza dostępną dla użytkownika przestrzeń adresową.

EIO Wystąpił błąd wejścia/wyjścia.

ELOOP
    Podczas rozwiązywania oldpath lub newpath napotkano zbyt wiele dowiązań symbolicznych.

EMLINK
    Plik do którego odnosi się oldpath, osiągnął już maksymalną liczbę prowadzących do niego dowiązań zwykłych. Przykładowo, w systemie plików ext4(5) bez cechy dir_index, limit liczby dowiązań zwykłych wynosi 65 000; na btrfs(5) jest to 65 535 dowiązań.

ENAMETOOLONG
    oldpath lub newpath było zbyt długie.

ENOENT
    Składnik katalogu w oldpath lub newpath nie istnieje, lub jest wiszącym dowiązaniem symbolicznym.

ENOMEM
    Brak pamięci jądra.

ENOSPC
    Na urządzeniu zawierającym plik nie ma miejsca na kolejny wpis w katalogu.

ENOTDIR
    Składnik oldpath lub newpath używany jako katalog nie jest w rzeczywistości katalogiem.

EPERM
    oldpath jest katalogiem.

EPERM
    System plików zawierający oldpath i newpath nie obsługuje tworzenia twardych dowiązań.

EPERM (od Linuksa 3.6)
    Wywołujący nie ma uprawnienia do utworzenia dowiązania zwykłego do tego pliku (zob. opis /proc/sys/fs/protected_hardlinks w proc_sys_fs(5)).

EPERM
    oldpath została oznaczona jako tylko do odczytu (immutable) lub tylko do nadpisu (append-only; zob FS_IOC_SETFLAGS(2const)).

EROFS
    Plik leży w systemie plików tylko do odczytu.

EXDEV
    oldpath i newpath nie są zamontowane w tym samym systemie plików (Linux dopuszcza montowanie systemu plików w wielu punktach, ale link() nie działa poprzez różne montowania, nawet gdy w obu miejscach zamontowano ten sam system plików).

Mogą wystąpić następujące dodatkowe błędy dla linkat():

EBADF
    oldpath (newpath) są względne, lecz olddirfd (newdirfd) nie wynosi ani AT_FDCWD, ani nie jest prawidłowym deskryptorem pliku.

EINVAL
    We flags podano nieprawidłową wartość znacznika.

ENOENT
    We flags podano AT_EMPTY_PATH, lecz wywołujący nie posiada przywileju CAP_DAC_READ_SEARCH (ang. capability).

ENOENT
    Próbowano utworzyć dowiązanie do pliku /proc/self/fd/NN, odnoszącego się do deskryptora liku utworzonego za pomocą

        open(path, O_TMPFILE | O_EXCL, mode);

    Zobacz open(2).

ENOENT
    Próbowano utworzyć dowiązanie do pliku /proc/self/fd/NN, odnoszącego się do pliku, który usunięto.

ENOENT
    oldpath jest ścieżką względną, a olddirfd odnosi się do usuniętego katalogu albo newpath jest ścieżką względną, a newdirfd odnosi się do usuniętego katalogu.

ENOTDIR
    oldpath jest względna, a olddirfd jest deskryptorem pliku odnoszącym się do pliku innego niż katalog; lub analogicznie dla newpath i newdirfd

EPERM
    We flags podano AT_EMPTY_PATH, oldpath jest łańcuchem pustym, a olddirfd odnosi się do katalogu.

WERSJE
POSIX.1-2001 twierdzi, że link() powinien rozwiązywać oldpath, jeśli jest ona dowiązaniem symbolicznym. Jednak od Linuksa 2.0, Linux tak nie czyni: jeśli oldpath jest dowiązaniem symbolicznym, to newpath jest tworzona jako dowiązanie zwykłe (twarde) do samego pliku dowiązania symbolicznego (tj. newpath staje się dowiązaniem symbolicznym do tego samego pliku, do którego odnosi się oldpath). Niektóre inne implementacje zachowują się w ten sam sposób co Linux. POSIX.1-2008 zmieniło specyfikację link(), czyniąc rozwiązywanie oldpath gdy jest to dowiązanie symboliczne, zależnym od implementacji. Aby uzyskać precyzyjną kontrolę nad traktowaniem dowiązań symbolicznych przy tworzeniu dowiązań zwykłych, należy korzystać z linkat().

  glibc
W starszych jądrach, gdy niedostępne jest linkat() funkcja opakowująca z biblioteki glibc z konieczności korzysta z link(), chyba że podano AT_SYMLINK_FOLLOW. Gdy oldpath i newpath są ścieżkami względnymi, glibc tworzy ścieżki w zależności od dowiązań symbolicznych w /proc/self/fd, które odnoszą się do argumentów olddirfd i newdirfd.

STANDARDY
POSIX.1-2024.

HISTORIA

link()
    4.3BSD, SVr4, POSIX.1-1988 (lecz zob. WERSJE).

linkat()
    POSIX.1-2008, glibc 2.4, Linux 2.6.16.

UWAGI
Dowiązania zwykłe (twarde), tworzone z pomocą link(), nie mogą wykraczać poza jeden system plików. W takich sytuacjach można użyć funkcji symlink(2).

USTERKI
Na systemach NFS, wartość zwracana może być nieprawidłowa w wypadku gdy serwer NFS dokonuje tworzenia dowiązania i umiera przed zakomunikowaniem tego faktu. Można użyć stat(2) aby dowiedzieć się, czy dowiązanie zostało utworzone.

ZOBACZ TAKŻE
ln(1), open(2), rename(2), stat(2), symlink(2), unlink(2), path_resolution(7), symlink(7)

TŁUMACZENIE
Tłumaczenie niniejszej strony podręcznika: Przemek Borys <pborys@dione.ids.pl>, Andrzej Krzysztofowicz <ankry@green.mf.pg.gda.pl> 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.