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

Commit	Line	Data
6d2010ae A	1	.\" $Darwin$
	2	.\"
	3	.\" Copyright (c) 1999-2002 Apple Computer, Inc. All rights reserved.
	4	.\"
	5	.\" @APPLE_LICENSE_HEADER_START@
	6	.\"
	7	.\" The contents of this file constitute Original Code as defined in and
	8	.\" are subject to the Apple Public Source License Version 1.1 (the
	9	.\" "License"). You may not use this file except in compliance with the
	10	.\" License. Please obtain a copy of the License at
	11	.\" http://www.apple.com/publicsource and read it before using this file.
	12	.\"
	13	.\" This Original Code and all software distributed under the License are
	14	.\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	15	.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	16	.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	17	.\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
	18	.\" License for the specific language governing rights and limitations
	19	.\" under the License.
	20	.\"
	21	.\" @APPLE_LICENSE_HEADER_END@
	22	.\"
	23	.Dd August 29, 2008
	24	.Dt SHM_OPEN 2
	25	.Os Darwin
	26	.Sh NAME
	27	.Nm shm_open
	28	.Nd open a shared memory object
	29	.Sh SYNOPSIS
	30	.Fd #include <sys/mman.h>
39236c6e	31	.Fd #include <fcntl.h>
6d2010ae A	32	.Ft int
	33	.Fo shm_open
	34	.Fa "const char *name"
	35	.Fa "int oflag"
	36	.Fa "..."
	37	.Fc
	38	.Pp
	39	The parameter "mode_t mode" is optional.
	40	.Sh DESCRIPTION
	41	The shared memory object referenced by
	42	.Fa name
	43	is opened for reading and/or writing as specified by the argument
	44	.Fa oflag
	45	and the file descriptor returned to the calling process.
	46	The returned file descriptor will be the lowest non-open file
	47	descriptor for the calling process, and is not shared with any
	48	other processes, as it is a new file descriptor. The new file
	49	descriptor will have the
	50	.Dv FD_CLOEXEC
	51	flag set.
	52	Repeated calls
	53	to
	54	.Nm shm_open
	55	with the same string value for
	56	.Fn name
	57	will return a file descriptor referring to the same shared memory
	58	object, provided that the object has not been unlinked by a call to
	59	.Fn shm_unlink .
	60	The
	61	.Fa oflag
	62	argument may indicate the file is to be
	63	created if it does not exist (by specifying the
	64	.Dv O_CREAT
	65	flag), in which case the file is created with mode
	66	.Fa mode
	67	as described in
	68	.Xr chmod 2
	69	and modified by the process' umask value (see
	70	.Xr umask 2 ) .
	71	.Pp
	72	The value of
	73	.Fa oflag
	74	is formed by
	75	.Em or Ns 'ing
	76	the following values:
	77	.Pp
	78	.Bd -literal -offset indent -compact
	79	O_RDONLY open for reading only
	80	O_RDWR open for reading and writing
	81	O_CREAT create object if it does not exist
	82	O_EXCL error if create and object exists
	83	O_TRUNC truncate size to 0
	84	.Ed
	85	.Pp
	86	Exactly one of
	87	.Dv O_RDONLY
	88	or
	89	.Dv O_RDWR
	90	must be specified.
	91	.Pp
	92	If
	93	.Dv O_TRUNC
	94	is specified and the
	95	file exists, the file is truncated to zero length.
96	If
97	.Dv O_EXCL
98	is set with
99	.Dv O_CREAT
100	and the file already
101	exists,
102	.Fn shm_open
103	returns an error. This may be used to
104	implement a simple exclusive access locking mechanism.
105	.Pp
106	If successful,
107	.Fn shm_open
108	returns a non-negative integer, termed a file descriptor.
109	It returns -1 and sets
110	.Va errno
111	on failure.
112	The file pointer used to mark the current position within the
113	memory object is set to the beginning of the object.
114	.Pp
115	When a new shared memory object is created it is given the
116	owner and group corresponding to the effective user and
117	group of the calling process. There is no visible entry in the
118	file system for the created object in this implementation.
119	.Pp
120	When a shared memory object is created, it persists until it
121	it unlinked and all other references are gone. Objects do
122	not persist across a system reboot.
123	.Pp
124	The system imposes a limit on the number of file descriptors
125	open simultaneously by one process.
39236c6e	126	.Xr getdtablesize 2
6d2010ae A	127	returns the current system limit.
	128	.Sh ERRORS
	129	The named object is opened unless:
	130	.Bl -tag -width Er
	131	.It Bq Er EACCES
	132	The required permissions (for reading and/or writing)
	133	are denied for the given flags.
	134	.It Bq Er EACCES
	135	.Dv O_CREAT
	136	is specified, the object does not exist, and permission to
	137	create the object is denied.
	138	.It Bq Er EEXIST
	139	.Dv O_CREAT
	140	and
	141	.Dv O_EXCL
	142	were specified and the object exists.
	143	.It Bq Er EINTR
	144	The
	145	.Fn shm_open
	146	operation was interrupted by a signal.
	147	.It Bq Er EINVAL
	148	The
	149	.Fn shm_open
	150	operation is not supported.
	151	.It Bq Er EMFILE
	152	The process has already reached its limit for open file descriptors.
	153	.It Bq Er ENAMETOOLONG
	154	.Fa name
	155	exceeded the name size limit.
	156	This is currently
	157	.Dv PSHMNAMLEN
	158	characters (defined in
	159	.In sys/posix_shm.h ) ,
	160	but this may change in the future.
	161	.It Bq Er ENFILE
	162	The system file table is full.
	163	.It Bq Er ENOENT
	164	.Dv O_CREAT
	165	is not set and the named object does not exist.
	166	.It Bq Er ENOSPC
	167	.Dv O_CREAT
	168	is specified, the file does not exist, and there is insufficient
	169	space available to create the object.
	170	.El
	171	.Sh SEE ALSO
	172	.Xr chmod 2 ,
	173	.Xr close 2 ,
	174	.Xr getdtablesize 2 ,
	175	.Xr mmap 2 ,
	176	.Xr shm_unlink 2 ,
	177	.Xr umask 2
	178	.Sh HISTORY
	179	.Fn shm_open
	180	is specified in the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995).