[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 EACCESS
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.
.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	).
65
66	A shared memory segment can be mapped read-only by specifying the
67	SHM_RDONLY flag in
68	.Fa shmflg .
69
70	.Fn shmdt
71	unmaps the shared memory segment that is currently mapped at
72	.Fa shmaddr
73	from the calling process' address space.
74	.Fa shmaddr
75	must be a value returned by a prior
76	.Fn shmat
77	call. A shared memory segment will remain existant until it is removed by
78	a call to
79	.Xr shmctl 2
80	with the IPC_RMID command.
81	.Sh RETURN VALUES
82	.Fn shmat
83	returns the address at which the shared memory segment has been mapped into
84	the calling process' address space when successful,
85	.Fn shmdt
86	returns 0 on successful completion. Otherwise, a value of -1 is returned,
87	and the global variable
88	.Va errno
89	is set to indicate the error.
90	.Sh ERRORS
91	.Fn shmat
92	will fail if:
93	.Bl -tag -width Er
94	.It Bq Er EACCESS
95	The calling process has no permission to access this shared memory segment.
96	.It Bq Er ENOMEM
97	There is not enough available data space for the calling process to
98	map the shared memory segment.
99	.It Bq Er EINVAL
100	.Fa shmid
101	is not a valid shared memory identifier.
102
103	.Fa shmaddr
104	specifies an illegal address.
105	.It Bq Er EMFILE
106	The number of shared memory segments has reached the system-wide limit.
107	.El
108
109	.Fn shmdt
110	will fail if:
111	.Bl -tag -width Er
112	.It Bq Er EINVAL
113	.Fa shmaddr
114	is not the start address of a mapped shared memory segment.
115	.Sh SEE ALSO
116	.Xr shmctl 2 ,
117	.Xr shmget 2 ,
118	.Xr mmap 2