[apple/xnu.git] / bsd / man / man2 / shmat.2

.\"   $OpenBSD: shmat.2,v 1.2 1996/10/08 01:20:15 michaels Exp $
.\"	$NetBSD: shmat.2,v 1.1 1995/10/16 23:49:29 jtc Exp $	
.\"
.\" Copyright (c) 1995 Frank van der Linden
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"      This product includes software developed for the NetBSD Project
.\"      by Frank van der Linden
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"/
.Dd August 17, 1995
.Dt SHMAT 2
.Os
.Sh NAME
.Nm shmat ,
.Nm shmdt
.Nd map/unmap shared memory
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/ipc.h>
.Fd #include <sys/shm.h>
.Ft void *
.Fn shmat "int shmid" "void *shmaddr" "int shmflg"
.Ft int
.Fn shmdt "void *shmaddr"
.Sh DESCRIPTION
.Fn shmat
maps the shared memory segment associated with the shared memory identifier
.Fa shmid
into the address space of the calling process. The address at which the
segment is mapped is determined by the
.Fa shmaddr
parameter. If it is equal to 0, the system will pick an address itself.
Otherwise, an attempt is made to map the shared memory segment at the
address
.Fa shmaddr
specifies. If SHM_RND is set in
.Fa shmflg ,
the system will round the address down to a multiple of SHMLBA bytes
(SHMLBA is defined in
.Aq Pa sys/shm.h
).
A shared memory segment can be mapped read-only by specifying the
SHM_RDONLY flag in
.Fa shmflg .
.Fn shmdt
unmaps the shared memory segment that is currently mapped at
.Fa shmaddr
from the calling process' address space.
.Fa shmaddr
must be a value returned by a prior
.Fn shmat
call. A shared memory segment will remain existant until it is removed by
a call to
.Xr shmctl 2
with the IPC_RMID command.
.Sh RETURN VALUES
.Fn shmat
returns the address at which the shared memory segment has been mapped into
the calling process' address space when successful, 
.Fn shmdt
returns 0 on successful completion. Otherwise, a value of -1 is returned,
and the global variable
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn shmat
will fail if:
.Bl -tag -width Er
.It Bq Er EACCES
The calling process has no permission to access this shared memory segment.
.It Bq Er ENOMEM
There is not enough available data space for the calling process to
map the shared memory segment.
.It Bq Er EINVAL
.Fa shmid
is not a valid shared memory identifier.
.Fa shmaddr
specifies an illegal address.
.It Bq Er EMFILE
The number of shared memory segments has reached the system-wide limit.
.El
.Fn shmdt
will fail if:
.Bl -tag -width Er
.It Bq Er EINVAL
.Fa shmaddr
is not the start address of a mapped shared memory segment.
.El
.Sh SEE ALSO
.Xr shmctl 2 ,
.Xr shmget 2 ,
.Xr mmap 2
Commit	Line	Data
9bccf70c A	1	.\" $OpenBSD: shmat.2,v 1.2 1996/10/08 01:20:15 michaels Exp $
	2	.\" $NetBSD: shmat.2,v 1.1 1995/10/16 23:49:29 jtc Exp $
	3	.\"
	4	.\" Copyright (c) 1995 Frank van der Linden
	5	.\" All rights reserved.
	6	.\"
	7	.\" Redistribution and use in source and binary forms, with or without
	8	.\" modification, are permitted provided that the following conditions
	9	.\" are met:
	10	.\" 1. Redistributions of source code must retain the above copyright
	11	.\" notice, this list of conditions and the following disclaimer.
	12	.\" 2. Redistributions in binary form must reproduce the above copyright
	13	.\" notice, this list of conditions and the following disclaimer in the
	14	.\" documentation and/or other materials provided with the distribution.
	15	.\" 3. All advertising materials mentioning features or use of this software
	16	.\" must display the following acknowledgement:
	17	.\" This product includes software developed for the NetBSD Project
	18	.\" by Frank van der Linden
	19	.\" 4. The name of the author may not be used to endorse or promote products
	20	.\" derived from this software without specific prior written permission
	21	.\"
	22	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
	23	.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	24	.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
	25	.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
	26	.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
	27	.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
	28	.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
	29	.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	30	.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
	31	.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	32	.\"/
	33	.Dd August 17, 1995
	34	.Dt SHMAT 2
	35	.Os
	36	.Sh NAME
	37	.Nm shmat ,
	38	.Nm shmdt
	39	.Nd map/unmap shared memory
	40	.Sh SYNOPSIS
	41	.Fd #include <sys/types.h>
	42	.Fd #include <sys/ipc.h>
	43	.Fd #include <sys/shm.h>
	44	.Ft void *
	45	.Fn shmat "int shmid" "void *shmaddr" "int shmflg"
	46	.Ft int
	47	.Fn shmdt "void *shmaddr"
	48	.Sh DESCRIPTION
	49	.Fn shmat
	50	maps the shared memory segment associated with the shared memory identifier
	51	.Fa shmid
	52	into the address space of the calling process. The address at which the
	53	segment is mapped is determined by the
	54	.Fa shmaddr
	55	parameter. If it is equal to 0, the system will pick an address itself.
	56	Otherwise, an attempt is made to map the shared memory segment at the
	57	address
	58	.Fa shmaddr
	59	specifies. If SHM_RND is set in
	60	.Fa shmflg ,
	61	the system will round the address down to a multiple of SHMLBA bytes
	62	(SHMLBA is defined in
	63	.Aq Pa sys/shm.h
	64	).
9bccf70c A	65	A shared memory segment can be mapped read-only by specifying the
	66	SHM_RDONLY flag in
	67	.Fa shmflg .
9bccf70c A	68	.Fn shmdt
	69	unmaps the shared memory segment that is currently mapped at
	70	.Fa shmaddr
	71	from the calling process' address space.
	72	.Fa shmaddr
	73	must be a value returned by a prior
	74	.Fn shmat
	75	call. A shared memory segment will remain existant until it is removed by
	76	a call to
	77	.Xr shmctl 2
	78	with the IPC_RMID command.
	79	.Sh RETURN VALUES
	80	.Fn shmat
	81	returns the address at which the shared memory segment has been mapped into
	82	the calling process' address space when successful,
	83	.Fn shmdt
	84	returns 0 on successful completion. Otherwise, a value of -1 is returned,
	85	and the global variable
	86	.Va errno
	87	is set to indicate the error.
	88	.Sh ERRORS
	89	.Fn shmat
	90	will fail if:
	91	.Bl -tag -width Er
55e303ae	92	.It Bq Er EACCES
9bccf70c A	93	The calling process has no permission to access this shared memory segment.
	94	.It Bq Er ENOMEM
	95	There is not enough available data space for the calling process to
	96	map the shared memory segment.
	97	.It Bq Er EINVAL
	98	.Fa shmid
	99	is not a valid shared memory identifier.
9bccf70c A	100	.Fa shmaddr
	101	specifies an illegal address.
	102	.It Bq Er EMFILE
	103	The number of shared memory segments has reached the system-wide limit.
	104	.El
9bccf70c A	105	.Fn shmdt
	106	will fail if:
	107	.Bl -tag -width Er
	108	.It Bq Er EINVAL
	109	.Fa shmaddr
	110	is not the start address of a mapped shared memory segment.
55e303ae	111	.El
9bccf70c A	112	.Sh SEE ALSO
	113	.Xr shmctl 2 ,
	114	.Xr shmget 2 ,
	115	.Xr mmap 2