.\" -*- coding: UTF-8 -*-
'\" t
.\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993
.\" and Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
.\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\" Modified 1993-07-28, Rik Faith <faith@cs.unc.edu>
.\" Modified 1993-11-28, Giorgio Ciucci <giorgio@crcc.it>
.\" Modified 1997-01-31, Eric S. Raymond <esr@thyrsus.com>
.\" Modified 2001-02-18, Andries Brouwer <aeb@cwi.nl>
.\" Modified 2002-01-05, 2004-05-27, 2004-06-17,
.\"    Michael Kerrisk <mtk.manpages@gmail.com>
.\" Modified 2004-10-11, aeb
.\" Modified, Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
.\"	Language and formatting clean-ups
.\"	Updated shmid_ds structure definitions
.\"	Added information on SHM_DEST and SHM_LOCKED flags
.\"	Noted that CAP_IPC_LOCK is not required for SHM_UNLOCK
.\"		since Linux 2.6.9
.\" Modified, 2004-11-25, mtk, notes on 2.6.9 RLIMIT_MEMLOCK changes
.\" 2005-04-25, mtk -- noted aberrant Linux behavior w.r.t. new
.\"	attaches to a segment that has already been marked for deletion.
.\" 2005-08-02, mtk: Added IPC_INFO, SHM_INFO, SHM_STAT descriptions.
.\" 2018-03-20, dbueso: Added SHM_STAT_ANY description.
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH shmctl 2 "15 grudnia 2022 r." "Linux man\-pages 6.03" 
.SH NAZWA
shmctl \- steruje segmentami pamięci dzielonej Systemu V
.SH BIBLIOTEKA
Standardowa biblioteka C (\fIlibc\fP, \fI\-lc\fP)
.SH SKŁADNIA
.nf
\fB#include <sys/shm.h>\fP
.PP
\fBint shmctl(int \fP\fIshmid\fP\fB, int \fP\fIcmd\fP\fB, struct shmid_ds *\fP\fIbuf\fP\fB);\fP
.fi
.SH OPIS
\fBshmctl\fP() wykonuje operację określoną przez parametr \fIcmd\fP na segmencie
pamięci dzielonej Systemu\ V o identyfikatorze \fIshmid\fP.
.PP
Parametr \fIbuf\fP jest wskaźnikiem do struktury \fIshmid_ds\fP, zdefiniowanej
następująco w \fI<sys/shm.h>\fP:
.PP
.in +4n
.EX
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 utworzenia/ostatniej mody\-
                                    fikacji za pomocą shmctl() */
    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ń */
    ...
};
.EE
.in
.PP
Pola struktury \fIshmid_ds\fP są następujące:
.TP  12
\fIshm_perm\fP
Jest to struktura \fIipc_perm\fP (zob. niżej), która określa prawa dostępu do
segmentu pamięci wspólnej.
.TP 
\fIshm_segsz\fP
Rozmiar segmentu pamięci wspólnej w bajtach.
.TP 
\fIshm_atime\fP
Czas ostatniego wykonania wywołania systemowego \fBshmat\fP(2), dołączającego
ten segment.
.TP 
\fIshm_dtime\fP
Czas ostatniego wykonania wywołania systemowego \fBshmdt\fP(2), odłączającego
ten segment.
.TP 
\fIshm_ctime\fP
Czas utworzenia segmentu lub czas ostatniej operacji \fBIPC_SET\fP \fBshmctl\fP().
.TP 
\fIshm_cpid\fP
Identyfikator procesu, który utworzył ten segment pamięci wspólnej.
.TP 
\fIshm_lpid\fP
Identyfikator procesu, który ostatni wykonał wywołanie systemowe \fBshmat\fP(2)
lub \fBshmdt\fP(2).
.TP 
\fIshm_nattch\fP
Liczba procesów, które dołączyły ten segment.
.PP
Struktura \fIipc_perm\fP jest zdefiniowana następująco (wyróżnione pola można
ustawić za pomocą \fBIPC_SET\fP):
.PP
.in +4n
.EX
struct ipc_perm {
    key_t          __key;    /* Klucz podany w msgget() */
    uid_t          \fBuid\fP;      /* Efektywny UID właściciela */
    gid_t          \fBgid\fP;      /* Efektywny GID właściciela */
    uid_t          cuid;     /* Efektywny UID twórcy */
    gid_t          cgid;     /* Efektywny GID twórcy */
    unsigned short \fBmode\fP;     /* \fBUprawnienia\fP + znaczniki */
                                SHM_DEST i SHM_LOCKED */
    unsigned short __seq;    /* Numer sekwencji */
};
.EE
.in
.PP
Najmniej znaczące 9 bitów pola \fImode\fP struktury \fIipc_perm\fP definiuje
uprawnienia dostępu do segmentu pamięci dzielonej. Istnieją następujące bity
uprawnień:
.TS
l l.
0400	Odczyt przez użytkownika
0200	Zapis przez użytkownika
0040	Odczyt przez grupę
0020	Zapis przez grupę
0004	Odczyt przez pozostałych
0002	Zapis przez pozostałych
.TE
.PP
Bity 0100, 0010 i 0001 (bity praw do uruchamiania) nie są przez system
wykorzystywane (nie jest konieczne posiadanie uprawnienia do wykonywania,
aby przeprowadzić wywołanie \fBshmat\fP(2) ze znacznikiem \fBSHM_EXEC\fP).
.PP
Poprawne wartości parametru \fIcmd\fP to:
.TP 
\fBIPC_STAT\fP
Kopiuje informacje ze struktury kontrolnej jądra skojarzonej z \fIshmid\fP do
struktury wskazywanej przez \fIbuf\fP. Wywołujący musi mieć uprawnienie odczytu
segmentu pamięci dzielonej.
.TP 
\fBIPC_SET\fP
Zapisuje wartości niektórych pól struktury \fBshmid_ds\fP wskazywanej przez
parametr \fIbuf\fP do struktury kontrolnej związanej z tym segmentem pamięci
dzielonej wraz z aktualizacją jego \fBshm_ctime\fP.
.IP
Aktualizowane są następujące pola: \fIshm_perm.uid\fP, \fIshm_perm.gid\fP i (9
najmniej znaczących bitów z) \fIshm_perm.mode\fP.
.IP
Efektywny identyfikator użytkownika procesu wywołującego musi odpowiadać
właścicielowi (\fIshm_permuid\fP) lub twórcy (\fIshm_perm.cuid\fP) segmentu
pamięci dzielonej albo wywołujący musi być uprzywilejowany.
.TP 
\fBIPC_RMID\fP
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 \fIshm_nattch\fP struktury \fIshmid_ds\fP opisującej segment osiągnie wartość
zero). Użytkownik musi być właścicielem segmentu, jego twórcą lub
użytkownikiem uprzywilejowanym. Argument \fIbuf\fP jest ignorowany.
.IP
Jeśli segment został zaznaczony do usunięcia, to zostanie ustawiony
(niestandardowy) znacznik \fBSHM_DEST\fP pola \fIshm_perm.mode\fP struktury danych
zwracanej przez \fBIPC_STAT\fP.
.IP
Wywołujący \fImusi\fP zapewnić, że segment po użyciu zostanie na pewno
usunięty. W przeciwnym przypadku pamięć lub obszar wymiany zajmowane przez
segment nie zostaną zwolnione.
.IP
Proszę zapoznać się również z opisem z \fI/proc/sys/kernel/shm_rmid_forced\fP w
\fBproc\fP(5).
.TP 
\fBIPC_INFO\fP (specyficzne dla Linuksa)
Zwraca w strukturze, na którą wskazuje \fIbuf\fP, informacje o systemowych
ograniczeniach i parametrach pamięci dzielonej. Struktura jest typu
\fIshminfo\fP (dlatego wymagane jest rzutowanie) i jest zdefiniowana w
\fI<sys/shm.h>\fP, pod warunkiem, że zdefiniowano również makro
\fB_GNU_SOURCE\fP:
.IP
.in +4n
.EX
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 */
};
.EE
.in
.IP
Ustawienia \fIshmmni\fP, \fIshmmax\fP oraz \fIshmall\fP można zmienić za pomocą
plików \fI/proc\fP o nazwach takich samych, jak nazwy tych ustawień; szczegóły
można znaleźć w podręczniku \fBproc\fP(5).
.TP 
\fBSHM_INFO\fP (specyficzne dla Linuksa)
Zwraca strukturę \fIshm_info\fP, której pola zawierają informacje o zasobach
systemowych używanych przez pamięć dzieloną. Struktura jest zdefiniowana w
\fI<sys/shm.h>\fP, pod warunkiem, że zdefiniowano również makro
\fB_GNU_SOURCE\fP:
.IP
.in +4n
.EX
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 */
};
.EE
.in
.TP 
\fBSHM_STAT\fP (specyficzne dla Linuksa)
Zwraca strukturę \fIshmid_ds\fP, taką jak dla \fBIPC_STAT\fP. Jednakże parametr
\fIshmid\fP nie jest identyfikatorem segmentu, ale indeksem wewnętrznej tablicy
jądra przechowującej informacje o wszystkich segmentach pamięci dzielonej w
systemie.
.TP 
\fBSHM_STAT_ANY\fP (specyficzne dla Linuksa, od Linuksa 4.17)
Zwraca strukturę \fIshmid_ds\fP, jak dla \fBSHM_STAT\fP. Jednak \fIsem_perm.mode\fP
nie jest sprawdzany pod kątem uprawnień odczytu do \fIshmid\fP co oznacza, że
każdy użytkownik może wykonać tę operację (podobnie jak każdy użytkownik
może odczytać \fI/proc/sysvipc/shm\fP, pozyskując te same informacje).
.PP
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 \fIcmd\fP:
.TP 
\fBSHM_LOCK\fP (specyficzne dla Linuksa)
Zapobiega umieszczaniu segmentu pamięci dzielonej w przestrzeni
wymiany. Wywołujący musi zawieść we wszystkich stronach, których obecność
jest konieczna po włączeniu blokowania. Jeśli segment jest zablokowany, to
zostanie ustawiony (niestandardowy) znacznik \fBSHM_LOCKED\fP pola
\fIshm_perm.mode\fP struktury danych zwracanej przez \fBIPC_STAT\fP.
.TP 
\fBSHM_UNLOCK\fP (specyficzne dla Linuksa)
Odblokowuje segment, zezwalając na umieszczenie go w przestrzeni wymiany.
.PP
.\" There was some weirdness in Linux 2.6.9: SHM_LOCK and SHM_UNLOCK could
.\" be applied to a segment, regardless of ownership of the segment.
.\" This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed
.\" in Linux 2.6.10.  MTK, May 2005
Przed Linuksem 2.6.10 tylko proces uprzywilejowany mógł stosować \fBSHM_LOCK\fP
i \fBSHM_UNLOCK\fP. Od Linuksa 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
\fBSHM_LOCK\fP) ilość pamięci do zablokowania mieści się w ograniczeniu zasobów
\fBRLIMIT_MEMLOCK\fP (patrz \fBsetrlimit\fP(2)).
.SH "WARTOŚĆ ZWRACANA"
Pomyślnie zakończone operacje \fBIPC_INFO\fP i \fBSHM_INFO\fP 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 \fBSHM_STAT\fP lub \fBSHM_STAT_ANY\fP, aby otrzymać informacje o
wszystkich segmentach pamięci dzielonej w systemie). Pomyślnie zakończona
operacja \fBSHM_STAT\fP zwraca identyfikator segmentu pamięci dzielonej o
indeksie przekazanym w \fIshmid\fP. Pozostałe operacje zwracają 0, jeżeli tylko
się powiodą.
.PP
W razie wystąpienia błędu zwracane jest \-1 i ustawiane \fIerrno\fP wskazując
błąd.
.SH BŁĘDY
.TP 
\fBEACCES\fP
Wydano polecenie \fBIPC_STAT\fP lub \fBSHM_STAT\fP, a prawa dostępu określone w
\fIshm_perm.modes\fP nie pozwalają na odczyt segmentu \fIshmid\fP i proces
wywołujący nie ma przywileju \fBCAP_IPC_OWNER\fP (ang. capability) w
przestrzeni nazw użytkownika, która zarządza jego przestrzenią IPC.
.TP 
\fBEFAULT\fP
Parametr \fIcmd\fP ma wartość \fBIPC_SET\fP lub \fBIPC_STAT\fP, ale adres wskazany
przez \fIbuf\fP jest niedostępny.
.TP 
\fBEIDRM\fP
\fIshmid\fP wskazuje na usunięty identyfikator.
.TP 
\fBEINVAL\fP
\fIshmid\fP nie jest poprawnym identyfikatorem lub \fIcmd\fP nie jest poprawnym
poleceniem. Albo: w przypadku operacji \fBSHM_STAT\fP lub \fBSHM_STAT_ANY\fP
wartość indeksu podana w parametrze \fIshmid\fP odwoływała się do obecnie
nieużywanego elementu tablicy.
.TP 
\fBENOMEM\fP
(Od Linuksa 2.6.9)  Podano \fBSHM_LOCK\fP, 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
\fBRLIMIT_MEMLOCK\fP (patrz \fBsetrlimit\fP(2)).
.TP 
\fBEOVERFLOW\fP
Próbowano wywołać polecenie \fBIPC_STAT\fP, a wartość GID lub UID jest za duża,
aby ją umieścić w strukturze wskazywanej przez \fIbuf\fP.
.TP 
\fBEPERM\fP
Próbowano wywołać polecenie  \fBIPC_SET\fP lub \fBIPC_RMID\fP, ale efektywny UID
właściciela wywołującego procesu nie odpowiada twórcy segmentu (określonemu
w \fIshm_perm.cuid\fP), właścicielowi segmentu (określonemu w \fIshm_perm.uid\fP),
a proces nie jest uprzywilejowany (Linux: nie ma przywileju
\fBCAP_SYS_ADMIN\fP).
.IP
Lub (przed Linuksem 2.6.9) podano \fBSHM_LOCK\fP lub \fBSHM_UNLOCK\fP, ale proces
nie był uprzywilejowany (Linux: nie miał ustawionego przywileju
\fBCAP_IPC_LOCK\fP; od wersji Linuksa 2.6.9 ten błąd może wystąpić również gdy
\fBRLIMIT_MEMLOCK\fP jest równy 0 i proces wywołujący nie jest
uprzywilejowany).
.SH STANDARDY
.\" SVr4 documents additional error conditions EINVAL,
.\" ENOENT, ENOSPC, ENOMEM, EEXIST.  Neither SVr4 nor SVID documents
.\" an EIDRM error condition.
POSIX.1\-2001, POSIX.1\-2008, SVr4.
.SH UWAGI
Operacje \fBIPC_INFO\fP, \fBSHM_STAT\fP oraz \fBSHM_INFO\fP są używane przez program
\fBipcs\fP(1) w celu dostarczenia informacji o zajmowanych zasobach. W
przyszłości operacje te mogą zostać zmodyfikowane lub przeniesione do
interfejsu systemu plików \fI/proc\fP.
.PP
Linux pozwala na dołączenie (\fBshmat\fP(2)) segmentu pamięci dzielonej, który
już został zaznaczony do usunięcia za pomocą \fIshmctl(IPC_RMID)\fP. Ta
właściwość nie jest dostępna w innych implementacjach Uniksa; przenośne
aplikacje nie powinny od niej zależeć.
.PP
Niektóre pola struktury \fIstruct shmid_ds\fP były w Linuksie 2.2 typu
\fIshort\fP, ale stały się typu \fIlong\fP 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 \fBIPC_64\fP w \fIcmd\fP).
.SH "ZOBACZ TAKŻE"
\fBmlock\fP(2), \fBsetrlimit\fP(2), \fBshmget\fP(2), \fBshmop\fP(2), \fBcapabilities\fP(7),
\fBsysvipc\fP(7)
.PP
.SH TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są:
Rafał Lewczuk <R.Lewczuk@elka.pw.edu.p>,
Andrzej Krzysztofowicz <ankry@green.mf.pg.gda.pl>,
Robert Luberda <robert@debian.org>
i
Michał Kułach <michal.kulach@gmail.com>
.
.PP
Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach
licencji można uzyskać zapoznając się z
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License w wersji 3
.UE
lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.
.PP
Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy
dyskusyjnej
.MT manpages-pl-list@lists.sourceforge.net
.ME .
