shmctl(2) System Calls Manual shmctl(2) NAZWA shmctl - steruje segmentami pamieci dzielonej Systemu V BIBLIOTEKA Standardowa biblioteka C (libc, -lc) SKLADNIA #include int shmctl(int shmid, int op, struct shmid_ds *buf); OPIS shmctl() wykonuje operacje okreslona przez parametr op na segmencie pamieci dzielonej Systemu V o identyfikatorze shmid. Parametr buf jest wskaznikiem do struktury shmid_ds, zdefiniowanej nastepujaco w : struct shmid_ds { struct ipc_perm shm_perm; /* Prawa dostepu */ size_t shm_segsz; /* Rozmiar segmentu (w bajtach) */ time_t shm_atime; /* Czas ostatniego dolaczenia */ time_t shm_dtime; /* Czas ostatniego odlaczenia */ time_t shm_ctime; /* Czas utworzenia/ostatniej mody- fikacji za pomoca shmctl() */ pid_t shm_cpid; /* PID tworcy segmentu */ pid_t shm_lpid; /* PID ostatniego shmat(2)/shmdt(2) */ shmatt_t shm_nattch; /* Liczba dolaczen */ ... }; Pola struktury shmid_ds sa nastepujace: shm_perm Jest to struktura ipc_perm (zob. nizej), ktora okresla prawa dostepu do segmentu pamieci wspolnej. shm_segsz Rozmiar segmentu pamieci wspolnej w bajtach. shm_atime Czas ostatniego wykonania wywolania systemowego shmat(2), dolaczajacego ten segment. shm_dtime Czas ostatniego wykonania wywolania systemowego shmdt(2), odlaczajacego ten segment. shm_ctime Czas utworzenia segmentu lub czas ostatniej operacji IPC_SET shmctl(). shm_cpid Identyfikator procesu, ktory utworzyl ten segment pamieci wspolnej. shm_lpid Identyfikator procesu, ktory ostatni wykonal wywolanie systemowe shmat(2) lub shmdt(2). shm_nattch Liczba procesow, ktore dolaczyly ten segment. Struktura ipc_perm jest zdefiniowana nastepujaco (wyroznione pola mozna ustawic za pomoca IPC_SET): struct ipc_perm { key_t __key; /* Klucz podany w msgget() */ uid_t uid; /* Efektywny UID wlasciciela */ gid_t gid; /* Efektywny GID wlasciciela */ uid_t cuid; /* Efektywny UID tworcy */ gid_t cgid; /* Efektywny GID tworcy */ unsigned short mode; /* Uprawnienia + znaczniki */ SHM_DEST i SHM_LOCKED */ unsigned short __seq; /* Numer sekwencji */ }; Najmniej znaczace 9 bitow pola mode struktury ipc_perm definiuje uprawnienia dostepu do segmentu pamieci dzielonej. Istnieja nastepujace bity uprawnien: 0400 Odczyt przez uzytkownika 0200 Zapis przez uzytkownika 0040 Odczyt przez grupe 0020 Zapis przez grupe 0004 Odczyt przez pozostalych 0002 Zapis przez pozostalych Bity 0100, 0010 i 0001 (bity praw do uruchamiania) nie sa przez system wykorzystywane (nie jest konieczne posiadanie uprawnienia do wykonywania, aby przeprowadzic wywolanie shmat(2) ze znacznikiem SHM_EXEC). Poprawne wartosci parametru op to: IPC_STAT Kopiuje informacje ze struktury kontrolnej jadra skojarzonej z shmid do struktury wskazywanej przez buf. Wywolujacy musi miec uprawnienie odczytu segmentu pamieci dzielonej. IPC_SET Zapisuje wartosci niektorych pol struktury shmid_ds wskazywanej przez parametr buf do struktury kontrolnej zwiazanej z tym segmentem pamieci dzielonej wraz z aktualizacja jego shm_ctime. Aktualizowane sa nastepujace pola: shm_perm.uid, shm_perm.gid i (9 najmniej znaczacych bitow z) shm_perm.mode. Efektywny identyfikator uzytkownika procesu wywolujacego musi odpowiadac wlascicielowi (shm_permuid) lub tworcy (shm_perm.cuid) segmentu pamieci dzielonej albo wywolujacy musi byc uprzywilejowany. IPC_RMID Zaznacza segment do usuniecia. Zostanie on naprawde usuniety jedynie w momencie, w ktorym ostatni uzywajacy go proces sie od niego odlaczy (tj. gdy pole shm_nattch struktury shmid_ds opisujacej segment osiagnie wartosc zero). Uzytkownik musi byc wlascicielem segmentu, jego tworca lub uzytkownikiem uprzywilejowanym. Argument buf jest ignorowany. Jesli segment zostal zaznaczony do usuniecia, to zostanie ustawiony (niestandardowy) znacznik SHM_DEST pola shm_perm.mode struktury danych zwracanej przez IPC_STAT. Wywolujacy musi zapewnic, ze segment po uzyciu zostanie na pewno usuniety. W przeciwnym przypadku pamiec lub obszar wymiany zajmowane przez segment nie zostana zwolnione. Prosze zapoznac sie rowniez z opisem z /proc/sys/kernel/shm_rmid_forced w proc(5). IPC_INFO (specyficzne dla Linuksa) Zwraca w strukturze, na ktora wskazuje buf, informacje o systemowych ograniczeniach i parametrach pamieci dzielonej. Struktura jest typu shminfo (dlatego wymagane jest rzutowanie) i jest zdefiniowana w , pod warunkiem, ze zdefiniowano rowniez makro _GNU_SOURCE: struct shminfo { unsigned long shmmax; /* Maksymalny rozmiar segmentu */ unsigned long shmmin; /* Minimalny rozmiar segmentu; zawsze 1 */ unsigned long shmmni; /* Maksymalna liczba segmentow */ unsigned long shmseg; /* Maksymalna liczba segmentow, ktore proces moze podlaczyc; nieuzywane przez jadro */ unsigned long shmall; /* Maksymalna liczba stron pamieci dzielonej, globalna dla systemu */ }; Ustawienia shmmni, shmmax oraz shmall mozna zmienic za pomoca plikow /proc o nazwach takich samych, jak nazwy tych ustawien; szczegoly mozna znalezc w podreczniku proc(5). SHM_INFO (specyficzne dla Linuksa) Zwraca strukture shm_info, ktorej pola zawieraja informacje o zasobach systemowych uzywanych przez pamiec dzielona. Struktura jest zdefiniowana w , pod warunkiem, ze zdefiniowano rowniez makro _GNU_SOURCE: struct shm_info { int used_ids; /* Liczba istniejacych obecnie segmentow */ unsigned long shm_tot; /* Calkowita liczba stron pamieci dzielonej */ unsigned long shm_rss; /* Liczba stron pamieci dzielonej w fizycznej pamieci */ unsigned long shm_swp; /* Liczba stron pamieci dzielonej w przestrzeni wymiany */ unsigned long swap_attempts; /* Nieuzywane od Linuksa 2.4 */ unsigned long swap_successes; /* Nieuzywane od Linuksa 2.4 */ }; SHM_STAT (specyficzne dla Linuksa) Zwraca strukture shmid_ds, taka jak dla IPC_STAT. Jednakze parametr shmid nie jest identyfikatorem segmentu, ale indeksem wewnetrznej tablicy jadra przechowujacej informacje o wszystkich segmentach pamieci dzielonej w systemie. SHM_STAT_ANY (specyficzne dla Linuksa, od Linuksa 4.17) Zwraca strukture shmid_ds, jak dla SHM_STAT. Jednak sem_perm.mode nie jest sprawdzany pod katem uprawnien odczytu do shmid co oznacza, ze kazdy uzytkownik moze wykonac te operacje (podobnie jak kazdy uzytkownik moze odczytac /proc/sysvipc/shm, pozyskujac te same informacje). Proces wywolujacy moze zabronic lub zezwolic na wymiane obszarow pamieci zajmowanych przez segment, uzywajac nastepujacych wartosci op: SHM_LOCK (specyficzne dla Linuksa) Zapobiega umieszczaniu segmentu pamieci dzielonej w przestrzeni wymiany. Wywolujacy musi zawiesc we wszystkich stronach, ktorych obecnosc jest konieczna po wlaczeniu blokowania. Jesli 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, zezwalajac na umieszczenie go w przestrzeni wymiany. Przed Linuksem 2.6.10 tylko proces uprzywilejowany mogl stosowac SHM_LOCK i SHM_UNLOCK. Od Linuksa 2.6.10 nieuprzywilejowany proces moze wywolac te operacje, pod warunkiem ze efektywny identyfikator uzytkownika odpowiada identyfikatorowi tworcy lub wlasciciela segmentu oraz (w przypadku SHM_LOCK) ilosc pamieci do zablokowania miesci sie w ograniczeniu zasobow RLIMIT_MEMLOCK (patrz setrlimit(2)). WARTOSC ZWRACANA Pomyslnie zakonczone operacje IPC_INFO i SHM_INFO zwracaja indeks najwyzszego uzywanego wpisu w wewnetrznej tablicy jadra przechowujacej informacje o wszystkich segmentach pamieci dzielonej. (Informacji tej mozna uzyc w operacjach SHM_STAT lub SHM_STAT_ANY, aby otrzymac informacje o wszystkich segmentach pamieci dzielonej w systemie). Pomyslnie zakonczona operacja SHM_STAT zwraca identyfikator segmentu pamieci dzielonej o indeksie przekazanym w shmid. Pozostale operacje zwracaja 0, jezeli tylko sie powioda. W razie wystapienia bledu zwracane jest -1 i ustawiane errno wskazujac blad. BLEDY EACCES Wydano polecenie IPC_STAT lub SHM_STAT, a prawa dostepu okreslone w shm_perm.modes nie pozwalaja na odczyt segmentu shmid i proces wywolujacy nie ma przywileju CAP_IPC_OWNER (ang. capability) w przestrzeni nazw uzytkownika, ktora zarzadza jego przestrzenia IPC. EFAULT Parametr op ma wartosc IPC_SET lub IPC_STAT, ale adres wskazany przez buf jest niedostepny. EIDRM shmid wskazuje na usuniety identyfikator. EINVAL shmid nie jest poprawnym identyfikatorem lub op nie jest poprawna operacja. Albo: w przypadku operacji SHM_STAT lub SHM_STAT_ANY wartosc indeksu podana w parametrze shmid odwolywala sie do obecnie nieuzywanego elementu tablicy. ENOMEM (Od Linuksa 2.6.9) Podano SHM_LOCK, a rozmiar segmentu do zablokowania oznaczalby przekroczenie ograniczenia na calkowita liczbe bajtow w pamieci dzielonej przypadajaca na rzeczywisty identyfikator uzytkownika procesu wywolujacego. Ograniczenie to jest opisywane przez miekki limit zasobu RLIMIT_MEMLOCK (patrz setrlimit(2)). EOVERFLOW Probowano wywolac polecenie IPC_STAT, a wartosc GID lub UID jest za duza, aby ja umiescic w strukturze wskazywanej przez buf. EPERM Probowano wywolac polecenie IPC_SET lub IPC_RMID, ale efektywny UID wlasciciela wywolujacego procesu nie odpowiada tworcy segmentu (okreslonemu w shm_perm.cuid), wlascicielowi segmentu (okreslonemu w shm_perm.uid), a proces nie jest uprzywilejowany (Linux: nie ma przywileju CAP_SYS_ADMIN). Lub (przed Linuksem 2.6.9) podano SHM_LOCK lub SHM_UNLOCK, ale proces nie byl uprzywilejowany (Linux: nie mial ustawionego przywileju CAP_IPC_LOCK; od wersji Linuksa 2.6.9 ten blad moze wystapic rowniez gdy RLIMIT_MEMLOCK jest rowny 0 i proces wywolujacy nie jest uprzywilejowany). WERSJE Linux pozwala na dolaczenie (shmat(2)) segmentu pamieci dzielonej, ktory juz zostal zaznaczony do usuniecia za pomoca shmctl(IPC_RMID). Ta wlasciwosc nie jest dostepna w innych implementacjach Uniksa; przenosne aplikacje nie powinny od niej zalezec. STANDARDY POSIX.1-2008. HISTORIA POSIX.1-2001, SVr4. Niektore pola struktury struct shmid_ds byly w Linuksie 2.2 typu short, ale staly sie typu long w Linuksie 2.4. Aby to wykorzystac, powinna wystarczyc rekompilacja pod glibc-2.1.91 lub nowsza (jadro rozroznia stare wywolania od nowych za pomoca znacznika IPC_64 w op). UWAGI Operacje IPC_INFO, SHM_STAT oraz SHM_INFO sa uzywane przez program ipcs(1) w celu dostarczenia informacji o zajmowanych zasobach. W przyszlosci operacje te moga zostac zmodyfikowane lub przeniesione do interfejsu systemu plikow /proc. ZOBACZ TAKZE mlock(2), setrlimit(2), shmget(2), shmop(2), capabilities(7), sysvipc(7) TLUMACZENIE Autorami polskiego tlumaczenia niniejszej strony podrecznika sa: Rafal Lewczuk , Andrzej Krzysztofowicz , Robert Luberda i Michal Kulach Niniejsze tlumaczenie jest wolna dokumentacja. Blizsze informacje o warunkach licencji mozna uzyskac zapoznajac sie z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje sie ZADNEJ ODPOWIEDZIALNOSCI. Bledy w tlumaczeniu strony podrecznika prosimy zglaszac na adres listy dyskusyjnej . Linux man-pages 6.8 2 maja 2024 r. shmctl(2)