From c952e22670c921775aa7a487631baea9ab408048 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Wed, 10 Nov 2004 17:23:19 +0000 Subject: [PATCH] Formatting & lag clean-ups; added /proc file notes --- man2/msgget.2 | 128 +++++++++++++++++++++--------------------- man2/semget.2 | 146 ++++++++++++++++++++++++++---------------------- man2/shmget.2 | 152 ++++++++++++++++++++++++-------------------------- 3 files changed, 215 insertions(+), 211 deletions(-) diff --git a/man2/msgget.2 b/man2/msgget.2 index e323a8ad4..a0f478f4e 100644 --- a/man2/msgget.2 +++ b/man2/msgget.2 @@ -1,7 +1,7 @@ .\" Copyright 1993 Giorgio Ciucci .\" .\" Permission is granted to make and distribute verbatim copies of this -.\" manual provided the copyright notice and this permission notice are +.\" manual provflags the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this @@ -26,6 +26,9 @@ .\" Removed EIDRM from errors - that can't happen... .\" Modified, 27 May 2004, Michael Kerrisk .\" Added notes on capability requirements +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Added notes on /proc files .\" .TH MSGGET 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" .SH NAME @@ -43,7 +46,9 @@ msgget \- get a message queue identifier .BI "int msgget(key_t " key , .BI "int " msgflg ); .SH DESCRIPTION -The function returns the message queue identifier associated +The +.BR msgget () +system call returns the message queue identifier associated with the value of the .I key argument. @@ -59,94 +64,87 @@ no message queue with the given key .IR key exists, and .B IPC_CREAT -is asserted in +is specified in +.IR msgflg . +.PP +If .I msgflg -(i.e., -.IB msgflg & IPC_CREAT -is nonzero). -The presence in -.I msgflg -of the fields -.B IPC_CREAT -and -.B IPC_EXCL -plays the same role, with respect to the existence -of the message queue, as the presence -of -.B O_CREAT -and -.B O_EXCL -in the mode argument of the -.BR open (2) -system call: i.e. the -.B msgget -function fails if -.I msgflg -asserts both +specifies both .B IPC_CREAT and .B IPC_EXCL and a message queue already exists for -.IR key . +.IR key , +then +.BR msgget () +fails with +.I errno +set to +.BR EEXIST . +(This is analogous to the effect of the combination +.B O_CREAT | O_EXCL +for +.BR open (2).) .PP -Upon creation, the lower 9 bits of the argument +Upon creation, the least significant bits of the argument .I msgflg -define the access permissions of the message queue. +define the permissions of the message queue. These permission bits have the same format and semantics -as the access permissions parameter in -.BR open (2) -or -.BR creat (2) -system calls. (The execute permissions are not used.) +as the permissions specified for the +.I mode +argument of +.BR open (2). +(The execute permissions are not used.) .PP If a new message queue is created, -the system call initializes the system message queue data structure -.B msqid_ds -as follows: +then its associated data structure +.i msqid_ds +(see +.BR msgctl (2)) +is initialised as follows: .IP -.B msg_perm.cuid +.I msg_perm.cuid and -.B msg_perm.uid +.I msg_perm.uid are set to the effective user\-ID of the calling process. .IP -.B msg_perm.cgid +.I msg_perm.cgid and -.B msg_perm.gid +.I msg_perm.gid are set to the effective group\-ID of the calling process. .IP -The lowest order 9 bits of -.B msg_perm.mode -are set to the lowest order 9 bit of +The least significant 9 bits of +.I msg_perm.mode +are set to the least significant 9 bits of .IR msgflg . .IP -.BR msg_qnum , -.BR msg_lspid , -.BR msg_lrpid , -.BR msg_stime +.IR msg_qnum , +.IR msg_lspid , +.IR msg_lrpid , +.IR msg_stime and -.B msg_rtime +.I msg_rtime are set to 0. .IP -.B msg_ctime +.I msg_ctime is set to the current time. .IP -.B msg_qbytes +.I msg_qbytes is set to the system limit .BR MSGMNB . .PP -If the message queue already exists the access permissions are +If the message queue already exists the permissions are verified, and a check is made to see if it is marked for destruction. .SH "RETURN VALUE" If successful, the return value will be the message queue identifier (a -nonnegative integer), otherwise -.B \-1 +nonnegative integer), otherwise \-1 with -.B errno +.I errno indicating the error. .SH ERRORS On failure, -.B errno +.I errno is set to one of the following values: .TP 11 .B EACCES @@ -162,7 +160,7 @@ A message queue exists for .B key and .I msgflg -was asserting both +specified both .B IPC_CREAT and .BR IPC_EXCL . @@ -172,12 +170,12 @@ No message queue exists for .I key and .I msgflg -wasn't asserting +did not specify .BR IPC_CREAT . .TP .B ENOMEM -A message queue has to be created but the system has not enough memory for -the new data structure. +A message queue has to be created but the system does not have enough +memory for the new data structure. .TP .B ENOSPC A message queue has to be created but the system limit for the maximum @@ -187,28 +185,30 @@ would be exceeded. .SH NOTES .B IPC_PRIVATE isn't a flag field but a -.B key_t +.I key_t type. If this special value is used for .IR key , -the system call ignores everything but the lowest order 9 bits of +the system call ignores everything but the least significant 9 bits of .I msgflg and creates a new message queue (on success). .PP The following is a system limit on message queue resources affecting a -.B msgget +.BR msgget () call: .TP 11 .B MSGMNI System wide maximum number of message queues: policy -dependent. +dependent +(on Linux, this limit can be read and modified via +.IR /proc/sys/kernel/msgmni ). .SH BUGS The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW would more clearly show its function. .SH "CONFORMING TO" SVr4, SVID. Until version 2.3.20 Linux would return EIDRM for a -.B msgget +.BR msgget () on a message queue scheduled for deletion. .SH "SEE ALSO" .BR msgctl (2), diff --git a/man2/semget.2 b/man2/semget.2 index 2d2eb77c2..4b9ad5fe4 100644 --- a/man2/semget.2 +++ b/man2/semget.2 @@ -25,6 +25,11 @@ .\" Modified 4 Jan 2002, Michael Kerrisk .\" Modified, 27 May 2004, Michael Kerrisk .\" Added notes on capability requirements +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Added notes on /proc files +.\" Rewrote BUGS note about semget()'s failure to initilaise +.\" semaphore values .\" .TH SEMGET 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual" .SH NAME @@ -43,7 +48,9 @@ semget \- get a semaphore set identifier .BI "int " nsems , .BI "int " semflg ); .SH DESCRIPTION -This function returns the semaphore set identifier +The +.BR semget () +system call returns the semaphore set identifier associated with the argument .IR key . A new set of @@ -56,102 +63,91 @@ or if no existing semaphore set is associated to .I key and .B IPC_CREAT -is asserted in -.I semflg -(i.e. -.IR semflg " &" -.B IPC_CREAT -isn't zero). +is specified in +.IR semflg . .PP -The presence in +If .I semflg -of the fields -.B IPC_CREAT -and -.B IPC_EXCL -plays the same role, with respect to the existence -of the semaphore set, as the presence -of -.B O_CREAT -and -.B O_EXCL -in the mode argument of the -.BR open (2) -system call: i.e. the -.B semget -function fails if -.I semflg -asserts both +specifies both .B IPC_CREAT and .B IPC_EXCL and a semaphore set already exists for -.IR key . +.IR key , +then +.BR semget () +fails with +.I errno +set to +.BR EEXIST . +(This is analogous to the effect of the combination +.B O_CREAT | O_EXCL +for +.BR open (2).) .PP -Upon creation, the low-order 9 bits of the argument +Upon creation, the least significant 9 bits of the argument .I semflg -define the access permissions (for owner, group and others) +define the permissions (for owner, group and others) for the semaphore set. These bits have the same format, and the same -meaning, as the mode argument in the +meaning, as the +.I mode +argument of .BR open (2) -or -.BR creat (2) -system calls (though the execute permissions are +(though the execute permissions are not meaningful for semaphores, and write permissions mean permission to alter semaphore values). .PP When creating a new semaphore set, -.B semget -initializes the semaphore set's associated data structure -.B semid_ds +.BR semget () +initialises the set's associated data structure +.I semid_ds +(see +.BR semctl (2)) as follows: .IP -.B sem_perm.cuid +.I sem_perm.cuid and -.B sem_perm.uid +.I sem_perm.uid are set to the effective user\-ID of the calling process. .IP -.B sem_perm.cgid +.I sem_perm.cgid and -.B sem_perm.gid +.I sem_perm.gid are set to the effective group\-ID of the calling process. .IP -The low-order 9 bits of -.B sem_perm.mode -are set to the low-order 9 bits of +The least significant 9 bits of +.I sem_perm.mode +are set to the least significant 9 bits of .IR semflg . .IP -.B sem_nsems +.I sem_nsems is set to the value of .IR nsems . .IP -.B sem_otime +.I sem_otime is set to 0. .IP -.B sem_ctime +.I sem_ctime is set to the current time. .PP The argument .I nsems -can be -.B 0 +can be 0 (a don't care) when a semaphore set is not being created. Otherwise .I nsems -must be greater than -.B 0 +must be greater than 0 and less than or equal to the maximum number of semaphores per semaphore set .RB ( SEMMSL ). .PP -If the semaphore set already exists, the access permissions are +If the semaphore set already exists, the permissions are verified. .\" and a check is made to see if it is marked for destruction. .SH "RETURN VALUE" If successful, the return value will be the semaphore set identifier -(a nonnegative integer), otherwise -.B \-1 +(a nonnegative integer), otherwise \-1 is returned, with .I errno indicating the error. @@ -173,7 +169,7 @@ A semaphore set exists for .B key and .I semflg -was asserting both +specified both .B IPC_CREAT and .BR IPC_EXCL . @@ -197,12 +193,12 @@ No semaphore set exists for .I key and .I semflg -wasn't asserting +did not specify .BR IPC_CREAT . .TP .B ENOMEM -A semaphore set has to be created but the system has not enough memory for -the new data structure. +A semaphore set has to be created but the system does not have +enough memory for the new data structure. .TP .B ENOSPC A semaphore set has to be created but the system limit for the maximum @@ -214,27 +210,33 @@ would be exceeded. .SH NOTES .B IPC_PRIVATE isn't a flag field but a -.B key_t +.I key_t type. If this special value is used for .IR key , -the system call ignores everything but the low-order 9 bits of +the system call ignores everything but the least significant 9 bits of .I semflg and creates a new semaphore set (on success). .PP The followings are limits on semaphore set resources affecting a -.B semget +.BR semget () call: .TP 11 .B SEMMNI -System wide maximum number of semaphore sets: policy dependent. +System wide maximum number of semaphore sets: policy dependent +(on Linux, this limit can be read and modified via the fourth field of +.IR /proc/sys/kernel/sem ). +.\" This /proc file is not available in Linux 2.2 and earlier -- MTK .TP .B SEMMSL Maximum number of semaphores per semid: implementation dependent -(500 currently). +(on Linux, this limit can be read and modified via the first field of +.IR /proc/sys/kernel/sem ). .TP .B SEMMNS -System wide maximum number of semaphores: policy dependent. +System wide maximum number of semaphores: policy dependent +(on Linux, this limit can be read and modified via the second field of +.IR /proc/sys/kernel/sem ). Values greater than .B SEMMSL * SEMMNI makes it irrelevant. @@ -242,16 +244,24 @@ makes it irrelevant. The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW would more clearly show its function. .LP -The data structure associated with each semaphore in the set -isn't initialized by the system call. -In order to initialize those data structures, one has to execute a -subsequent call to +The semaphores in a set are not initialised by +.BR semget (). +.\" In fact they are initalised to zero on Linux, but POSIX.1-2001 +.\" does not specifiy this, and we can't portably rely on it. +In order to initialise the semaphores, .BR semctl (2) -to perform a +must be used to perform a .B SETVAL or a .B SETALL -command on the semaphore set. +operation on the semaphore set. +(Where multiple peers do not know who will be the first to +initialise the set, checking for a non-zero +.I sem_otime +in the associated data structure retrieved by a +.BR semctl () +.B IPC_STAT +operation can be used to avoid races.) .SH "CONFORMING TO" SVr4, SVID. SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN, diff --git a/man2/shmget.2 b/man2/shmget.2 index 76d7fe70c..e75bf2894 100644 --- a/man2/shmget.2 +++ b/man2/shmget.2 @@ -29,6 +29,9 @@ .\" Removed EIDRM from errors - that can't happen... .\" Modified, 27 May 2004, Michael Kerrisk .\" Added notes on capability requirements +.\" Modified, 11 Nov 2004, Michael Kerrisk +.\" Language and formatting clean-ups +.\" Added notes on /proc files .\" .TH SHMGET 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" .SH NAME @@ -42,7 +45,7 @@ shmget \- allocates a shared memory segment .BI "int shmget(key_t " key ", int " size ", int " shmflg ); .ad b .SH DESCRIPTION -.B shmget() +.BR shmget () returns the identifier of the shared memory segment associated with the value of the argument .IR key . @@ -62,11 +65,27 @@ no shared memory segment corresponding to .IR key exists, and .B IPC_CREAT -is asserted in +is specified in +.IR shmflg . +.PP +If .I shmflg -(i.e. -.IB shmflg &IPC_CREAT -isn't zero). +specifies both +.B IPC_CREAT +and +.B IPC_EXCL +and a shared memory segment already exists for +.IR key , +then +.BR shmget () +fails with +.I errno +set to +.BR EEXIST . +(This is analogous to the effect of the combination +.B O_CREAT | O_EXCL +for +.BR open (2).) .PP The value .I shmflg @@ -74,108 +93,77 @@ is composed of: .TP 12 .B IPC_CREAT to create a new segment. If this flag is not used, then -.B shmget() +.BR shmget () will find the segment associated with \fIkey\fP and check to see if the user has permission to access the segment. .TP .B IPC_EXCL used with \fBIPC_CREAT\fP to ensure failure if the segment already exists. .TP -.B mode_flags (lowest 9 bits) +.I mode_flags +(least significant 9 bits) specifying the permissions granted to the owner, group, and world. +These bits have the same format, and the same +meaning, as the +.I mode +argument of +.BR open (2). Presently, the execute permissions are not used by the system. .\" FIXME -- document SHM_HUGETLB .PP -If a new segment is created, the access permissions from -.I shmflg -are copied into the -.I shm_perm -member of the +If a new shared memory segment is created, +then its associated data structure .I shmid_ds -structure that defines the segment. -The \fIshmid_ds\fP structure has the following form: -.PP -.in +0.5i -.nf -struct shmid_ds { - struct ipc_perm shm_perm; /* operation perms */ - int shm_segsz; /* size of segment (bytes) */ - time_t shm_atime; /* last attach time */ - time_t shm_dtime; /* last detach time */ - time_t shm_ctime; /* last change time */ - unsigned short shm_cpid; /* pid of creator */ - unsigned short shm_lpid; /* pid of last operator */ - short shm_nattch; /* no. of current attaches */ -}; -.fi -.in -0.5i -.PP -.in +0.5i -.nf -struct ipc_perm { - key_t key; - ushort uid; /* owner euid and egid */ - ushort gid; - ushort cuid; /* creator euid and egid */ - ushort cgid; - ushort mode; /* lower 9 bits of \fIshmflg\fP */ - ushort seq; /* sequence number */ -}; -.fi -.PP -When creating a new shared memory segment, -the system call initializes the \fIshmid_ds\fP data structure -.B shmid_ds -as follows: +(see +.BR shmctl (2)) +is initialised as follows: .IP -.B shm_perm.cuid +.I shm_perm.cuid and -.B shm_perm.uid +.I shm_perm.uid are set to the effective user\-ID of the calling process. .IP -.B shm_perm.cgid +.I shm_perm.cgid and -.B shm_perm.gid +.I shm_perm.gid are set to the effective group\-ID of the calling process. .IP -The lowest order 9 bits of -.B shm_perm.mode -are set to the lowest order 9 bit of +The least significant 9 bits of +.I shm_perm.mode +are set to the least significant 9 bit of .IR shmflg . .IP -.B shm_segsz +.I shm_segsz is set to the value of .IR size . .IP -.BR shm_lpid , -.BR shm_nattch , -.B shm_atime +.IR shm_lpid , +.IR shm_nattch , +.I shm_atime and -.B shm_dtime -are set to -.BR 0 . +.I shm_dtime +are set to 0. .IP -.B shm_ctime +.I shm_ctime is set to the current time. .PP -If the shared memory segment already exists, the access permissions are +If the shared memory segment already exists, the permissions are verified, and a check is made to see if it is marked for destruction. -.PP .SH "SYSTEM CALLS" .TP -.B fork() +.BR fork () After a -.B fork() +.BR fork () the child inherits the attached shared memory segments. .TP -.B exec() +.BR exec () After an -.B exec() +.BR exec () all attached shared memory segments are detached (not destroyed). .TP -.B exit() +.BR exit () Upon -.B exit() +.BR exit () all attached shared memory segments are detached (not destroyed). .PP .SH "RETURN VALUE" @@ -184,7 +172,7 @@ A valid segment identifier, is returned on success, \-1 on error. .SH ERRORS On failure, -.B errno +.I errno is set to one of the following: .TP 12 .B EACCES @@ -227,24 +215,27 @@ would cause the system to exceed the system-wide limit on shared memory .SH NOTES .B IPC_PRIVATE isn't a flag field but a -.B key_t +.I key_t type. If this special value is used for .IR key , -the system call ignores everything but the lowest order 9 bits of +the system call ignores everything but the least significant 9 bits of .I shmflg and creates a new shared memory segment (on success). .PP The followings are limits on shared memory segment resources affecting a -.B shmget +.BR shmget () call: .TP 11 .B SHMALL -System wide maximum of shared memory pages: policy dependent. +System wide maximum of shared memory pages +(on Linux, this limit can be read and modified via +.IR /proc/sys/kernel/shmall ). .TP .B SHMMAX -Maximum size in bytes for a shared memory segment: implementation -dependent (currently 4M). +Maximum size in bytes for a shared memory segment: policy dependent +(on Linux, this limit can be read and modified via +.IR /proc/sys/kernel/shmmax ). .TP .B SHMMIN Minimum size in bytes for a shared memory segment: implementation @@ -254,7 +245,10 @@ is the effective minimum size). .TP .B SHMMNI System wide maximum number of shared memory segments: implementation -dependent (currently 4096, was 128 before Linux 2.3.99). +dependent (currently 4096, was 128 before Linux 2.3.99; +on Linux, this limit can be read and modified via +.IR /proc/sys/kernel/shmmni ). +.\" This /proc file is not available in Linux 2.2 and earlier -- MTK .PP The implementation has no specific limits for the per process maximum number of shared memory segments @@ -265,7 +259,7 @@ would more clearly show its function. .SH "CONFORMING TO" SVr4, SVID. SVr4 documents an additional error condition EEXIST. Until version 2.3.30 Linux would return EIDRM for a -.B shmget +.BR shmget () on a shared memory segment scheduled for deletion. .SH "SEE ALSO" .BR shmat (2),