git.saurik.com Git - apple/xnu.git/blame_incremental

... / ...

Commit	Line	Data
	1	.\"
	2	.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com>
	3	.\"
	4	.\" All rights reserved.
	5	.\"
	6	.\" Redistribution and use in source and binary forms, with or without
	7	.\" modification, are permitted provided that the following conditions
	8	.\" are met:
	9	.\" 1. Redistributions of source code must retain the above copyright
	10	.\" notice, this list of conditions and the following disclaimer.
	11	.\" 2. Redistributions in binary form must reproduce the above copyright
	12	.\" notice, this list of conditions and the following disclaimer in the
	13	.\" documentation and/or other materials provided with the distribution.
	14	.\"
	15	.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
	16	.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	17	.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
	18	.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
	19	.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
	20	.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
	21	.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
	22	.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	23	.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
	24	.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	25	.\"
	26	.\" $FreeBSD: src/lib/libc/sys/semget.2,v 1.14 2002/12/19 09:40:25 ru Exp $
	27	.\"
	28	.Dd September 12, 1995
	29	.Dt SEMGET 2
	30	.Os
	31	.Sh NAME
	32	.Nm semget
	33	.Nd obtain a semaphore id
	34	.Sh SYNOPSIS
	35	.In sys/sem.h
	36	.Ft int
	37	.Fo semget
	38	.Fa "key_t key"
	39	.Fa "int nsems"
	40	.Fa "int semflg"
	41	.Fc
	42	.Sh DESCRIPTION
	43	Based on the values of
	44	.Fa key
	45	and
	46	.Fa semflg ,
	47	.Fn semget
	48	returns the identifier of a newly created or previously existing
	49	set of semaphores.
	50	.\"
	51	.\" This is copied verbatim from the shmget manpage. Perhaps
	52	.\" it should go in a common manpage, such as .Xr ipc 2
	53	.\"
	54	The key
	55	is analogous to a filename: it provides a handle that names an
	56	IPC object. There are three ways to specify a key:
	57	.Bl -bullet
	58	.It
	59	IPC_PRIVATE may be specified, in which case a new IPC object
	60	will be created.
	61	.It
	62	An integer constant may be specified. If no IPC object corresponding
	63	to
	64	.Fa key
	65	is specified and the IPC_CREAT bit is set in
	66	.Fa semflg ,
	67	a new one will be created.
	68	.It
	69	The
	70	.Xr ftok 3
	71	function
	72	may be used to generate a key from a pathname.
	73	.El
	74	.\"
	75	.\" Likewise for this section, except SHM_* becomes SEM_*.
	76	.\"
	77	.Pp
	78	The mode of a newly created IPC object is determined by
	79	.Em OR Ns 'ing
	80	the following constants into the
	81	.Fa semflg
	82	argument:
	83	.Bl -tag -width XSEM_WXX6XXX
	84	.It Dv SEM_R
	85	Read access for user.
	86	.It Dv SEM_A
	87	Alter access for user.
	88	.It Dv ( SEM_R>>3 )
	89	Read access for group.
	90	.It Dv ( SEM_A>>3 )
	91	Alter access for group.
	92	.It Dv ( SEM_R>>6 )
	93	Read access for other.
	94	.It Dv ( SEM_A>>6 )
	95	Alter access for other.
	96	.El
	97	.Pp
	98	If a new set of semaphores is being created,
	99	.Fa nsems
	100	is used to indicate the number of semaphores the set should contain.
	101	Otherwise,
	102	.Fa nsems
	103	may be specified as 0.
	104	.Sh RETURN VALUES
	105	The
	106	.Fn semget
	107	system call
	108	returns the id of a semaphore set if successful; otherwise, -1
	109	is returned and
	110	.Va errno
	111	is set to indicate the error.
	112	.Sh ERRORS
	113	The
	114	.Fn semget
	115	system call
	116	will fail if:
	117	.Bl -tag -width Er
	118	.\" ===========
	119	.\" ipcperm could fail (we're opening to read and write, as it were)
	120	.It Bq Er EACCES
	121	Access permission failure.
	122	.\" ===========
	123	.\"
	124	.\" sysv_sem.c is quite explicit about these,
	125	.\" so I'm pretty sure this is accurate
	126	.\"
	127	.It Bq Er EEXIST
	128	IPC_CREAT and IPC_EXCL were specified,
	129	and a semaphore set corresponding to
	130	.Fa key
	131	already exists.
	132	.\" ===========
	133	.It Bq Er EINVAL
	134	The number of semaphores requested
	135	is either less than 1 or greater than the system imposed maximum per set.
	136	.\" ===========
	137	.It Bq Er EINVAL
	138	A semaphore identifier exists for the argument key,
	139	but the number of semaphores in the set associated with it
	140	is less than
	141	.Fa nsems ,
	142	and
	143	.Fa nsems
	144	is non-zero.
	145	.\" ===========
	146	.It Bq Er ENOENT
	147	No semaphore set was found corresponding to
	148	.Fa key ,
	149	and IPC_CREAT was not specified.
	150	.\" ===========
	151	.It Bq Er ENOSPC
	152	Insufficiently many semaphores are available.
	153	.\" ===========
	154	.It Bq Er ENOSPC
	155	The kernel could not allocate a
	156	.Fa "struct semid_ds" .
	157	.El
	158	.Sh LEGACY SYNOPSIS
	159	.Fd #include <sys/types.h>
	160	.Fd #include <sys/ipc.h>
	161	.Fd #include <sys/sem.h>
	162	.Pp
	163	The include files
	164	.In sys/types.h
	165	and
	166	.In sys/ipc.h
	167	are necessary.
	168	.Sh SEE ALSO
	169	.Xr semctl 2 ,
	170	.Xr semop 2 ,
	171	.Xr ftok 3 ,
	172	.Xr compat 5