focal (2) shmctl.2.gz

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

NAZWA

       shmctl - sterowanie segmentami pamięci dzielonej Systemu V

SKŁADNIA

       #include <sys/ipc.h>
       #include <sys/shm.h>

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

OPIS

       shmctl()  wykonuje  operację  określoną  przez  parametr  cmd  na segmencie pamięci dzielonej Systemu V o
       identyfikatorze shmid.

       Parametr buf jest wskaźnikiem do struktury shmid_ds, zdefiniowanej następująco w <sys/shm.h>:

           struct shmid_ds {
               struct ipc_perm shm_perm;    /* Prawa dostępu */
               size_t          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 */
               pid_t           shm_cpid;    /* PID twórcy segmentu */
               pid_t           shm_lpid;    /* PID ostatniego shmat(2)/shmdt(2) */
               shmatt_t        shm_nattch;  /* Liczba dołączeń */
               ...
           };

       Struktura ipc_perm jest zdefiniowana następująco (wyróżnione pola można ustawić za pomocą IPC_SET):

           struct ipc_perm {
               key_t          __key;    /* Klucz podany w msgget() */
               uid_t          uid;      /* Efektywny UID właściciela */
               gid_t          gid;      /* Efektywny GID właściciela */
               uid_t          cuid;     /* Efektywny UID twórcy */
               gid_t          cgid;     /* Efektywny GID twórcy */
               unsigned short mode;     /* Uprawnienia + znaczniki */
                                           SHM_DEST i SHM_LOCKED */
               unsigned short __seq;    /* Numer sekwencji */
           };

       Poprawne wartości parametru cmd to:

       IPC_STAT  Kopiuje informacje ze struktury kontrolnej jądra skojarzonej z shmid do  struktury  wskazywanej
                 przez buf. Wywołujący musi mieć uprawnienie odczytu segmentu pamięci dzielonej.

       IPC_SET   Zapisuje  wartości  niektórych pól struktury shmid_ds wskazywanej przez buf do struktury danych
                 jądra powiązanej  z  tym  segmentem  pamięci  dzielonej,  aktualizując  także  pole  shm_ctime.
                 Następujące  pola  mogą  być  zmieniane: shm_perm.uid, shm_perm.gid oraz (9 najmniej znaczących
                 bitów pola) shm_perm.mode. Efektywny identyfikator użytkownika procesu  wywołującego  musi  być
                 równy  identyfikatorowi  właściciela (shm_perm.uid) lub twórcy (shm_perm.cuid) segmentu pamięci
                 dzielonej albo proces wywołujący musi być uprzywilejowany.

       IPC_RMID  Zaznacza segment do usunięcia. Zostanie on naprawdę  usunięty  jedynie  w  momencie,  w  którym
                 ostatni  używający  go  proces się od niego odłączy (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 użytkownikiem uprzywilejowanym. Argument buf jest ignorowany.

                 Jeśli  segment  został zaznaczony do usunięcia, to zostanie ustawiony (niestandardowy) znacznik
                 SHM_DEST pola shm_perm.mode struktury danych zwracanej przez IPC_STAT.

                 Wywołujący 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.

                 Proszę zapoznać się również z opisem z /proc/sys/kernel/shm_rmid_forced w proc(5).

       IPC_INFO (specyficzne dla Linuksa)
                 Zwraca  w  strukturze,  na  którą  wskazuje  buf,  informacje  o  systemowych  ograniczeniach i
                 parametrach pamięci dzielonej. Struktura jest typu shminfo (dlatego wymagane jest rzutowanie) i
                 jest zdefiniowana w <sys/shm.h>, pod warunkiem, że zdefiniowano również makro _GNU_SOURCE:

                     struct shminfo {
                         unsigned long shmmax; /* Maksymalny rozmiar segmentu */
                         unsigned long shmmin; /* Minimalny rozmiar segmentu;
                                                  zawsze 1 */
                         unsigned long shmmni; /* Maksymalna liczba segmentów */
                         unsigned long shmseg; /* Maksymalna liczba segmentów,
                                                  które proces może podłączyć;
                                                  nieużywane przez jądro */
                         unsigned long shmall; /* Maksymalna liczba stron
                                                  pamięci dzielonej, globalna
                                                  dla systemu */
                     };

                 Ustawienia  shmmni,  shmmax  oraz  shmall można zmienić za pomocą plików /proc o nazwach takich
                 samych, jak nazwy tych ustawień; szczegóły można znaleźć w podręczniku proc(5).

       SHM_INFO (specyficzne dla Linuksa)
                 Zwraca strukturę shm_info, której pola zawierają informacje o  zasobach  systemowych  używanych
                 przez   pamięć   dzieloną.  Struktura  jest  zdefiniowana  w  <sys/shm.h>,  pod  warunkiem,  że
                 zdefiniowano również makro _GNU_SOURCE:

                     struct shm_info {
                         int           used_ids; /* Liczba istniejących
                                                    obecnie segmentów */
                         unsigned long shm_tot;  /* Całkowita liczba stron
                                                    pamięci dzielonej */
                         unsigned long shm_rss;  /* Liczba stron pamięci dzielonej
                                                    w fizycznej pamięci */
                         unsigned long shm_swp;  /* Liczba stron pamięci dzielonej
                                                    w przestrzeni wymiany */
                         unsigned long swap_attempts;
                                                 /* Nieużywane od Linuksa 2.4 */
                         unsigned long swap_successes;
                                                 /* Nieużywane od Linuksa 2.4 */
                     };

       SHM_STAT (specyficzne dla Linuksa)
                 Zwraca  strukturę  shmid_ds,  taką  jak  dla  IPC_STAT.  Jednakże  parametr  shmid   nie   jest
                 identyfikatorem  segmentu,  ale  indeksem wewnętrznej tablicy jądra przechowującej informacje o
                 wszystkich segmentach pamięci dzielonej w systemie.

       Proces wywołujący może zabronić lub zezwolić na  wymianę  obszarów  pamięci  zajmowanych  przez  segment,
       używając następujących wartości cmd:

       SHM_LOCK (specyficzne dla Linuksa)
                 Zapobiega  umieszczaniu segmentu pamięci dzielonej w przestrzeni wymiany. The caller must fault
                 in any pages that are required to be present after  locking  is  enabled.  Jeśli  segment  jest
                 zablokowany,  to  zostanie  ustawiony  (niestandardowy)  znacznik SHM_LOCKED pola shm_perm.mode
                 struktury danych zwracanej przez IPC_STAT.

       SHM_UNLOCK (specyficzne dla Linuksa)
                 Odblokowuje segment, zezwalając na umieszczenie go w przestrzeni wymiany.

       W jądrach wcześniejszych niż 2.6.10 tylko proces uprzywilejowany mógł stosować SHM_LOCK i SHM_UNLOCK.  Od
       jądra 2.6.10 nieuprzywilejowany proces może wywołać te operacje, pod warunkiem że efektywny identyfikator
       użytkownika odpowiada identyfikatorowi twórcy lub właściciela segmentu oraz (w przypadku SHM_LOCK)  ilość
       pamięci do zablokowania mieści się w ograniczeniu zasobów RLIMIT_MEMLOCK (patrz setrlimit(2)).

WARTOŚĆ ZWRACANA

       Pomyślnie  zakończone  operacje  IPC_INFO  i  SHM_INFO  zwracają  indeks  najwyższego  używanego  wpisu w
       wewnętrznej  tablicy  jądra  przechowującej  informacje  o  wszystkich  segmentach   pamięci   dzielonej.
       (Informacji tej można użyć w operacjach SHM_STAT, aby otrzymać informacje o wszystkich segmentach pamięci
       dzielonej w systemie). Pomyślnie zakończona  operacja  SHM_STAT  zwraca  identyfikator  segmentu  pamięci
       dzielonej o indeksie przekazanym w shmid. Pozostałe operacje zwracają 0, jeżeli tylko się powiodą.

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

BŁĘDY

       EACCES Wydano  polecenie  IPC_STAT lub SHM_STAT, a prawa dostępu określone w shm_perm.modes nie pozwalają
              na odczyt segmentu shmid i proces wywołujący nie ma ustawionego atrybutu CAP_IPC_OWNER.

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

       EIDRM  shmid wskazuje na usunięty identyfikator.

       EINVAL shmid nie jest poprawnym identyfikatorem lub cmd nie jest poprawnym poleceniem. Albo: w  przypadku
              operacji SHM_STAT wartość indeksu podana w parametrze shmid odwoływała się do obecnie nieużywanego
              elementu tablicy.

       ENOMEM (W jądrach  wcześniejszych  niż  2.6.9)  podano  SHM_LOCK,  a  rozmiar  segmentu  do  zablokowania
              oznaczałby  przekroczenie ograniczenia na całkowitą liczbę bajtów w pamięci dzielonej przypadającą
              na rzeczywisty identyfikator użytkownika procesu  wywołującego.  Ograniczenie  to  jest  opisywane
              przez miękki limit zasobu RLIMIT_MEMLOCK (patrz setrlimit(2)).

       EOVERFLOW
              Próbowano  wywołać  polecenie  IPC_STAT,  a  wartość  GID  lub UID jest za duża, aby ją umieścić w
              strukturze wskazywanej przez buf.

       EPERM  Próbowano wywołać polecenie  IPC_SET lub IPC_RMID,  ale  efektywny  UID  właściciela  wywołującego
              procesu  nie  odpowiada  twórcy  segmentu  (określonemu  w  shm_perm.cuid), właścicielowi segmentu
              (określonemu w shm_perm.uid), a  proces  nie  jest  uprzywilejowany  (Linux:  nie  ma  ustawionego
              atrybutu CAP_SYS_ADMIN).

              Lub  (w  jądrach  starszych  niż  2.6.9)  podano  SHM_LOCK  lub  SHM_UNLOCK,  ale  proces  nie był
              uprzywilejowany (Linux: nie miał ustawionego atrybutu CAP_IPC_LOCK). (Od wersji Linuksa 2.6.9  ten
              błąd  może  wystąpić  również  gdy  RLIMIT_MEMLOCK  jest  równy  0  i  proces  wywołujący nie jest
              uprzywilejowany).

ZGODNE Z

       POSIX.1-2001, POSIX.1-2008, SVr4.

UWAGI

       Dołączenie <sys/types.h> i <sys/ipc.h> nie jest wymagane na Linuksie ani  przez  żadną  z  wersji  POSIX.
       Jednak   niektóre  stare  implementacje  wymagają  dołączenia  tych  plików  nagłówkowych,  SVID  również
       dokumentuje ich dołączenie. Aplikacje które mają być przenośne na tego typu stare  systemy  mogą  wymagać
       dołączenia omawianych plików nagłówkowych.

       Operacje IPC_INFO, SHM_STAT oraz SHM_INFO są używane przez program ipcs(1) w celu dostarczenia informacji
       o zajmowanych zasobach.  W  przyszłości  operacje  te  mogą  zostać  zmodyfikowane  lub  przeniesione  do
       interfejsu systemu plików /proc.

       Linux  pozwala  na  dołączenie  (shmat(2))  segmentu  pamięci  dzielonej,  który już został zaznaczony do
       usunięcia za pomocą shmctl(IPC_RMID). Ta właściwość nie jest dostępna w  innych  implementacjach  Uniksa;
       przenośne aplikacje nie powinny od niej zależeć.

       Niektóre  pola  struktury  struct  shmid_ds  były  w  Linuksie  2.2 typu short, ale 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 wywołania od nowych za pomocą znacznika IPC_64 w cmd).

ZOBACZ TAKŻE

       mlock(2), setrlimit(2), shmget(2), shmop(2), capabilities(7), svipc(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ą:  Rafał  Lewczuk  (PTM)
       <R.Lewczuk@elka.pw.edu.p>,   Andrzej   Krzysztofowicz   (PTM)   <ankry@mif.pg.gda.pl>,   Robert   Luberda
       <robert@debian.org> i Michał Kułach <michal.kulach@gmail.com>.

       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.