Add shm_open(3) and shm_unlink(3). The documentation could use a good
bit of work (and is stylistically probably the worst manual page I've ever written).
This commit is contained in:
Garrett Wollman
parent
aa543039b5
commit
5c317306cb
@ -19,6 +19,7 @@ SRCS+= _rand48.c _spinlock_stub.c alarm.c arc4random.c assert.c \
|
||||
msgget.c msgrcv.c msgsnd.c nice.c \
|
||||
nlist.c nrand48.c ntp_gettime.c opendir.c \
|
||||
pause.c popen.c psignal.c pwcache.c raise.c readdir.c rewinddir.c \
|
||||
posixshm.c \
|
||||
scandir.c seed48.c seekdir.c semconfig.c semctl.c semget.c semop.c \
|
||||
setdomainname.c sethostname.c setjmperr.c setmode.c shmat.c \
|
||||
shmctl.c shmdt.c shmget.c siginterrupt.c siglist.c signal.c \
|
||||
@ -45,8 +46,8 @@ MAN3+= alarm.3 arc4random.3 clock.3 \
|
||||
glob.3 initgroups.3 isinf.3 \
|
||||
ldexp.3 lockf.3 modf.3 msgctl.3 msgget.3 msgrcv.3 msgsnd.3 \
|
||||
nice.3 nlist.3 pause.3 popen.3 psignal.3 pwcache.3 \
|
||||
raise.3 rand48.3 scandir.3 setjmp.3 setmode.3 siginterrupt.3 \
|
||||
signal.3 sigsetops.3 sleep.3 stringlist.3 \
|
||||
raise.3 rand48.3 scandir.3 setjmp.3 setmode.3 shm_open.3 \
|
||||
siginterrupt.3 signal.3 sigsetops.3 sleep.3 stringlist.3 \
|
||||
sysconf.3 sysctl.3 syslog.3 tcgetpgrp.3 \
|
||||
tcsendbreak.3 tcsetattr.3 tcsetpgrp.3 time.3 times.3 timezone.3 \
|
||||
ttyname.3 tzset.3 ualarm.3 uname.3 unvis.3 usleep.3 utime.3 \
|
||||
@ -104,6 +105,7 @@ MLINKS+=setjmp.3 _longjmp.3 setjmp.3 _setjmp.3 setjmp.3 longjmp.3 \
|
||||
setjmp.3 longjmperr.3 setjmp.3 longjmperror.3 \
|
||||
setjmp.3 siglongjmp.3 setjmp.3 sigsetjmp.3
|
||||
MLINKS+=setmode.3 getmode.3
|
||||
MLINKS+=shm_open.3 shm_unlink.3
|
||||
MLINKS+=sigsetops.3 sigaddset.3 sigsetops.3 sigdelset.3 \
|
||||
sigsetops.3 sigemptyset.3 sigsetops.3 sigfillset.3 \
|
||||
sigsetops.3 sigismember.3
|
||||
|
||||
69
lib/libc/gen/posixshm.c
Normal file
69
lib/libc/gen/posixshm.c
Normal file
@ -0,0 +1,69 @@
|
||||
/*
|
||||
* Copyright 2000 Massachusetts Institute of Technology
|
||||
*
|
||||
* Permission to use, copy, modify, and distribute this software and
|
||||
* its documentation for any purpose and without fee is hereby
|
||||
* granted, provided that both the above copyright notice and this
|
||||
* permission notice appear in all copies, that both the above
|
||||
* copyright notice and this permission notice appear in all
|
||||
* supporting documentation, and that the name of M.I.T. not be used
|
||||
* in advertising or publicity pertaining to distribution of the
|
||||
* software without specific, written prior permission. M.I.T. makes
|
||||
* no representations about the suitability of this software for any
|
||||
* purpose. It is provided "as is" without express or implied
|
||||
* warranty.
|
||||
*
|
||||
* THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS
|
||||
* ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
|
||||
* INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
||||
* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
|
||||
* SHALL M.I.T. 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.
|
||||
*
|
||||
* $FreeBSD$
|
||||
*/
|
||||
|
||||
#include <sys/types.h>
|
||||
#include <sys/fcntl.h>
|
||||
#include <sys/mman.h>
|
||||
#include <sys/stat.h>
|
||||
|
||||
#include <errno.h>
|
||||
#include <unistd.h>
|
||||
|
||||
int
|
||||
shm_open(const char *path, int flags, mode_t mode)
|
||||
{
|
||||
int fd;
|
||||
struct stat stab;
|
||||
|
||||
if ((flags & O_ACCMODE) == O_WRONLY)
|
||||
return (EINVAL);
|
||||
|
||||
fd = open(path, flags, mode);
|
||||
if (fd != -1) {
|
||||
if (fstat(fd, &stab) != 0 || !S_ISREG(stab.st_mode)) {
|
||||
close(fd);
|
||||
errno = EINVAL;
|
||||
return (-1);
|
||||
}
|
||||
|
||||
if (fcntl(fd, F_SETFL, (int)FPOSIXSHM) != 0) {
|
||||
close(fd);
|
||||
return (-1);
|
||||
}
|
||||
}
|
||||
return (fd);
|
||||
}
|
||||
|
||||
int
|
||||
shm_unlink(const char *path)
|
||||
{
|
||||
return (unlink(path));
|
||||
}
|
||||
192
lib/libc/gen/shm_open.3
Normal file
192
lib/libc/gen/shm_open.3
Normal file
@ -0,0 +1,192 @@
|
||||
.\"
|
||||
.\" Copyright 2000 Massachusetts Institute of Technology
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software and
|
||||
.\" its documentation for any purpose and without fee is hereby
|
||||
.\" granted, provided that both the above copyright notice and this
|
||||
.\" permission notice appear in all copies, that both the above
|
||||
.\" copyright notice and this permission notice appear in all
|
||||
.\" supporting documentation, and that the name of M.I.T. not be used
|
||||
.\" in advertising or publicity pertaining to distribution of the
|
||||
.\" software without specific, written prior permission. M.I.T. makes
|
||||
.\" no representations about the suitability of this software for any
|
||||
.\" purpose. It is provided "as is" without express or implied
|
||||
.\" warranty.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS
|
||||
.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
|
||||
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
||||
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
|
||||
.\" SHALL M.I.T. 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.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd March 24, 2000
|
||||
.Dt SHM_OPEN 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm shm_open
|
||||
.Nd open or create a shared memory object
|
||||
.Nm shm_unlink
|
||||
.Nd remove a shared memory object
|
||||
.Sh SYNOPSIS
|
||||
.Fd #include <sys/types.h>
|
||||
.Fd #include <sys/mman.h>
|
||||
.Ft int
|
||||
.Fn shm_open "const char *path" "int flags" "mode_t mode"
|
||||
.Ft int
|
||||
.Fn shm_unlink "const char *path"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Nm shm_open
|
||||
function opens (or optionally creates) a
|
||||
.Tn POSIX
|
||||
shared memory object named
|
||||
.Fa path .
|
||||
The
|
||||
.Nm shm_unlink
|
||||
function removes a shared memory object named
|
||||
.Fa path .
|
||||
.Pp
|
||||
In the
|
||||
.Fx
|
||||
implementation,
|
||||
.Tn POSIX
|
||||
shared memory objects are implemented as ordinary files.
|
||||
The
|
||||
.Nm shm_open
|
||||
and
|
||||
.Nm shm_unlink
|
||||
act as wrappers around the
|
||||
.Xr open 2
|
||||
and
|
||||
.Xr unlink 2
|
||||
routines, and
|
||||
.Fa path ,
|
||||
.Fa flags ,
|
||||
and
|
||||
.Fa mode
|
||||
arguments are as specified for those functions.
|
||||
The
|
||||
.Fa flags
|
||||
argument is checked to ensure that the access mode specified is not
|
||||
.Dv O_WRONLY
|
||||
(which is not defined for shared memory objects).
|
||||
.Pp
|
||||
In addition, the
|
||||
.Fx
|
||||
implementation causes
|
||||
.Fn mmap
|
||||
of a descriptor returned by
|
||||
.Nm shm_open
|
||||
to behave as if the
|
||||
.Dv MAP_ASYNC
|
||||
flag had been specified to
|
||||
.Xr mmap 2 .
|
||||
(It does so by setting a special file flag using
|
||||
.Xr fcntl 2 . )
|
||||
.Pp
|
||||
The
|
||||
.Nm shm_unlink
|
||||
function makes no effort to ensure that
|
||||
.Fa path
|
||||
refers to a shared memory object.
|
||||
.Sh PORTABILITY
|
||||
The
|
||||
.Fa path
|
||||
argument does not necessarily represent a pathname (although it does in this
|
||||
and most other implementations).
|
||||
Two processes opening the same
|
||||
.Fa path
|
||||
are guaranteed to access the same shared memory object if and only if
|
||||
.Fa path
|
||||
begins with a slash
|
||||
.Pq Ql \&/
|
||||
character.
|
||||
.Pp
|
||||
Only the
|
||||
.Dv O_RDONLY ,
|
||||
.Dv O_RDWR ,
|
||||
.Dv O_CREAT ,
|
||||
.Dv O_EXCL ,
|
||||
and
|
||||
.Dv O_TRUNC
|
||||
flags may be used in portable programs.
|
||||
.Pp
|
||||
The result of using
|
||||
.Xr open 2 ,
|
||||
.Xr read 2 ,
|
||||
or
|
||||
.Xr write 2
|
||||
on a shared memory object, or on the descriptor returned by
|
||||
.Fn shm_open ,
|
||||
is undefined.
|
||||
It is also undefined whether the shared memory object itself, or its
|
||||
contents, persist across reboots.
|
||||
.Sh RETURN VALUES
|
||||
If successful,
|
||||
.Fn shm_open
|
||||
returns a non-negative integer;
|
||||
.Fn shm_unlink
|
||||
returns zero.
|
||||
Both functions return -1 on failure, and set
|
||||
.Va errno
|
||||
to indicate the error.
|
||||
.Sh ERRORS
|
||||
The
|
||||
.Fn shm_open
|
||||
and
|
||||
.Fn shm_unlink
|
||||
functions can fail with any error defined for
|
||||
.Fn open
|
||||
and
|
||||
.Fn unlink ,
|
||||
respectively. In addition, the following errors are defined for
|
||||
.Fn shm_open :
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EINVAL
|
||||
The object named by
|
||||
.Fa path
|
||||
is not a shared memory object
|
||||
(i.e., it is not a regular file).
|
||||
.It Bq Er EINVAL
|
||||
The
|
||||
.Fa flags
|
||||
argument to
|
||||
.Fn shm_open
|
||||
specifies an access mode of
|
||||
.Dv O_WRONLY .
|
||||
.El
|
||||
.Sh SEE ALSO
|
||||
.Xr mmap 2 ,
|
||||
.Xr munmap 2 ,
|
||||
.Xr open 2 ,
|
||||
.Xr unlink 2
|
||||
.Sh STANDARDS
|
||||
The
|
||||
.Nm shm_open
|
||||
and
|
||||
.Nm shm_unlink
|
||||
functions are believed to conform to
|
||||
.St -p1003.1b .
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Nm shm_open
|
||||
and
|
||||
.Nm shm_unlink
|
||||
functions first appeared in
|
||||
.Fx 5.0 .
|
||||
.Sh AUTHORS
|
||||
.An Garrett A. Wollman Aq wollman@FreeBSD.org
|
||||
(C library support and this manual page)
|
||||
.Pp
|
||||
.An Matthew Dillon Aq dillon@FreeBSD.org
|
||||
.Pq Dv MAP_NOSYNC
|
||||
|
||||
192
lib/libc/sys/shm_open.2
Normal file
192
lib/libc/sys/shm_open.2
Normal file
@ -0,0 +1,192 @@
|
||||
.\"
|
||||
.\" Copyright 2000 Massachusetts Institute of Technology
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software and
|
||||
.\" its documentation for any purpose and without fee is hereby
|
||||
.\" granted, provided that both the above copyright notice and this
|
||||
.\" permission notice appear in all copies, that both the above
|
||||
.\" copyright notice and this permission notice appear in all
|
||||
.\" supporting documentation, and that the name of M.I.T. not be used
|
||||
.\" in advertising or publicity pertaining to distribution of the
|
||||
.\" software without specific, written prior permission. M.I.T. makes
|
||||
.\" no representations about the suitability of this software for any
|
||||
.\" purpose. It is provided "as is" without express or implied
|
||||
.\" warranty.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS
|
||||
.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
|
||||
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
||||
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
|
||||
.\" SHALL M.I.T. 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.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd March 24, 2000
|
||||
.Dt SHM_OPEN 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm shm_open
|
||||
.Nd open or create a shared memory object
|
||||
.Nm shm_unlink
|
||||
.Nd remove a shared memory object
|
||||
.Sh SYNOPSIS
|
||||
.Fd #include <sys/types.h>
|
||||
.Fd #include <sys/mman.h>
|
||||
.Ft int
|
||||
.Fn shm_open "const char *path" "int flags" "mode_t mode"
|
||||
.Ft int
|
||||
.Fn shm_unlink "const char *path"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Nm shm_open
|
||||
function opens (or optionally creates) a
|
||||
.Tn POSIX
|
||||
shared memory object named
|
||||
.Fa path .
|
||||
The
|
||||
.Nm shm_unlink
|
||||
function removes a shared memory object named
|
||||
.Fa path .
|
||||
.Pp
|
||||
In the
|
||||
.Fx
|
||||
implementation,
|
||||
.Tn POSIX
|
||||
shared memory objects are implemented as ordinary files.
|
||||
The
|
||||
.Nm shm_open
|
||||
and
|
||||
.Nm shm_unlink
|
||||
act as wrappers around the
|
||||
.Xr open 2
|
||||
and
|
||||
.Xr unlink 2
|
||||
routines, and
|
||||
.Fa path ,
|
||||
.Fa flags ,
|
||||
and
|
||||
.Fa mode
|
||||
arguments are as specified for those functions.
|
||||
The
|
||||
.Fa flags
|
||||
argument is checked to ensure that the access mode specified is not
|
||||
.Dv O_WRONLY
|
||||
(which is not defined for shared memory objects).
|
||||
.Pp
|
||||
In addition, the
|
||||
.Fx
|
||||
implementation causes
|
||||
.Fn mmap
|
||||
of a descriptor returned by
|
||||
.Nm shm_open
|
||||
to behave as if the
|
||||
.Dv MAP_ASYNC
|
||||
flag had been specified to
|
||||
.Xr mmap 2 .
|
||||
(It does so by setting a special file flag using
|
||||
.Xr fcntl 2 . )
|
||||
.Pp
|
||||
The
|
||||
.Nm shm_unlink
|
||||
function makes no effort to ensure that
|
||||
.Fa path
|
||||
refers to a shared memory object.
|
||||
.Sh PORTABILITY
|
||||
The
|
||||
.Fa path
|
||||
argument does not necessarily represent a pathname (although it does in this
|
||||
and most other implementations).
|
||||
Two processes opening the same
|
||||
.Fa path
|
||||
are guaranteed to access the same shared memory object if and only if
|
||||
.Fa path
|
||||
begins with a slash
|
||||
.Pq Ql \&/
|
||||
character.
|
||||
.Pp
|
||||
Only the
|
||||
.Dv O_RDONLY ,
|
||||
.Dv O_RDWR ,
|
||||
.Dv O_CREAT ,
|
||||
.Dv O_EXCL ,
|
||||
and
|
||||
.Dv O_TRUNC
|
||||
flags may be used in portable programs.
|
||||
.Pp
|
||||
The result of using
|
||||
.Xr open 2 ,
|
||||
.Xr read 2 ,
|
||||
or
|
||||
.Xr write 2
|
||||
on a shared memory object, or on the descriptor returned by
|
||||
.Fn shm_open ,
|
||||
is undefined.
|
||||
It is also undefined whether the shared memory object itself, or its
|
||||
contents, persist across reboots.
|
||||
.Sh RETURN VALUES
|
||||
If successful,
|
||||
.Fn shm_open
|
||||
returns a non-negative integer;
|
||||
.Fn shm_unlink
|
||||
returns zero.
|
||||
Both functions return -1 on failure, and set
|
||||
.Va errno
|
||||
to indicate the error.
|
||||
.Sh ERRORS
|
||||
The
|
||||
.Fn shm_open
|
||||
and
|
||||
.Fn shm_unlink
|
||||
functions can fail with any error defined for
|
||||
.Fn open
|
||||
and
|
||||
.Fn unlink ,
|
||||
respectively. In addition, the following errors are defined for
|
||||
.Fn shm_open :
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EINVAL
|
||||
The object named by
|
||||
.Fa path
|
||||
is not a shared memory object
|
||||
(i.e., it is not a regular file).
|
||||
.It Bq Er EINVAL
|
||||
The
|
||||
.Fa flags
|
||||
argument to
|
||||
.Fn shm_open
|
||||
specifies an access mode of
|
||||
.Dv O_WRONLY .
|
||||
.El
|
||||
.Sh SEE ALSO
|
||||
.Xr mmap 2 ,
|
||||
.Xr munmap 2 ,
|
||||
.Xr open 2 ,
|
||||
.Xr unlink 2
|
||||
.Sh STANDARDS
|
||||
The
|
||||
.Nm shm_open
|
||||
and
|
||||
.Nm shm_unlink
|
||||
functions are believed to conform to
|
||||
.St -p1003.1b .
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Nm shm_open
|
||||
and
|
||||
.Nm shm_unlink
|
||||
functions first appeared in
|
||||
.Fx 5.0 .
|
||||
.Sh AUTHORS
|
||||
.An Garrett A. Wollman Aq wollman@FreeBSD.org
|
||||
(C library support and this manual page)
|
||||
.Pp
|
||||
.An Matthew Dillon Aq dillon@FreeBSD.org
|
||||
.Pq Dv MAP_NOSYNC
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user