man7/svipc.7

   1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" FIXME . There is now duplication of some of the information
  26 .\" below in semctl.2, msgctl.2, and shmctl.2 -- MTK, Nov 04
  27 .\"
  28 .\" FIXME . Ultimately, there should probably be
  29 .\" svmq_overview(7), svshm_overview(7), and svsem_overview(7)
  30 .\" that provide an overview of each System V IPC mechanism.
  31 .\" In that case:
  32 .\"   * Those files should add a discussion of the /proc/sysvipc
  33 .\"     interfaces.
  34 .\"   * Documentation of the various /proc interfaces should move into
  35 .\"     those files (from proc(5)), and references in the various *.2
  36 .\"     pages that refer to the /proc files should be adjusted.
  37 .\"   * The only part that uniquely belongs in svipc(7) is perhaps
  38 .\"     the discussion of ipc_perm.
  39 .\"
  40 .TH SVIPC 7 2016-03-15 "Linux" "Linux Programmer's Manual"
  41 .SH NAME
  42 svipc \- System V interprocess communication mechanisms
  43 .SH SYNOPSIS
  44 .nf
  45 .B #include <sys/msg.h>
  46 .B #include <sys/sem.h>
  47 .B #include <sys/shm.h>
  48 .fi
  49 .SH DESCRIPTION
  50 This manual page refers to the Linux implementation of the System V
  51 interprocess communication (IPC) mechanisms:
  52 message queues, semaphore sets, and shared memory segments.
  53 In the following, the word
  54 .I resource
  55 means an instantiation of one among such mechanisms.
  56 .SS Resource access permissions
  57 For each resource, the system uses a common structure of type
  58 .I "struct ipc_perm"
  59 to store information needed in determining permissions to perform an
  60 IPC operation.
  61 The
  62 .I ipc_perm
  63 structure includes the following members:
  64 .PP
  65 .in +4n
  66 .EX
  67 struct ipc_perm {
  68     uid_t          cuid;   /* creator user ID */
  69     gid_t          cgid;   /* creator group ID */
  70     uid_t          uid;    /* owner user ID */
  71     gid_t          gid;    /* owner group ID */
  72     unsigned short mode;   /* r/w permissions */
  73 };
  74 .EE
  75 .in
  76 .PP
  77 The
  78 .I mode
  79 member of the
  80 .I ipc_perm
  81 structure defines, with its lower 9 bits, the access permissions to the
  82 resource for a process executing an IPC system call.
  83 The permissions are interpreted as follows:
  84 .PP
  85 .nf
  86     0400    Read by user.
  87     0200    Write by user.
  88     0040    Read by group.
  89     0020    Write by group.
  90     0004    Read by others.
  91     0002    Write by others.
  92 .fi
  93 .PP
  94 Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
  95 Furthermore,
  96 "write"
  97 effectively means
  98 "alter"
  99 for a semaphore set.
 100 .PP
 101 The same system header file also defines the following symbolic
 102 constants:
 103 .TP 14
 104 .B IPC_CREAT
 105 Create entry if key doesn't exist.
 106 .TP
 107 .B IPC_EXCL
 108 Fail if key exists.
 109 .TP
 110 .B IPC_NOWAIT
 111 Error if request must wait.
 112 .TP
 113 .B IPC_PRIVATE
 114 Private key.
 115 .TP
 116 .B IPC_RMID
 117 Remove resource.
 118 .TP
 119 .B IPC_SET
 120 Set resource options.
 121 .TP
 122 .B IPC_STAT
 123 Get resource options.
 124 .PP
 125 Note that
 126 .B IPC_PRIVATE
 127 is a
 128 .I key_t
 129 type, while all the other symbolic constants are flag fields and can
 130 be OR'ed into an
 131 .I int
 132 type variable.
 133 .SS Message queues
 134 A message queue is uniquely identified by a positive integer
 135 .RI "(its " msqid )
 136 and has an associated data structure of type
 137 .IR "struct msqid_ds" ,
 138 defined in
 139 .IR <sys/msg.h> ,
 140 containing the following members:
 141 .PP
 142 .in +4n
 143 .EX
 144 struct msqid_ds {
 145     struct ipc_perm msg_perm;
 146     msgqnum_t       msg_qnum;    /* no of messages on queue */
 147     msglen_t        msg_qbytes;  /* bytes max on a queue */
 148     pid_t           msg_lspid;   /* PID of last msgsnd(2) call */
 149     pid_t           msg_lrpid;   /* PID of last msgrcv(2) call */
 150     time_t          msg_stime;   /* last msgsnd(2) time */
 151     time_t          msg_rtime;   /* last msgrcv(2) time */
 152     time_t          msg_ctime;   /* last change time */
 153 };
 154 .EE
 155 .in
 156 .TP 11
 157 .I msg_perm
 158 .I ipc_perm
 159 structure that specifies the access permissions on the message
 160 queue.
 161 .TP
 162 .I msg_qnum
 163 Number of messages currently on the message queue.
 164 .TP
 165 .I msg_qbytes
 166 Maximum number of bytes of message text allowed on the message
 167 queue.
 168 .TP
 169 .I msg_lspid
 170 ID of the process that performed the last
 171 .BR msgsnd (2)
 172 system call.
 173 .TP
 174 .I msg_lrpid
 175 ID of the process that performed the last
 176 .BR msgrcv (2)
 177 system call.
 178 .TP
 179 .I msg_stime
 180 Time of the last
 181 .BR msgsnd (2)
 182 system call.
 183 .TP
 184 .I msg_rtime
 185 Time of the last
 186 .BR msgrcv (2)
 187 system call.
 188 .TP
 189 .I msg_ctime
 190 Time of the last
 191 system call that changed a member of the
 192 .I msqid_ds
 193 structure.
 194 .SS Semaphore sets
 195 A semaphore set is uniquely identified by a positive integer
 196 .RI "(its " semid )
 197 and has an associated data structure of type
 198 .IR "struct semid_ds" ,
 199 defined in
 200 .IR <sys/sem.h> ,
 201 containing the following members:
 202 .IP
 203 .in +4n
 204 .EX
 205 struct semid_ds {
 206     struct ipc_perm sem_perm;
 207     time_t          sem_otime;   /* last operation time */
 208     time_t          sem_ctime;   /* last change time */
 209     unsigned long   sem_nsems;   /* count of sems in set */
 210 };
 211 .EE
 212 .in
 213 .TP 11
 214 .I sem_perm
 215 .I ipc_perm
 216 structure that specifies the access permissions on the semaphore
 217 set.
 218 .TP
 219 .I sem_otime
 220 Time of last
 221 .BR semop (2)
 222 system call.
 223 .TP
 224 .I sem_ctime
 225 Time of last
 226 .BR semctl (2)
 227 system call that changed a member of the above structure or of one
 228 semaphore belonging to the set.
 229 .TP
 230 .I sem_nsems
 231 Number of semaphores in the set.
 232 Each semaphore of the set is referenced by a nonnegative integer
 233 ranging from
 234 .B 0
 235 to
 236 .IR sem_nsems\-1 .
 237 .PP
 238 A semaphore is a data structure of type
 239 .I "struct sem"
 240 containing the following members:
 241 .PP
 242 .in +4n
 243 .EX
 244 struct sem {
 245     int semval;  /* semaphore value */
 246     int sempid;  /* PID of process that last modified */
 247 .\"    unsigned short semncnt; /* nr awaiting semval to increase */
 248 .\"    unsigned short semzcnt; /* nr awaiting semval = 0 */
 249 };
 250 .EE
 251 .in
 252 .TP 11
 253 .I semval
 254 Semaphore value: a nonnegative integer.
 255 .TP
 256 .I sempid
 257 PID of the last process that modified the value of
 258 this semaphore.
 259 .\".TP
 260 .\".I semncnt
 261 .\"Number of processes suspended awaiting for
 262 .\".I semval
 263 .\"to increase.
 264 .\".TP
 265 .\".I semznt
 266 .\"Number of processes suspended awaiting for
 267 .\".I semval
 268 .\"to become zero.
 269 .SS Shared memory segments
 270 A shared memory segment is uniquely identified by a positive integer
 271 .RI "(its " shmid )
 272 and has an associated data structure of type
 273 .IR "struct shmid_ds" ,
 274 defined in
 275 .IR <sys/shm.h> ,
 276 containing the following members:
 277 .PP
 278 .in +4n
 279 .EX
 280 struct shmid_ds {
 281     struct ipc_perm shm_perm;
 282     size_t          shm_segsz;   /* size of segment */
 283     pid_t           shm_cpid;    /* PID of creator */
 284     pid_t           shm_lpid;    /* PID, last operation */
 285     shmatt_t        shm_nattch;  /* no. of current attaches */
 286     time_t          shm_atime;   /* time of last attach */
 287     time_t          shm_dtime;   /* time of last detach */
 288     time_t          shm_ctime;   /* time of last change */
 289 };
 290 .EE
 291 .in
 292 .TP 11
 293 .I shm_perm
 294 .I ipc_perm
 295 structure that specifies the access permissions on the shared memory
 296 segment.
 297 .TP
 298 .I shm_segsz
 299 Size in bytes of the shared memory segment.
 300 .TP
 301 .I shm_cpid
 302 ID of the process that created the shared memory segment.
 303 .TP
 304 .I shm_lpid
 305 ID of the last process that executed a
 306 .BR shmat (2)
 307 or
 308 .BR shmdt (2)
 309 system call.
 310 .TP
 311 .I shm_nattch
 312 Number of current alive attaches for this shared memory segment.
 313 .TP
 314 .I shm_atime
 315 Time of the last
 316 .BR shmat (2)
 317 system call.
 318 .TP
 319 .I shm_dtime
 320 Time of the last
 321 .BR shmdt (2)
 322 system call.
 323 .TP
 324 .I shm_ctime
 325 Time of the last
 326 .BR shmctl (2)
 327 system call that changed
 328 .IR shmid_ds .
 329 .SS IPC namespaces
 330 For a discussion of the interaction of System V IPC objects and
 331 IPC namespaces, see
 332 .BR namespaces (7).
 333 .SH SEE ALSO
 334 .BR ipcmk (1),
 335 .BR ipcrm (1),
 336 .BR ipcs (1),
 337 .BR lsipc (1),
 338 .BR ipc (2),
 339 .BR msgctl (2),
 340 .BR msgget (2),
 341 .BR msgrcv (2),
 342 .BR msgsnd (2),
 343 .BR semctl (2),
 344 .BR semget (2),
 345 .BR semop (2),
 346 .BR shmat (2),
 347 .BR shmctl (2),
 348 .BR shmdt (2),
 349 .BR shmget (2),
 350 .BR ftok (3),
 351 .BR namespaces (7)