original/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 .TH SVIPC 7 2013-02-12 "Linux" "Linux Programmer's Manual"
  28 .SH NAME
  29 svipc \- System V interprocess communication mechanisms
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <sys/msg.h>
  33 .B #include <sys/sem.h>
  34 .B #include <sys/shm.h>
  35 .fi
  36 .SH DESCRIPTION
  37 This manual page refers to the Linux implementation of the System V
  38 interprocess communication (IPC) mechanisms:
  39 message queues, semaphore sets, and shared memory segments.
  40 In the following, the word
  41 .I resource
  42 means an instantiation of one among such mechanisms.
  43 .SS Resource access permissions
  44 For each resource, the system uses a common structure of type
  45 .I "struct ipc_perm"
  46 to store information needed in determining permissions to perform an
  47 IPC operation.
  48 The
  49 .I ipc_perm
  50 structure includes the following members:
  51 .in +4n
  52 .nf
  53
  54 struct ipc_perm {
  55     uid_t          cuid;   /* creator user ID */
  56     gid_t          cgid;   /* creator group ID */
  57     uid_t          uid;    /* owner user ID */
  58     gid_t          gid;    /* owner group ID */
  59     unsigned short mode;   /* r/w permissions */
  60 };
  61 .fi
  62 .in
  63 .PP
  64 The
  65 .I mode
  66 member of the
  67 .I ipc_perm
  68 structure defines, with its lower 9 bits, the access permissions to the
  69 resource for a process executing an IPC system call.
  70 The permissions are interpreted as follows:
  71 .sp
  72 .nf
  73     0400    Read by user.
  74     0200    Write by user.
  75 .sp .5
  76     0040    Read by group.
  77     0020    Write by group.
  78 .sp .5
  79     0004    Read by others.
  80     0002    Write by others.
  81 .fi
  82 .PP
  83 Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
  84 Furthermore,
  85 "write"
  86 effectively means
  87 "alter"
  88 for a semaphore set.
  89 .PP
  90 The same system header file also defines the following symbolic
  91 constants:
  92 .TP 14
  93 .B IPC_CREAT
  94 Create entry if key doesn't exist.
  95 .TP
  96 .B IPC_EXCL
  97 Fail if key exists.
  98 .TP
  99 .B IPC_NOWAIT
 100 Error if request must wait.
 101 .TP
 102 .B IPC_PRIVATE
 103 Private key.
 104 .TP
 105 .B IPC_RMID
 106 Remove resource.
 107 .TP
 108 .B IPC_SET
 109 Set resource options.
 110 .TP
 111 .B IPC_STAT
 112 Get resource options.
 113 .PP
 114 Note that
 115 .B IPC_PRIVATE
 116 is a
 117 .I key_t
 118 type, while all the other symbolic constants are flag fields and can
 119 be OR'ed into an
 120 .I int
 121 type variable.
 122 .SS Message queues
 123 A message queue is uniquely identified by a positive integer
 124 .RI "(its " msqid )
 125 and has an associated data structure of type
 126 .IR "struct msqid_ds" ,
 127 defined in
 128 .IR <sys/msg.h> ,
 129 containing the following members:
 130 .in +4n
 131 .nf
 132
 133 struct msqid_ds {
 134     struct ipc_perm msg_perm;
 135     msgqnum_t       msg_qnum;    /* no of messages on queue */
 136     msglen_t        msg_qbytes;  /* bytes max on a queue */
 137     pid_t           msg_lspid;   /* PID of last msgsnd(2) call */
 138     pid_t           msg_lrpid;   /* PID of last msgrcv(2) call */
 139     time_t          msg_stime;   /* last msgsnd(2) time */
 140     time_t          msg_rtime;   /* last msgrcv(2) time */
 141     time_t          msg_ctime;   /* last change time */
 142 };
 143 .fi
 144 .in
 145 .TP 11
 146 .I msg_perm
 147 .I ipc_perm
 148 structure that specifies the access permissions on the message
 149 queue.
 150 .TP
 151 .I msg_qnum
 152 Number of messages currently on the message queue.
 153 .TP
 154 .I msg_qbytes
 155 Maximum number of bytes of message text allowed on the message
 156 queue.
 157 .TP
 158 .I msg_lspid
 159 ID of the process that performed the last
 160 .BR msgsnd (2)
 161 system call.
 162 .TP
 163 .I msg_lrpid
 164 ID of the process that performed the last
 165 .BR msgrcv (2)
 166 system call.
 167 .TP
 168 .I msg_stime
 169 Time of the last
 170 .BR msgsnd (2)
 171 system call.
 172 .TP
 173 .I msg_rtime
 174 Time of the last
 175 .BR msgrcv (2)
 176 system call.
 177 .TP
 178 .I msg_ctime
 179 Time of the last
 180 system call that changed a member of the
 181 .I msqid_ds
 182 structure.
 183 .SS Semaphore sets
 184 A semaphore set is uniquely identified by a positive integer
 185 .RI "(its " semid )
 186 and has an associated data structure of type
 187 .IR "struct semid_ds" ,
 188 defined in
 189 .IR <sys/sem.h> ,
 190 containing the following members:
 191 .in +4n
 192 .nf
 193
 194 struct semid_ds {
 195     struct ipc_perm sem_perm;
 196     time_t          sem_otime;   /* last operation time */
 197     time_t          sem_ctime;   /* last change time */
 198     unsigned long   sem_nsems;   /* count of sems in set */
 199 };
 200 .fi
 201 .in
 202 .TP 11
 203 .I sem_perm
 204 .I ipc_perm
 205 structure that specifies the access permissions on the semaphore
 206 set.
 207 .TP
 208 .I sem_otime
 209 Time of last
 210 .BR semop (2)
 211 system call.
 212 .TP
 213 .I sem_ctime
 214 Time of last
 215 .BR semctl (2)
 216 system call that changed a member of the above structure or of one
 217 semaphore belonging to the set.
 218 .TP
 219 .I sem_nsems
 220 Number of semaphores in the set.
 221 Each semaphore of the set is referenced by a nonnegative integer
 222 ranging from
 223 .B 0
 224 to
 225 .IR sem_nsems\-1 .
 226 .PP
 227 A semaphore is a data structure of type
 228 .I "struct sem"
 229 containing the following members:
 230 .in +4n
 231 .nf
 232
 233 struct sem {
 234     int semval;  /* semaphore value */
 235     int sempid;  /* PID for last operation */
 236 .\"    unsigned short semncnt; /* nr awaiting semval to increase */
 237 .\"    unsigned short semzcnt; /* nr awaiting semval = 0 */
 238 };
 239 .fi
 240 .in
 241 .TP 11
 242 .I semval
 243 Semaphore value: a nonnegative integer.
 244 .TP
 245 .I sempid
 246 ID of the last process that performed a semaphore operation
 247 on this semaphore.
 248 .\".TP
 249 .\".I semncnt
 250 .\"Number of processes suspended awaiting for
 251 .\".I semval
 252 .\"to increase.
 253 .\".TP
 254 .\".I semznt
 255 .\"Number of processes suspended awaiting for
 256 .\".I semval
 257 .\"to become zero.
 258 .SS Shared memory segments
 259 A shared memory segment is uniquely identified by a positive integer
 260 .RI "(its " shmid )
 261 and has an associated data structure of type
 262 .IR "struct shmid_ds" ,
 263 defined in
 264 .IR <sys/shm.h> ,
 265 containing the following members:
 266 .in +4n
 267 .nf
 268
 269 struct shmid_ds {
 270     struct ipc_perm shm_perm;
 271     size_t          shm_segsz;   /* size of segment */
 272     pid_t           shm_cpid;    /* PID of creator */
 273     pid_t           shm_lpid;    /* PID, last operation */
 274     shmatt_t        shm_nattch;  /* no. of current attaches */
 275     time_t          shm_atime;   /* time of last attach */
 276     time_t          shm_dtime;   /* time of last detach */
 277     time_t          shm_ctime;   /* time of last change */
 278 };
 279 .fi
 280 .in
 281 .TP 11
 282 .I shm_perm
 283 .I ipc_perm
 284 structure that specifies the access permissions on the shared memory
 285 segment.
 286 .TP
 287 .I shm_segsz
 288 Size in bytes of the shared memory segment.
 289 .TP
 290 .I shm_cpid
 291 ID of the process that created the shared memory segment.
 292 .TP
 293 .I shm_lpid
 294 ID of the last process that executed a
 295 .BR shmat (2)
 296 or
 297 .BR shmdt (2)
 298 system call.
 299 .TP
 300 .I shm_nattch
 301 Number of current alive attaches for this shared memory segment.
 302 .TP
 303 .I shm_atime
 304 Time of the last
 305 .BR shmat (2)
 306 system call.
 307 .TP
 308 .I shm_dtime
 309 Time of the last
 310 .BR shmdt (2)
 311 system call.
 312 .TP
 313 .I shm_ctime
 314 Time of the last
 315 .BR shmctl (2)
 316 system call that changed
 317 .IR shmid_ds .
 318 .SH SEE ALSO
 319 .BR ipcmk (1),
 320 .BR ipcrm (1),
 321 .BR ipcs (1),
 322 .BR ipc (2),
 323 .BR msgctl (2),
 324 .BR msgget (2),
 325 .BR msgrcv (2),
 326 .BR msgsnd (2),
 327 .BR semctl (2),
 328 .BR semget (2),
 329 .BR semop (2),
 330 .BR shmat (2),
 331 .BR shmctl (2),
 332 .BR shmdt (2),
 333 .BR shmget (2),
 334 .BR ftok (3)