Provided by: manpages-pl-dev_20060617-3_all bug

NAZWA

       semop, semtimedop - operacje na semaforach

SK/LADNIA

       #include <sys/types.h>
       #include <sys/ipc.h>
       #include <sys/sem.h>

       int semop(int semid, struct sembuf *sops, unsigned nsops);

       int  semtimedop(int  semid, struct sembuf *sops, unsigned nsops, struct
       timespec *timeout);

OPIS

       Semafor jest reprezentowany za pomoc anonimowej  struktury  zawierajcej
       nastpujce pola:

           unsigned short  semval;   /* warto semafora */
           unsigned short  semzcnt;  /* # oczekiwanie na  zero */
           unsigned short  semncnt;  /* # oczekiwanie na zwikszenie */
           pid_t           sempid;   /* proces, ktory wykonal ost. op. */

       Funkcja  semop  wykonuje  operacje  na  wybranych  semaforach z zestawu
       wskazywanego przez semid.  Kady z nsops elementow  tablicy  wskazywanej
       przez  parametr sops okrela operacj, ktora ma by wykonana na semaforze.
       Struktura struct sembuf zawiera nastpujce pola:

           unsigned short sem_num;        /* numer semafora */
           short sem_op;                  /* operacja na semaforze */
           short sem_flg;                 /* dodatkowe znaczniki operacji */

       W  sem_flg  mog  zosta  ustawione  znaczniki  operacji:  IPC_NOWAIT   i
       SEM_UNDO.   Jeli  operacja  jest  opatrzona  znacznikiem  SEM_UNDO,  to
       zostanie cofnita w chwili, gdy proces zakoczy dzialanie.

       Zestaw operacji zawartych w sops jest wykonywany  atomowo,  to  znaczy,
       operacje  s  wykonywane jednoczenie i tylko wtedy, gdy wszystkie mog by
       jednoczenie wykonywane.  Zachowanie funkcji systemowej w sytuacji,  gdy
       nie wszystkie operacje mog by wykonane natychmiast, zaley od ustawienia
       znacznika IPC_NOWAIT w poszczegolnych polach sem_flg,  jak  to  opisano
       poniej.

       Kada  z  nich jest wykonywana na sem_num-tym semaforze w zestawie, przy
       czym pierwszy semafor ma  numer  0.   Istniej  trzy  rodzaje  operacji,
       rozroniane na podstawie wartoci sem_op.

       Jeli  sem_op  jest  liczb  dodatni, to warto semafora (semval) zostanie
       zwikszona o t liczb. Ponadto, jeli zostal przekazany znacznik SEM_UNDO,
       wowczas  system  zaktualizuje  licznik zmian (semadj) tego semafora dla
       procesu Operacja ta nigdy  nie  powoduje  wstrzymania  procesu.  Proces
       wywolujcy funkcj musi mie prawo do modyfikacji zestawu semaforow.

       Jeli  sem_op  jest  rowne  0,  proces musi mie prawo do odczytu zestawu
       semaforow.  Jest to operacja "oczekiwania na zero" (wait-for-zero): gdy
       semval  ma  warto  0,  operacja  moe  by  kontynuowana bezzwlocznie.  W
       przeciwnym razie, jeli w sem_flg przekazany zostal znacznik IPC_NOWAIT,
       wowczas  funkcja  systemowa zglosi bld, za zmienna errno przyjmie warto
       EAGAIN (i adna z operacji z sops nie zostanie wykonana).   Jeli  proces
       zostanie   wstrzymany  przez  system,  wowczas  warto  semzcnt  (liczby
       procesow oczekujcych na osignicie przez semafor wartoci zero)  zostanie
       zwikszona  o  1.  Proces  bdzie  zawieszony  a do chwili, gdy spelniony
       zostanie jeden z poniszych warunkow:

       o      semval osignie warto 0;  wowczas  warto  pola  semzcnt  zostanie
              zmniejszona o 1.

       o      Zestaw semaforow zostanie usunity: system zglosi bld, przypisujc
              zmiennej errno warto EIDRM.

       o      Proces  wywolujcy  funkcj  przechwyci  sygnal:   warto   semzcnt
              zostanie   zmniejszona   o   1,  natomiast  system  zglosi  bld,
              przypisujc zmiennej errno warto EINTR.

       Jeli sem_op ma warto  mniejsz  od  0,  to  proces  musi  mie  prawo  do
       modyfikacji  zestawu semaforow. Jeli wowczas warto semafora semval jest
       wiksza lub  rowna  wartoci  bezwzgldnej  sem_op,  to  operacja  moe  by
       kontynuowana bezzwlocznie: warto semafora semval zostanie zmniejszona o
       warto bezwzgldn sem_op.  Ponadto, jeli  przekazano  znacznik  SEM_UNDO,
       wowczas   system   zaktualizuje  licznik  zmian  semafora  dla  procesu
       (semadj).  Jeli warto bezwzgldna sem_op jest  wiksza  ni  semval,  a  w
       sem_flg  przekazano  znacznik  IPC_NOWAIT, system zglosi bld przypisujc
       zmiennej errno warto EAGAIN (i adna z operacji   z  sops  nie  zostanie
       wykonana).   W przeciwnym wypadku semncnt (licznik procesow oczekujcych
       na zwikszenie wartoci tego semafora) zostanie zwikszony o 1. Proces moe
       by wznowiony w nastpujcych sytuacjach:

       o      semval  osignie warto wiksz lub rown wartoci bezwzgldnej sem_op;
              wtedy  warto  semncnt  zostanie  zmniejszona  o  1,   za   warto
              bezwzgldna  z sem_op zostanie odjta od semval .  Jeli przekazany
              zostal znacznik SEM_UNDO , to system zaktualizuje licznik  zmian
              semafora dla procesu (semadj).

       o      Zestaw zostanie usunity z systemu: funkcja systemowa zglosi bld,
              przypisujc zmiennej errno warto EIDRM.

       o      Proces  wywolujcy  funkcj  przechwyci  sygnal:   warto   semncnt
              zostanie  zmniejszona  o  1,  natomiast funkcja systemowa zglosi
              bld, przypisujc zmiennej errno warto EINTR.

       Jeli operacja zostanie zakoczona pomylnie, to wartoci sempid  kadego  z
       semaforow wyszczegolnionych w tablicy wskazywanej przez sops przypisany
       zostanie identyfikator procesu (PID), ktory  wywolal  semop.   Ponadto,
       polu  sem_otime  przypisany zostanie aktualny czas.  Funkcja semtimedop
       zachowuje si tak samo jak funkcja semop, poza tym e w tych  przypadkach
       gdy  proces  wywolujcy  by  spal,  czas trwania spania jest ograniczony
       przez czas  okrelony  w  strukturze  timespec,  do  ktorej  adres  jest
       przekazywany w parametrze timeout.  Jeli osignito okrelony limit czasu,
       to wywolanie systemowe zwraca bld, ustawiajc errno na EAGAIN (i adna  z
       operacji  w  sops  nie  jest  wykonywana).  Jeeli parametr timeout jest
       NULL, to semtimedop zachowuje si dokladnie tak samo jak semop.

WARTO ZWRACANA

       Jeli operacja zakoczy si  pomylnie,  wowczas  funkcja  zwroci  0,  a  w
       przeciwnym  wypadku  zwroci -1, przypisujc zmiennej errno kod okrelajcy
       rodzaj bldu.

B/LDY

       Po niepomylnym zakoczeniu, zmienna errno przyjmie  jedn  z  nastpujcych
       wartoci:

       E2BIG  Warto   nsops   przekracza   SEMOPM,  maksymaln  liczb  operacji
              wykonywanych w jednym wywolaniu.

       EACCES Proces  nie  ma  uprawnie  potrzebnych  do  wykonania  jednej  z
              podanych operacji.

       EAGAIN Operacja  opatrzona  znacznikiem IPC_NOWAIT w sem_flg nie moe by
              natychmiast  wykonana  lub  uplynl  limit   czasu   okrelony   w
              parametrze timeout.

       EFAULT Adres wskazywany przez sops jest niedostpny.

       EFBIG  Numer  semafora  sem_num, do ktorego odnosi si jedna z operacji,
              jest mniejszy od 0 albo wikszy lub  rowny  liczbie  semaforow  w
              zestawie.

       EIDRM  Zestaw zostal usunity z systemu.

       EINTR  Podczas  oczekiwania  na  wykonanie  operacji proces przechwycil
              sygnal.

       EINVAL Zestaw semaforow nie istnieje lub warto semid jest mniejsza od 0
              lub warto nsops nie jest liczb dodatni.

       ENOMEM Brak  pamici  na  zapamitanie  zmian  wywolanych  przez  operacj
              (znacznik SEM_UNDO w sem_flg).

       ERANGE Dla pewnej operacji  warto  sem_op+semval  przekroczyla  SEMVMX,
              zalen od implementacji maksymaln warto semval.

UWAGI

       Struktury   sem_undo  nie  s  dziedziczone  poprzez  wywolania  funkcji
       systemowej  fork(2),  ale  s  dziedziczone  poprzez  wywolania  funkcji
       systemowej execve(2).

       semop   nie  jest  nigdy  automatycznie  uruchamiana  ponownie  po  jej
       przerwaniu  przez  funkcj  obslugi  sygnalu,  niezalenie   od   ustawie
       znacznika SA_RESTART podczas tworzenia funkcji obslugi sygnalu.

       semadj jest przypisan procesowi liczb calkowit, ktora stanowi po prostu
       (ujemny)  licznik  wszystkich  operacji  na  semaforach  wykonanych   z
       podaniem  znacznika  SEM_UNDO.  Podczas bezporedniego nadawania wartoci
       semaforowi za pomoc polece SETVAL lub SETALL dla semctl(2), odpowiednie
       wartoci semadj dla wszystkich procesow s zerowane.

       Wartoci  semval,  sempid, semzcnt i semnct dla semafora mona odczyta za
       pomoc odpowiednich wywola semctl(2).

       Wywolania semop dotycz nastpujce ograniczenia zasobow:

       SEMOPM Maksymalna liczba operacji,  ktore  mog  by  wykonane  w  jednym
              wywolaniu semop: (32).

       SEMVMX Maksymalna   dozwolona  warto  semval:  zaley  od  implementacji
              (32767).

       Implementacja w systemie Linux nie  naklada  wewntrznych  ogranicze  na
       maksymaln  zmian  wartoci semafora podczas zakoczenia procesu (SEMAEM),
       na ogolnosystemow liczb struktur przechowujcych informacje  o  zmianach
       stanu  semaforow  (SEMMNU), ani na maksymaln dla procesu liczb struktur
       przechowujcych informacje o zmianach stanu semaforow.

USTERKI

       Gdy proces koczy dzialanie, zestaw skojarzonych z nim  struktur  semadj
       jest   wykorzystywany   do  cofnicia  efektow  wszystkich  operacji  na
       semaforach, ktore ten proces wykonal z ustawionym znacznikiem SEM_UNDO.
       Wprowadza  to  trudno:  jeeli  jedna  (lub  wicej)  sporod  tych  zmian
       semaforow spowodowalby prob zmniejszenia wartoci semafora poniej  zera,
       to  co  implementacja  powinna uczyni?  Jednym z moliwych podej do tego
       zadadnienia moglo by by zablokowanie  do  chwili,  gdy  przeprowadzenie
       wszystkich  zmian  semaforow  bdzie moliwe.  Jest to jednake niepodane,
       gdy  spowodowaloby  wymuszenie  zablokowania  zakoczenia   procesu   na
       dowolnie dlugi okres.  Inn moliwoci jest zignorowanie wszystkich takich
       zmian semaforow (nieco analogiczne do niepomylnego zakoczenia, gdy  dla
       operacji  na  semaforze podany jest znacznik IPC_NOWAIT).  Linux przyjl
       trzecie rozwizanie: zmniejszenie wartoci semafora na tyle, na ile  jest
       to  moliwe  (tzn.  do  zera)  i umoliwienie natychmiastowej kontynuacji
       koczenia dzialania procesu.

ZGODNE Z

       SVr4, SCID.  SVr4 dokumentuje dodatkowe kody  bldow:  EINVAL,  EFBIG  i
       ENOSPC.

ZOBACZ TAKE

       ipc(5), semctl(2), semget(2), sigaction(2)

INFORMACJE O T/LUMACZENIU

       Powysze  tlumaczenie  pochodzi z nieistniejcego ju Projektu Tlumaczenia
       Manuali i moe nie by aktualne. W razie zauwaenia ronic  midzy  powyszym
       opisem  a  rzeczywistym  zachowaniem  opisywanego programu lub funkcji,
       prosimy o zapoznanie si z oryginaln (angielsk) wersj strony podrcznika.