1f1ac9460362aab913c6a93abf529a29 semget.2

Changed files:
    semget.2 -> 1.1

diff --git a/semget.2 b/semget.2
new file mode 100644 (file)
index 0000000..a23c016
--- /dev/null
+++ b/semget.2
@@ -0,0 +1,271 @@
+.\" 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
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one
+.\" 
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\" 
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\"
+.\" Modified Tue Oct 22 17:54:56 1996 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified 1 Jan 2002, Martin Schulze <joey@infodrom.org>
+.\" Modified 4 Jan 2002, Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
+.\"
+.TH SEMGET 2 2002-01-04 "Linux 2.5" "Linux Programmer's Manual" 
+.SH NAME
+semget \- get a semaphore set identifier
+.SH SYNOPSIS
+.nf
+.B
+#include <sys/types.h>
+.B
+#include <sys/ipc.h>
+.B
+#include <sys/sem.h>
+.fi
+.sp
+.BI "int semget(key_t " key ,
+.BI "int " nsems ,
+.BI "int " semflg );
+.SH DESCRIPTION
+This function returns the semaphore set identifier
+associated with the argument
+.IR key .
+A new set of
+.I nsems
+semaphores is created if
+.I key
+has the value
+.B IPC_PRIVATE
+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).
+.PP
+The presence in
+.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
+.B IPC_CREAT
+and
+.B IPC_EXCL
+and a semaphore set already exists for
+.IR key .
+.PP
+Upon creation, the low-order 9 bits of the argument
+.I semflg
+define the access 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
+.BR open (2)
+or
+.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
+initializes the semaphore set's associated data structure
+.B semid_ds
+as follows:
+.IP
+.B sem_perm.cuid
+and
+.B sem_perm.uid
+are set to the effective user\-ID of the calling process.
+.IP
+.B sem_perm.cgid
+and
+.B 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
+.IR semflg .
+.IP
+.B sem_nsems
+is set to the value of
+.IR nsems .
+.IP
+.B sem_otime
+is set to 0.
+.IP
+.B sem_ctime
+is set to the current time.
+.PP
+The argument
+.I nsems
+can be
+.B 0
+(a don't care)
+when a semaphore set is not being created.
+Otherwise
+.I nsems
+must be greater than
+.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
+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
+is returned, with
+.I errno
+indicating the error.
+.SH ERRORS
+On failure
+.I errno
+will be set to one of the following:
+.TP 11
+.B EACCES
+A semaphore set exists for
+.IR key ,
+but the calling process does not have permission to access the set.
+.TP
+.B EEXIST
+A semaphore set exists for
+.B key
+and
+.I semflg
+was asserting both
+.B IPC_CREAT
+and
+.BR IPC_EXCL .
+.\" .TP
+.\" .B EIDRM
+.\" The semaphore set is marked to be deleted.
+.TP
+.B ENOENT
+No semaphore set exists for
+.I key
+and
+.I semflg
+wasn't asserting
+.BR IPC_CREAT .
+.TP
+.B EINVAL
+.IR nsems
+is less than 0 or greater than the limit on the number
+of semaphores per semaphore set
+.RB ( SEMMSL ),
+or a semaphore set corresponding to
+.I key
+already exists, and
+.I nsems
+is larger than the number of semaphores in that set.
+.TP
+.B ENOMEM
+A semaphore set has to be created but the system has not enough memory for
+the new data structure.
+.TP
+.B ENOSPC
+A semaphore set has to be created but the system limit for the maximum
+number of semaphore sets
+.RB ( SEMMNI ),
+or the system wide maximum number of semaphores
+.RB ( SEMMNS ),
+would be exceeded.
+.SH NOTES
+.B IPC_PRIVATE
+isn't a flag field but a
+.B key_t
+type.
+If this special value is used for
+.IR key ,
+the system call ignores everything but the low-order 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
+call:
+.TP 11
+.B SEMMNI
+System wide maximum number of semaphore sets: policy dependent.
+.TP
+.B SEMMSL
+Maximum number of semaphores per semid: implementation dependent
+(500 currently).
+.TP
+.B SEMMNS
+System wide maximum number of semaphores: policy dependent.
+Values greater than
+.B SEMMSL * SEMMNI
+makes it irrelevant.
+.SH BUGS
+Use of
+.B IPC_PRIVATE
+doesn't inhibit to other processes the access to the allocated
+semaphore set.
+.PP
+As for the files, there is currently no intrinsic way for a process to ensure
+exclusive access to a semaphore set.
+Asserting both
+.B IPC_CREAT
+and
+.B IPC_EXCL
+in
+.I semflg
+only ensures (on success) that a new semaphore set will be created,
+it doesn't imply exclusive access to the semaphore set.
+.PP
+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
+.BR semctl (2)
+to perform a
+.B SETVAL
+or a
+.B SETALL
+command on the semaphore set.
+.SH "CONFORMING TO"
+SVr4, SVID.
+SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN,
+ERANGE, EFAULT.
+.SH "SEE ALSO"
+.BR ftok (3),
+.BR ipc (5),
+.BR semctl (2),
+.BR semop (2)