Provided by: manpages-pl-dev_20051117-1_all bug

NAZWA

       shmctl - sterowanie segmentami pamięci wspólnej

SKŁADNIA

       #include <sys/ipc.h>

       #include <sys/shm.h>

       int shmctl(int shmid, int cmd, struct shmid_ds *buf);

OPIS

       shmctl()  pozwala  użytkownikowi pobierać informacje dotyczące segmentu
       pamięci wspólnej, zmieniać właściciela, grupę i prawa dostępu  do  tego
       segmentu oraz usunąć segment. Informacje dotyczące segmentu określonego
       przez  shmid  zwracane   są   w   strukturze   shmid_ds   zdefiniowanej
       następująco:

           struct shmid_ds {
               struct ipc_perm shm_perm;  /* prawa dostępu */
               int shm_segsz;             /* rozmiar segmentu (w bajtach) */
               time_t shm_atime;          /* czas ostatniego dołączenia */
               time_t shm_dtime;          /* czas ostatniego odłączenia */
               time_t shm_ctime;          /* czas ostatniej modyfikacji */
               unsigned short shm_cpid;   /* PID twórcy segmentu */
               unsigned short shm_lpid;   /* PID ostatniego operatora segmentu */
               short shm_nattch;          /* liczba dołączeń */
               ...
           };

       Można  nadać  wartość  wyróżnionym  polom struktury shm_perm opisującej
       prawa dostępu:

           struct ipc_perm
           {
               key_t  key;
               ushort uid;   /* euid oraz egid właściciela segmentu */
               ushort gid;
               ushort cuid;  /* euid oraz egid twórcy segmentu */
               ushort cgid;
               ushort mode;  /* 9 najmniej znaczących bitów praw dostępu */
               ushort seq;   /* numer porządkowy */
           };

       Następujące polecenia mogą być przekazane za pomocą parametru cmd :

       IPC_STAT    służy do kopiowania informacji o segmencie pamięci wspólnej
                   do  bufora  buf.  Użytkownik  musi  mieć  prawo  do odczytu
                   segmentu pamięci wspólnej.

       IPC_SET     służy do modyfikacji  praw  dostępu  do  segmentu.  Z  pola
                   shm_perms  struktury wskazanej przez parametr buf pobierane
                   są uid, gid i mode.  System  uwzględnia  tylko  9  najmniej
                   znaczących    bitów   parametru   mode.    Polu   shm_ctime
                   przypisywane  jest  aktualny  czas.  Użytkownik  musi   być
                   właścicielem  segmentu,  jego  twórcą  lub  administratorem
                   systemu.

       IPC_RMID    służy do zaznaczenia segmentu  do  usunięcia.  Zostanie  on
                   naprawdę usunięty w momencie, gdy wszystkie procesy odłączą
                   się. (Tj. gdy pole shm_nattch struktury shmid_ds opisującej
                   segment   osiągnie   wartość  zero.)  Użytkownik  musi  być
                   właścicielem  segmentu,  jego  twórcą  lub  administratorem
                   systemu.

       Użytkownik  musi  zapewnić,  że  segment  po  użyciu  zostanie na pewno
       usunięty. W przeciwnym przypadku, pamięć lub obszar  wymiany  zajmowane
       przez segment nie zostaną zwolnione.

       Dodatkowo,  administrator systemu może zabronić lub zezwolić na wymianę
       obszarów pam ięci zajmowanych przez segment (tylko w  systemie  Linux).
       Służą do tego następujące wartości cmd:

       SHM_LOCK    zabezpiecza segment pamięci wspólnej przed wymianą. Strony,
                   które wcześniej uległy wymianie zostaną ponownie załadowane
                   do  pamięci  dopiero  w  momencie, gdy użytkownik wykona do
                   nich dostęp.

       SHM_UNLOCK  zezwala na wymianę stron  należących  do  segmentu  pamięci
                   wspólnej.

       Polecenia  sterujące  IPC_INFO, SHM_STAT oraz SHM_INFO są używane przez
       program  ipcs(8)  do  pobierania  informacji  o  używanych  zasobach  w
       systemie.  Jeśli zajdzie potrzeba, polecenia te mogą w przyszłości ulec
       zmianie lub ich obsługa może zostać zawarta w systemie plików /proc.

WARTOŚĆ ZWRACANA

       Funkcja zwraca 0, jeśli operacja zakończy  się  pomyślnie,  a  -1,  gdy
       wystąpi błąd.

BŁĘDY

       W przypadku wystąpienia błędu, zmiennej errno przypisana zostanie jedna
       z poniższych wartośći:

       EACCES      jeśli wydano polecenie IPC_STAT, a prawa dostępu  określone
                   w shm_perm.modes nie pozwalają na odczyt segmentu shmid.

       EFAULT      Parametr  cmd  ma  wartość  IPC_SET lub IPC_STAT, ale adres
                   wskazany przez buf jest niedostępny.

       EINVAL      jeśli shmid nie jest poprawnym identyfikatorem segmentu lub
                   cmd nie jest poprawnym poleceniem.

       EIDRM       jeśli  shmid_ds wskazuje na segment, który został usunięty.

       EPERM       jeśli użytkownik próbował wywołać  polecenie  IPC_RMID  lub
                   IPC_SET, ale efektywny UID właściciela procesu wywołującego
                   funkcję  nie  odpowiada  twórcy  segmentu  (określonemu   w
                   shm_perm.cuid),   właścicielowi   segmentu  (określonemu  w
                   shm_perm.uid), ani administratorowi systemu.

       EOVERFLOW   jest zwracane, gdy wydano polecenie IPC_STAT, a wartość gid
                   lub  uid  jest  za  duża,  aby  ją  umieścić  w  strukturze
                   wskazywanej przez buf.

UWAGA

       Niektóre pola struktury struct shmid_ds były w Linuksie 2.2 typu  short
       a  stały  się  typu  long  w  Linuksie 2.4. Aby to wykorzystać, powinna
       wystarczyć rekompilacja pod glibc-2.1.91 lub nowszą.  (Jądro  rozróżnia
       stare i nowe wywołania za pomocą znacznika IPC_64 w cmd.)

ZGODNE Z

       SVr4,  SVID.  SVr4  dokumentuje  dodatkowe kody błędów: EINVAL, ENOENT,
       ENOSPC, ENOMEM, EEXIST. Ani SVr4 ani SVID nie  dokumentują  kodu  błędu
       EIDRM.

ZOBACZ TAKŻE

       shmget(2), shmop(2)