Provided by: manpages-pl-dev_0.7-1_all bug

NAZWA

       getitimer, setitimer - pobranie i ustawienie wartości czasomierza

SKŁADNIA

       #include <sys/time.h>

       int getitimer(int which, struct itimerval *curr_value);
       int setitimer(int which, const struct itimerval *new_value,
                     struct itimerval *old_value);

OPIS

       Te  wywołania systemowe umożliwiają dostęp do czasomierzy (timerów) interwałowych, to jest
       timerów, które najpierw wygasają w pewnym punkcie w przyszłości, a potem  (opcjonalnie)  w
       regularnych  odstępach  czasu.  Po  wygaśnięciu  timera  wysyłany  jest  sygnał do procesu
       wywołującego, a następnie timer jest ponownie inicjowany podaną wartością interwału (jeśli
       jest niezerowa).

       Dostępne  są  trzy typy czasomierzy, podawane w argumencie which; każdy z nich mierzy czas
       według innego zegara i generuje inny sygnał, gdy upłynie czas ważności:

       ITIMER_REAL    Odlicza czas rzeczywisty. Po wygaśnięciu generuje sygnał SIGALRM.

       ITIMER_VIRTUAL Odlicza  czas  CPU  wykonywania  się  procesu  w  przestrzeni  użytkownika.
                      (Obliczenia  obejmują  czas  CPU  zużyty przez wszystkie wątki procesu). Po
                      każdorazowym wygaśnięciu generowany jest sygnał SIGVTALRM.

       ITIMER_PROF    Odlicza całkowity (tj. zarówno  w  przestrzeni  użytkownika,  jak  i  jądra
                      systemu)  czas  CPU wykonywania się  procesu. (Obliczenia obejmują czas CPU
                      zużyty  przez  wszystkie  wątki  procesu).  Po   każdorazowym   wygaśnięciu
                      generowany jest sygnał SIGPROF.

                      W  powiązaniu  z  ITIMER_VIRTUAL  ten  czasomierz  zwykle jest  używany  do
                      profilowania  czasu  używanego  przez  aplikację  zarówno   w   przestrzeni
                      użytkownika, jak i jądra.

       Proces ma tylko po jednym timerze każdego z tych trzech typów.

       Wartości czasomierza są zdefiniowane za pomocą następujących struktur:

           struct itimerval {
               struct timeval it_interval; /* Interwał czasomierza periodycznego */
               struct timeval it_value;    /* Czas do następnego wygaśnięcia */
           };

           struct timeval {
               long tv_sec;                /* sekundy */
               long tv_usec;               /* mikrosekundy */
           };

   getitimer()
       Funkcja  getitimer()  wypełnia  bufor  wskazywany  przez  curr_value  bieżącym  wskazaniem
       czasomierza podanego w parametrze which.

       Do struktury it_value jest wpisywana ilość czasu,  który  pozostał  podanemu  timerowi  do
       następnego  wygaśnięcia.  Wartość  ta  się  zmienia  podczas odliczania przez czasomierz i
       zostanie ustawiona na it_interval, gdy timer wygaśnie. Obie wartości it_value  równe  zero
       oznaczają, że podany timer nie jest obecnie aktywny.

       Struktura  w it_interval jest ustawiana na odstęp pomiędzy kolejnymi wygaśnięciami timera.
       Oba pola w it_interval równe zero oznaczają timer  jednorazowy  (czyli,  że  wygasa  tylko
       raz).

   getitimer()
       Funkcja  setitimer(2) włącza lub wyłącza timer podany w argumencie which, ustawiając timer
       na wartość podaną w new_value. Jeśli old_value jest różne od  NULL,  to  bufor,  na  który
       wskazuje,  jest  używany  do  zwrócenia  poprzedniej  wartości  timera  (to  jest  ta sama
       informacja, którą zwraca getitimer()).

       Jeśli którekolwiek pole w new_value.it_value jest niezerowe, to timer  jest  aktywowany  i
       ustawiony   tak,   żeby   początkowo   wygasł   w   podanym   czasie.  Jeśli  oba  pola  w
       new_value.it_value mają wartość zero, to timer jest wyłączony.

       Pole new_value.it_interval określa nowy interwał dla timera, jeśli oba pola w nim  zawarte
       mają wartość zero, to jest to timer jednorazowy.

WARTOŚĆ ZWRACANA

       Po  pomyślnym  zakończeniu  zwracane  jest zero. Po błędzie zwracane jest -1 i odpowiednio
       ustawiane errno.

BŁĘDY

       EFAULT new_value, old_value lub curr_value nie jest poprawnym wskaźnikiem.

       EINVAL which nie jest jednym  z  ITIMER_REAL,  ITIMER_VIRTUAL  lub  ITIMER_PROF  albo  (od
              Linuksa  2.6.22)  jedno  z  pól  tv_usec  w  strukturze wskazywanej przez new_value
              zawiera wartość spoza zakresu od 0 do 999999.

ZGODNE Z

       POSIX.1-2001, SVr4, 4.4BSD (to wywołanie najpierw pojawiło  się  w  4.2BSD).  POSIX.1-2008
       uznaje  getitimer()  i  setitimer()  za  przestarzałe, zalecając zamiast nich używanie API
       POSIX-owych czasomierzy (timer_gettime(2), timer_settime(2) i tak dalej).

UWAGI

       Ważność czasomierzy nigdy nie upływa przed zadanym  czasem,  natomiast  może  ona  upłynąć
       jakiś  (krótki) czas później, co zależy od rozdzielczości zegara systemowego  i obciążenia
       systemu, patrz time(7) (patrz także rozdział USTERKI poniżej). Jeśli czas ważności upływa,
       gdy  proces  jest  aktywny  (jest to zawsze prawda dla ITIMER_VIRTUAL), to sygnał zostanie
       dostarczony natychmiast po wygenerowaniu.

       Dziecko utworzone przez fork(2) nie dziedziczy  timerów  interwałowych  rodzica.  Jednakże
       timery te są zachowywane przez execve(2).

       POSIX.1  nie  określa  interakcji  pomiędzy  setitimer()  i  trzema interfejsami alarm(2),
       sleep(3) oraz usleep(3).

       Standardy nie określają znaczenia poniższego wywołania:

           setitimer(which, NULL, &old_value);

       Wiele systemów (Solaris, systemy BSD i być może również inne) traktuje to jako  równoważne
       z:

           getitimer(which, &old_value);

       Pod  Linuksem  jest  to  odpowiednikiem wywołania, w którym pola new_value są ustawione na
       zero, to jest czasomierz jest wyłączany. Prosimiy o nieużywanie tej  właściwości  Linuska:
       jest nieprzenośna i niepotrzebna.

USTERKI

       Pod  Linuksem  generowanie i dostarczanie sygnału są oddzielnymi zdarzeniami i dla każdego
       sygnału  może  być  tylko  jedno  zaległe  zdarzenie.  Zatem  możliwe  jest,  że   podczas
       patologicznie  dużego  obciążenia  czas  ważności  ITIMER_REAL może upłynąć wcześniej, niż
       sygnał poprzedniego przeterminowania zostanie dostarczony. Drugi sygnał w takiej  sytuacji
       zostanie utracony.

       W   jądrach  Linuksa  wcześniejszych  niż  2.6.16  wartości  timerów  są  przedstawiane  w
       jednostkach jiffies. Jeśli żądane jest ustawienie timera na wartość, której  reprezentacja
       w  jiffies  przekracza  MAX_SEC_IN_JIFFIES  (zdefiniowany  w  include/linux/jiffies.h), to
       timer jest po cichu obcinany do tej wartości progowej. W  systemie  Linux/i386  (gdzie  od
       Linuksa  2.6.13  wartość  jednego  jiffy jest równa 0,004 sekundy), oznacza to, że wartość
       progowa timera w przybliżeniu wynosi 99,42  dni.  Od  Linuksa  2.6.16  jądro  używa  innej
       wewnętrznej reprezentacji czasów i to ograniczenie jest usunięte.

       Jądra  Linuksa wcześniejsze niż 2.6.12 miały na niektórych systemach (włączając w to i386)
       błąd powodujący w pewnych sytuacjach ciągłe wygaszanie timera, nawet co jedno jiffy.  Błąd
       został poprawiony w jądrze 2.6.12.

       POSIX.1-2001  mówi,  że setitimer() powinno zwrócić błąd, jeśli wartość tv_usec jest spoza
       zakresu od 0 do 999999. Jednakże w jądrach Linuksa aż do wersji 2.6.21  włącznie  tak  się
       nie działo. Zamiast tego Linux odpowiednio uaktualniał liczbę sekund (tv_sec) czasomierza.
       W wersji jądra 2.6.22 ta niezgodność ze standardem została naprawiona: niepoprawna wartość
       tv_usec powoduje zwrócenie błędu EINVAL.

ZOBACZ TAKŻE

       gettimeofday(2), sigaction(2), signal(2), timer_create(2), timerfd_create(2), time(7)

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ą: Przemek Borys (PTM)
       <pborys@dione.ids.pl>, Andrzej M. Krzysztofowicz (PTM) <ankry@green.mf.pg.gda.pl> 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.