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 .\"
  28 .\" FIXME Ultimately, there should probably be
  29 .\" svmq_overview(7), svshm_overview(7), and sem_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 perphaps
  38 .\"     the discussion of ipc_perm.
  39 .\"
  40 .TH SVIPC 7 2013-02-12 "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 .in +4n
  65 .nf
  66
  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 .fi
  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 .sp
  85 .nf
  86     0400    Read by user.
  87     0200    Write by user.
  88 .sp .5
  89     0040    Read by group.
  90     0020    Write by group.
  91 .sp .5
  92     0004    Read by others.
  93     0002    Write by others.
  94 .fi
  95 .PP
  96 Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
  97 Furthermore,
  98 "write"
  99 effectively means
 100 "alter"
 101 for a semaphore set.
 102 .PP
 103 The same system header file also defines the following symbolic
 104 constants:
 105 .TP 14
 106 .B IPC_CREAT
 107 Create entry if key doesn't exist.
 108 .TP
 109 .B IPC_EXCL
 110 Fail if key exists.
 111 .TP
 112 .B IPC_NOWAIT
 113 Error if request must wait.
 114 .TP
 115 .B IPC_PRIVATE
 116 Private key.
 117 .TP
 118 .B IPC_RMID
 119 Remove resource.
 120 .TP
 121 .B IPC_SET
 122 Set resource options.
 123 .TP
 124 .B IPC_STAT
 125 Get resource options.
 126 .PP
 127 Note that
 128 .B IPC_PRIVATE
 129 is a
 130 .I key_t
 131 type, while all the other symbolic constants are flag fields and can
 132 be OR'ed into an
 133 .I int
 134 type variable.
 135 .SS Message queues
 136 A message queue is uniquely identified by a positive integer
 137 .RI "(its " msqid )
 138 and has an associated data structure of type
 139 .IR "struct msqid_ds" ,
 140 defined in
 141 .IR <sys/msg.h> ,
 142 containing the following members:
 143 .in +4n
 144 .nf
 145
 146 struct msqid_ds {
 147     struct ipc_perm msg_perm;
 148     msgqnum_t       msg_qnum;    /* no of messages on queue */
 149     msglen_t        msg_qbytes;  /* bytes max on a queue */
 150     pid_t           msg_lspid;   /* PID of last msgsnd(2) call */
 151     pid_t           msg_lrpid;   /* PID of last msgrcv(2) call */
 152     time_t          msg_stime;   /* last msgsnd(2) time */
 153     time_t          msg_rtime;   /* last msgrcv(2) time */
 154     time_t          msg_ctime;   /* last change time */
 155 };
 156 .fi
 157 .in
 158 .TP 11
 159 .I msg_perm
 160 .I ipc_perm
 161 structure that specifies the access permissions on the message
 162 queue.
 163 .TP
 164 .I msg_qnum
 165 Number of messages currently on the message queue.
 166 .TP
 167 .I msg_qbytes
 168 Maximum number of bytes of message text allowed on the message
 169 queue.
 170 .TP
 171 .I msg_lspid
 172 ID of the process that performed the last
 173 .BR msgsnd (2)
 174 system call.
 175 .TP
 176 .I msg_lrpid
 177 ID of the process that performed the last
 178 .BR msgrcv (2)
 179 system call.
 180 .TP
 181 .I msg_stime
 182 Time of the last
 183 .BR msgsnd (2)
 184 system call.
 185 .TP
 186 .I msg_rtime
 187 Time of the last
 188 .BR msgrcv (2)
 189 system call.
 190 .TP
 191 .I msg_ctime
 192 Time of the last
 193 system call that changed a member of the
 194 .I msqid_ds
 195 structure.
 196 .SS Semaphore sets
 197 A semaphore set is uniquely identified by a positive integer
 198 .RI "(its " semid )
 199 and has an associated data structure of type
 200 .IR "struct semid_ds" ,
 201 defined in
 202 .IR <sys/sem.h> ,
 203 containing the following members:
 204 .in +4n
 205 .nf
 206
 207 struct semid_ds {
 208     struct ipc_perm sem_perm;
 209     time_t          sem_otime;   /* last operation time */
 210     time_t          sem_ctime;   /* last change time */
 211     unsigned long   sem_nsems;   /* count of sems in set */
 212 };
 213 .fi
 214 .in
 215 .TP 11
 216 .I sem_perm
 217 .I ipc_perm
 218 structure that specifies the access permissions on the semaphore
 219 set.
 220 .TP
 221 .I sem_otime
 222 Time of last
 223 .BR semop (2)
 224 system call.
 225 .TP
 226 .I sem_ctime
 227 Time of last
 228 .BR semctl (2)
 229 system call that changed a member of the above structure or of one
 230 semaphore belonging to the set.
 231 .TP
 232 .I sem_nsems
 233 Number of semaphores in the set.
 234 Each semaphore of the set is referenced by a nonnegative integer
 235 ranging from
 236 .B 0
 237 to
 238 .IR sem_nsems\-1 .
 239 .PP
 240 A semaphore is a data structure of type
 241 .I "struct sem"
 242 containing the following members:
 243 .in +4n
 244 .nf
 245
 246 struct sem {
 247     int semval;  /* semaphore value */
 248     int sempid;  /* PID for last operation */
 249 .\"    unsigned short semncnt; /* nr awaiting semval to increase */
 250 .\"    unsigned short semzcnt; /* nr awaiting semval = 0 */
 251 };
 252 .fi
 253 .in
 254 .TP 11
 255 .I semval
 256 Semaphore value: a nonnegative integer.
 257 .TP
 258 .I sempid
 259 ID of the last process that performed a semaphore operation
 260 on this semaphore.
 261 .\".TP
 262 .\".I semncnt
 263 .\"Number of processes suspended awaiting for
 264 .\".I semval
 265 .\"to increase.
 266 .\".TP
 267 .\".I semznt
 268 .\"Number of processes suspended awaiting for
 269 .\".I semval
 270 .\"to become zero.
 271 .SS Shared memory segments
 272 A shared memory segment is uniquely identified by a positive integer
 273 .RI "(its " shmid )
 274 and has an associated data structure of type
 275 .IR "struct shmid_ds" ,
 276 defined in
 277 .IR <sys/shm.h> ,
 278 containing the following members:
 279 .in +4n
 280 .nf
 281
 282 struct shmid_ds {
 283     struct ipc_perm shm_perm;
 284     size_t          shm_segsz;   /* size of segment */
 285     pid_t           shm_cpid;    /* PID of creator */
 286     pid_t           shm_lpid;    /* PID, last operation */
 287     shmatt_t        shm_nattch;  /* no. of current attaches */
 288     time_t          shm_atime;   /* time of last attach */
 289     time_t          shm_dtime;   /* time of last detach */
 290     time_t          shm_ctime;   /* time of last change */
 291 };
 292 .fi
 293 .in
 294 .TP 11
 295 .I shm_perm
 296 .I ipc_perm
 297 structure that specifies the access permissions on the shared memory
 298 segment.
 299 .TP
 300 .I shm_segsz
 301 Size in bytes of the shared memory segment.
 302 .TP
 303 .I shm_cpid
 304 ID of the process that created the shared memory segment.
 305 .TP
 306 .I shm_lpid
 307 ID of the last process that executed a
 308 .BR shmat (2)
 309 or
 310 .BR shmdt (2)
 311 system call.
 312 .TP
 313 .I shm_nattch
 314 Number of current alive attaches for this shared memory segment.
 315 .TP
 316 .I shm_atime
 317 Time of the last
 318 .BR shmat (2)
 319 system call.
 320 .TP
 321 .I shm_dtime
 322 Time of the last
 323 .BR shmdt (2)
 324 system call.
 325 .TP
 326 .I shm_ctime
 327 Time of the last
 328 .BR shmctl (2)
 329 system call that changed
 330 .IR shmid_ds .
 331 .SH SEE ALSO
 332 .BR ipcmk (1),
 333 .BR ipcrm (1),
 334 .BR ipcs (1),
 335 .BR ipc (2),
 336 .BR msgctl (2),
 337 .BR msgget (2),
 338 .BR msgrcv (2),
 339 .BR msgsnd (2),
 340 .BR semctl (2),
 341 .BR semget (2),
 342 .BR semop (2),
 343 .BR shmat (2),
 344 .BR shmctl (2),
 345 .BR shmdt (2),
 346 .BR shmget (2),
 347 .BR ftok (3)
 348 .SH COLOPHON
 349 This page is part of release 3.64 of the Linux
 350 .I man-pages
 351 project.
 352 A description of the project,
 353 and information about reporting bugs,
 354 can be found at
 355 \%http://www.kernel.org/doc/man\-pages/.