shm_unlink(3)

1SHM_OPEN(3)                Linux Programmer's Manual               SHM_OPEN(3)
2
3
4

NAME

6       shm_open,  shm_unlink  -  Create/open  or  unlink  POSIX  shared memory
7       objects
8

SYNOPSIS

10       #include <sys/types.h>
11       #include <sys/mman.h>
12       #include <fcntl.h>           /* For O_* constants */
13
14       int shm_open(const char *name, int oflag, mode_t mode);
15
16       int shm_unlink(const char *name);
17

DESCRIPTION

19       shm_open() creates and opens a new, or opens an existing, POSIX  shared
20       memory  object.   A  POSIX  shared  memory object is in effect a handle
21       which can be used by unrelated processes to mmap(2) the same region  of
22       shared  memory.  The shm_unlink() function performs the converse opera‐
23       tion, removing an object previously created by shm_open().
24
25       The operation of shm_open() is analogous  to  that  of  open(2).   name
26       specifies the shared memory object to be created or opened.  For porta‐
27       ble use, name should have an initial slash (/) and contain no  embedded
28       slashes.
29
30       oflag  is  a bit mask created by ORing together exactly one of O_RDONLY
31       or O_RDWR and any of the other flags listed here:
32
33       O_RDONLY   Open the object for read access.   A  shared  memory  object
34                  opened   in   this  way  can  only  be  mmap(2)ed  for  read
35                  (PROT_READ) access.
36
37       O_RDWR     Open the object for read-write access.
38
39       O_CREAT    Create the shared memory object if it does not  exist.   The
40                  user  and  group  ownership of the object are taken from the
41                  corresponding effective IDs of the calling process, and  the
42                  object's  permission bits are set according to the low-order
43                  9 bits of mode, except that those bits set  in  the  process
44                  file  mode  creation mask (see umask(2)) are cleared for the
45                  new object.  A set of macro constants which can be  used  to
46                  define mode is listed in open(2).
47
48                  A  new  shared memory object initially has zero length — the
49                  size of the object can be set using ftruncate(2).  The newly
50                  allocated  bytes of a shared memory object are automatically
51                  initialised to 0.
52
53       O_EXCL     If O_CREAT was also specified, and a  shared  memory  object
54                  with  the  given  name already exists, return an error.  The
55                  check for the existence of the object, and its  creation  if
56                  it does not exist, are performed atomically.
57
58       O_TRUNC    If  the  shared memory object already exists, truncate it to
59                  zero bytes.
60
61       On successful completion  shm_open()  returns  a  new  file  descriptor
62       referring to the shared memory object.  This file descriptor is guaran‐
63       teed to be the lowest-numbered file descriptor  not  previously  opened
64       within  the process.  The FD_CLOEXEC flag (see fcntl(2)) is set for the
65       file descriptor.
66
67       The file descriptor is normally used  in  subsequent  calls  to  ftrun‐
68       cate(2)  (for  a  newly  created  object) and mmap(2).  After a call to
69       mmap(2) the file descriptor may be closed without affecting the  memory
70       mapping.
71
72       The  operation  of shm_unlink() is analogous to unlink(2): it removes a
73       shared memory object name, and, once all processes  have  unmapped  the
74       object, de-allocates and destroys the contents of the associated memory
75       region.  After a successful shm_unlink(),  attempts  to  shm_open()  an
76       object  with  the same name will fail (unless O_CREAT was specified, in
77       which case a new, distinct object is created).
78

RETURN VALUE

80       On success, shm_open() returns  a  non-negative  file  descriptor.   On
81       failure,  shm_open() returns -1.  shm_unlink() returns 0 on success, or
82       -1 on error.
83

ERRORS

85       On failure, errno is set to indicate the cause of  the  error.   Values
86       which may appear in errno include the following:
87
88       EACCES Permission to shm_unlink() the shared memory object was denied.
89
90       EACCES Permission  was denied to shm_open() name in the specified mode,
91              or O_TRUNC was specified and the caller does not have write per‐
92              mission on the object.
93
94       EEXIST Both  O_CREAT  and  O_EXCL  were specified to shm_open() and the
95              shared memory object specified by name already exists.
96
97       EINVAL The name argument to shm_open() was invalid.
98
99       EMFILE The process already has the maximum number of files open.
100
101       ENAMETOOLONG
102              The length of name exceeds PATH_MAX.
103
104       ENFILE The limit on the total number of files open on  the  system  has
105              been reached.
106
107       ENOENT An attempt was made to shm_open() a name that did not exist, and
108              O_CREAT was not specified.
109
110       ENOENT An attempt was to made to shm_unlink()  a  name  that  does  not
111              exist.
112

NOTES

114       These  functions  are  provided in glibc 2.2 and later.  Programs using
115       these functions must specify the -lrt flag  to  cc  in  order  to  link
116       against the required ("realtime") library.
117
118       POSIX  leaves  the  behavior of the combination of O_RDONLY and O_TRUNC
119       unspecified.  On Linux, this will  successfully  truncate  an  existing
120       shared memory object — this may not be so on other Unix systems.
121
122       The POSIX shared memory object implementation on Linux 2.4 makes use of
123       a dedicated file system, which is normally mounted under /dev/shm.
124

CONFORMING TO

126       POSIX.1-2001.
127
128       POSIX.1-2001 says that the group ownership of a  newly  created  shared
129       memory object is set to either the calling process's effective group ID
130       or "a system default group ID"
131