[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/shm.h>
.Ft void *
.Fo shmat
.Fa "int shmid"
.Fa "const void *shmaddr"
.Fa "int shmflg"
.Fc
.Ft int
.Fo shmdt
.Fa "const void *shmaddr"
.Fc
.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
The
.Fn shmat
system call 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 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.
.\" ===========
.It Bq Er ENOMEM
There is not enough available data space for the calling process to
map the shared memory segment.
.Pp
.El
The
.Fn shmdt
system call 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 LEGACY SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/ipc.h>
.Fd #include <sys/shm.h>
.Pp
The include files
.In sys/types.h
and
.In sys/ipc.h
are necessary for both functions.
.Sh SEE ALSO
.Xr mmap 2 ,
.Xr shmctl 2 ,
.Xr shmget 2 ,
.Xr compat 5
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
9bccf70c A	41	.Fd #include <sys/shm.h>
9bccf70c A	42	.Ft void *
2d21ac55 A	43	.Fo shmat
	44	.Fa "int shmid"
	45	.Fa "const void *shmaddr"
	46	.Fa "int shmflg"
	47	.Fc
9bccf70c	48	.Ft int
2d21ac55 A	49	.Fo shmdt
	50	.Fa "const void *shmaddr"
	51	.Fc
9bccf70c A	52	.Sh DESCRIPTION
	53	.Fn shmat
	54	maps the shared memory segment associated with the shared memory identifier
	55	.Fa shmid
	56	into the address space of the calling process. The address at which the
	57	segment is mapped is determined by the
	58	.Fa shmaddr
	59	parameter. If it is equal to 0, the system will pick an address itself.
	60	Otherwise, an attempt is made to map the shared memory segment at the
	61	address
	62	.Fa shmaddr
	63	specifies. If SHM_RND is set in
	64	.Fa shmflg ,
	65	the system will round the address down to a multiple of SHMLBA bytes
	66	(SHMLBA is defined in
	67	.Aq Pa sys/shm.h
	68	).
9bccf70c A	69	A shared memory segment can be mapped read-only by specifying the
	70	SHM_RDONLY flag in
	71	.Fa shmflg .
9bccf70c A	72	.Fn shmdt
	73	unmaps the shared memory segment that is currently mapped at
	74	.Fa shmaddr
	75	from the calling process' address space.
	76	.Fa shmaddr
	77	must be a value returned by a prior
	78	.Fn shmat
	79	call. A shared memory segment will remain existant until it is removed by
	80	a call to
	81	.Xr shmctl 2
	82	with the IPC_RMID command.
	83	.Sh RETURN VALUES
	84	.Fn shmat
	85	returns the address at which the shared memory segment has been mapped into
	86	the calling process' address space when successful,
	87	.Fn shmdt
	88	returns 0 on successful completion. Otherwise, a value of -1 is returned,
	89	and the global variable
	90	.Va errno
	91	is set to indicate the error.
	92	.Sh ERRORS
2d21ac55	93	The
9bccf70c	94	.Fn shmat
2d21ac55	95	system call will fail if:
9bccf70c	96	.Bl -tag -width Er
2d21ac55	97	.\" ===========
55e303ae	98	.It Bq Er EACCES
9bccf70c	99	The calling process has no permission to access this shared memory segment.
2d21ac55	100	.\" ===========
9bccf70c A	101	.It Bq Er EINVAL
	102	.Fa shmid
	103	is not a valid shared memory identifier.
9bccf70c A	104	.Fa shmaddr
9bccf70c A	105	specifies an illegal address.
2d21ac55	106	.\" ===========
9bccf70c A	107	.It Bq Er EMFILE
9bccf70c A	108	The number of shared memory segments has reached the system-wide limit.
2d21ac55 A	109	.\" ===========
	110	.It Bq Er ENOMEM
	111	There is not enough available data space for the calling process to
	112	map the shared memory segment.
	113	.Pp
9bccf70c	114	.El
2d21ac55	115	The
9bccf70c	116	.Fn shmdt
2d21ac55	117	system call will fail if:
9bccf70c A	118	.Bl -tag -width Er
	119	.It Bq Er EINVAL
	120	.Fa shmaddr
	121	is not the start address of a mapped shared memory segment.
55e303ae	122	.El
2d21ac55 A	123	.Sh LEGACY SYNOPSIS
	124	.Fd #include <sys/types.h>
	125	.Fd #include <sys/ipc.h>
	126	.Fd #include <sys/shm.h>
	127	.Pp
	128	The include files
	129	.In sys/types.h
	130	and
	131	.In sys/ipc.h
	132	are necessary for both functions.
9bccf70c	133	.Sh SEE ALSO
2d21ac55	134	.Xr mmap 2 ,
9bccf70c A	135	.Xr shmctl 2 ,
9bccf70c A	136	.Xr shmget 2 ,
2d21ac55	137	.Xr compat 5