NAZWA

       write - zapisuje do deskryptora pliku

SKŁADNIA

       #include <unistd.h>

       ssize_t write(int fd, const void *buf, size_t liczba);

OPIS

       write() zapisuje do liczba bajtów z bufora wskazanego przez buf do pliku określonego przez
       deskryptor pliku fd.

       Liczba bajtów zapisanych  może  być  mniejsza  niż  liczba  jeżeli,  na  przykład  nie  ma
       wystarczającej  ilości wolnej przestrzeni na urządzeniu fizycznym, lub zasoby RLIMIT_FSIZE
       zostały wyczerpane (patrz setrlimit(2)), wywołanie zostało przerwane przez obsługę sygnału
       po zapisaniu mniej niż liczba bajtów (spójrz również na pipe(7)).

       Dla  przeszukiwalnych plików (np. takie na których można użyć lseek(2), na przykład, pliki
       zwykłe  (regular))  zapis  ma  miejsce  w  danym  przesunięciu  pliku  (offsecie),  i   to
       przesunięcie  jest  zwiększane  o  ilość  aktualnie  zapisanych danych. Jeżeli plik został
       otwarty (open(2)) z O_APPEND, wtedy  przesunięciem  (offsetem)  jest  koniec  pliku  przed
       zapisem.   Dostosowanie   przesunięcia   pliku   i  operacja  zapisu  są  wykonywane  jako
       nierozdzielne (atomowe).

       Standard POSIX wymaga, aby read, który może nastąpić po write() zwrócił nowe dane. Prosimy
       zauważyć, że nie wszystkie systemy plików są zgodne z POSIX.

WARTOŚĆ ZWRACANA

       Po pomyślnym wykonaniu, zwracana jest liczba zapisanych bajtów (zero informuje, że nic nie
       zostało zapisane). Nie jest błędem, jeśli liczba ta  jest  mniejsza  niż  liczba  żądanych
       bajtów; może się to zdarzyć na przykład z powodu zapełnienia dysku. Zob. też UWAGI.

       W  razie  wystąpienia błędu zwracane jest -1 i ustawiana jest odpowiednia wartość zmiennej
       errno.

       Jeżeli liczba jest zerem a fd wskazuje na  zwykły  (regular)  plik,  wtedy  write()   może
       zwrócić status niepowodzenia jeżeli zostanie wykryty jeden z poniższych błędów. Jeżeli nie
       wykryto błędów lub nie dokonano próby wykrycia błędów, 0  zostanie  zwrócone  bez  żadnych
       innych  skutków.  Jeżeli  liczba  jest  zerem  a  fd odwołuje się do pliku innego typu niż
       zwykły (regular), skutki nie są sprecyzowane.

BŁĘDY

       EAGAIN Deskryptor pliku fd odwołuje się do gniazda i został  oznaczony  jako  nieblokujący
              (O_NONBLOCK), a zapis go zablokuje. Zob. open(2) aby dowiedzieć się więcej o fladze
              O_NONBLOCK.

       EAGAIN lub EWOULDBLOCK
              Deskryptor pliku fd odwołuje się do gniazda i został  oznaczony  jako  nieblokujący
              (O_NONBLOCK),  a  zapis  go  zablokuje.  POSIX.1-2001  pozwala  w  tej  sytuacji na
              zwrócenie błędu ale nie wymaga aby ta stała miała  taką  samą  wartość,  portowalna
              aplikacja powinna sprawdzać obie możliwości.

       EBADF  fd nie jest prawidłowym deskryptorem pliku lub nie jest otwarty do zapisu

       EDESTADDRREQ
              fd odwołuje się do gniazda datagramowego dla którego adres nie został ustalony przy
              użyciu connect(2).

       EDQUOT Kwota bloków dyskowych użytkownika  dotycząca  systemu  plików  zawierającego  plik
              wskazany przez fd została wyczerpana.

       EFAULT buf jest poza dostępną przestrzenią adresową.

       EFBIG  Dokonano   próby   zapisu  pliku  który  przekracza  zdefiniowane  w  implementacji
              maksymalne rozmiary pliku, rozmiary pliku procesu lub zapis na pozycję wykraczającą
              poza maksymalne dozwolone przesunięcie (offset).

       EINTR  Wywołanie  zostało  przerwane  przez  sygnał przed zapisaniem jakichkolwiek danych,
              patrz signal(7).

       EINVAL fd jest dołączony do obiektu nieodpowiedniego do  zapisu,  plik  został  otwarty  z
              flagą  O_DIRECT  i adres podany w buf bądź wartość liczba lub przesunięcie (offset)
              nie zostały odpowiednio dopasowane.

       EIO    Podczas modyfikacji i-węzła nastąpił niskopoziomowy błąd wejścia/wyjścia.

       ENOSPC Urządzenie zawierające plik wskazany przez fd nie ma miejsca na dane.

       EPERM  Operacja zablokowana przez zakluczenie pliku (ang. file seal); zob. fcntl(2).

       EPIPE  fd  jest  podłączony  do  potoku  (pipe)  lub  gniazda  (socket)  którego  końcówka
              odczytująca  jest zamknięta. Gdy taka sytuacja następuje, proces zapisujący również
              otrzyma sygnał  SIGPIPE. (Więc wartość zwracana przez write() jest  widziana  tylko
              wówczas gdy program obsługuje, blokuje lub ignoruje ten sygnał).

       Zależnie od obiektu podłączonego do fd, mogą także zajść inne (nieopisane) błędy.

ZGODNE Z

       SVr4, 4.3BSD, POSIX.1-2001.

       Pod  SVr4  EINTR  jest zwracane zarówno gdy po przerwaniu wywołania, dane zostały zapisane
       częściowo lub przed jakimkolwiek zapisem.

UWAGI

       Typy size_t i ssize_t to odpowiednio liczba całkowita bez i ze znakiem, zgodnie z POSIX.1.

       Pomyślny powrót z write() nie daje gwarancji,  że  dane  zostały  faktycznie  zapisane  na
       urządzeniu.  W  rzeczywistości,  w  niektórych  wadliwych  implementacjach,  nie  ma nawet
       pewności, że przestrzeń potrzebna  do  zapisu  została  pomyślnie  zarezerwowana.  Jedynym
       sposobem  aby  mieć  pewność,  że  dane  zostały  zapisane  jest  wywołanie   fsync(2)  po
       skończeniu zapisywania wszystkich danych przez write().

       Jeżeli write() zostanie przerwany przez obsługe  sygnału  przed  zapisaniem  jakichkolwiek
       danych,  wtedy  wywołanie  nie powiedzie się i zwracany jest błąd EINTR; jeżeli przerwanie
       nastąpi po zapisaniu co najmniej jednego bajtu danych, wywołanie powiedzie  się  i  zwróci
       ilość zapisanych bajtów danych.

       W  Linuksie,  write()  (i  podobne wywołania systemowe) mogą dokonać transferu co najwyżej
       0x7ffff000   (2   147   479   552)   bajtów,   zwracając   liczbę   bajtów    rzeczywiście
       przetransferowanych (jest to prawdziwe zarówno dla systemów 32 jak i 64-bitowych).

BŁĘDY

       Zgodnie  z  POSIX.1-2008/SUSv4  Section  XSI 2.9.7 ("Thread Interactions with Regular File
       Operations"):

           Wszystkie poniższe funkcje powinny być atomowe w  odniesieniu  do  innych  biorąc  pod
           uwagę   wyniki  określone  w  POSIX.1-2008,  gdy  działają  na  zwykłych  plikach  lub
           dowiązaniach symbolicznych: ...

       Spośród wymienionych tam dalej API  są  między  innymi  write()  i  writev(2).  I  spośród
       efektów,  które  powinny  być  atomowe  pomiędzy  wątkami  (i procesami) jest aktualizacja
       przesunięcia pliku. Jednak w Linuksie przed wersją 3.14 tak  się  nie  działo:  jeśli  dwa
       procesy  dzielące  otwarty  deskryptor  pliku   (zob. open(2)) przeprowadzały write() (lub
       writev(2)) w tym samym czasie, to operacje wejścia/wyjścia nie były atomowe w  odniesieniu
       do  aktualizacji  przesunięcia  pliku, co powodowało, że bloki danych wypisywane przez dwa
       procesy mogły się (nieprawidłowo) nakładać. Problem został naprawiony w Linuksie 3.14.

ZOBACZ TAKŻE

       close(2), fcntl(2), fsync(2), ioctl(2), lseek(2), open(2), pwrite(2), read(2),  select(2),
       writev(2), fwrite(3)

O STRONIE

       Angielska  wersja  tej  strony  pochodzi  z  wydania  4.07  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 man są: Artur Kruszewski
       <mazdac@gmail.com>,   Michał   Kułach   <michal.kulach@gmail.com>   i    Robert    Luberda
       <robert@debian.org>.

       Polskie  tłumaczenie jest częścią projektu manpages-pl; uwagi, pomoc, zgłaszanie błędów na
       stronie  http://sourceforge.net/projects/manpages-pl/.  Jest   zgodne   z   wersją    4.07
       oryginału.