SHMCTL(2)

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 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. Jeżeli segment został zaznaczony do usunięcie, to (niestandardowy) znacznik SHM_DEST będzie ustawiony w polu shm_perm.mode skojarzonej z segmentem 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_ds 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
SVr4, POSIX.1-2001.

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 3.52 projektu Linux man-pages. Opis projektu oraz informacje dotyczące zgłaszania błędów można znaleźć pod adresem http://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ą 3.52 oryginału.