Formatting & lag clean-ups; added /proc file notes

man2/msgget.2

@@ -1,7 +1,7 @@
 .\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
 .\"
 .\" 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 <mtk-manpages@gmx.net>
 .\"     Added notes on capability requirements
+.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net>
+.\"	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.,
+specifies both
-.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
 .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 
+as the permissions specified for the 
-.BR open (2)
+.I mode
-or
+argument of
-.BR creat (2)
+.BR open (2).
-system calls.  (The execute permissions are not used.)
+(The execute permissions are not used.)
 .PP
 If a new message queue is created,
-the system call initializes the system message queue data structure
+then its associated data structure
-.B msqid_ds
+.i msqid_ds
-as follows:
+(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
+The least significant 9 bits of
-.B msg_perm.mode
+.I msg_perm.mode
-are set to the lowest order 9 bit of
+are set to the least significant 9 bits of
 .IR msgflg .
 .IP
-.BR msg_qnum ,
+.IR msg_qnum ,
-.BR msg_lspid ,
+.IR msg_lspid ,
-.BR msg_lrpid ,
+.IR msg_lrpid ,
-.BR msg_stime
+.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
+nonnegative integer), otherwise \-1
-.B \-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
+A message queue has to be created but the system does not have enough
-the new data structure.
+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),

man2/semget.2

@@ -25,6 +25,11 @@
 .\" Modified 4 Jan 2002, Michael Kerrisk <mtk-manpages@gmx.net>
 .\" Modified, 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net>
 .\"     Added notes on capability requirements
+.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net>
+.\"	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
+is specified in
-.I semflg
+.IR semflg .
-(i.e.
-.IR semflg " &"
-.B IPC_CREAT
-isn't zero).
 .PP
-The presence in
+If
 .I semflg
-of the fields
+specifies both
-.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
 .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
+(though the execute permissions are
-.BR creat (2)
-system calls (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
+.BR semget ()
-initializes the semaphore set's associated data structure
+initialises the set's associated data structure
-.B semid_ds
+.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
+The least significant 9 bits of
-.B sem_perm.mode
+.I sem_perm.mode
-are set to the low-order 9 bits of
+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
+can be 0
-.B 0
 (a don't care)
 when a semaphore set is not being created.
 Otherwise
 .I nsems
-must be greater than
+must be greater than 0
-.B 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
+(a nonnegative integer), otherwise \-1
-.B \-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
+A semaphore set has to be created but the system does not have
-the new data structure.
+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
+The semaphores in a set are not initialised by
-isn't initialized by the system call.
+.BR semget ().
-In order to initialize those data structures, one has to execute a
+.\" In fact they are initalised to zero on Linux, but POSIX.1-2001 
-subsequent call to
+.\" 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,

man2/shmget.2

@@ -29,6 +29,9 @@
 .\"	Removed EIDRM from errors - that can't happen...
 .\" Modified, 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net>
 .\"     Added notes on capability requirements
+.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net>
+.\"	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.
+specifies both
-.IB shmflg &IPC_CREAT
+.B IPC_CREAT
-isn't zero).
+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
+If a new shared memory segment is created,
-.I shmflg
+then its associated data structure
-are copied into the 
-.I shm_perm
-member of the 
 .I shmid_ds
-structure that defines the segment.
+(see
-The \fIshmid_ds\fP structure has the following form:
+.BR shmctl (2))
-.PP
+is initialised as follows:
-.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:
 .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
+The least significant 9 bits of
-.B shm_perm.mode
+.I shm_perm.mode
-are set to the lowest order 9 bit of
+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 ,
+.IR shm_lpid ,
-.BR shm_nattch ,
+.IR shm_nattch ,
-.B shm_atime
+.I shm_atime
 and
-.B shm_dtime
+.I shm_dtime
-are set to
+are set to 0.
-.BR 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
+Maximum size in bytes for a shared memory segment: policy dependent
-dependent (currently 4M).
+(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),