Changeset View
Standalone View
lib/libc/sys/shm_open.2
Show All 26 Lines | |||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd January 20, 2017 | .Dd January 20, 2017 | ||||
.Dt SHM_OPEN 2 | .Dt SHM_OPEN 2 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm shm_open , shm_unlink | .Nm shm_open , shm_rename , shm_unlink | ||||
.Nd "shared memory object operations" | .Nd "shared memory object operations" | ||||
.Sh LIBRARY | .Sh LIBRARY | ||||
.Lb libc | .Lb libc | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.In sys/types.h | .In sys/types.h | ||||
.In sys/mman.h | .In sys/mman.h | ||||
.In fcntl.h | .In fcntl.h | ||||
.Ft int | .Ft int | ||||
.Fn shm_open "const char *path" "int flags" "mode_t mode" | .Fn shm_open "const char *path" "int flags" "mode_t mode" | ||||
.Ft int | .Ft int | ||||
.Fn shm_rename "const char *path_from" "const char *path_to" "int flags" | |||||
jilles: I recommend adding an int flags here (for example, compare Linux's renameat2()). Since no flags… | |||||
Done Inline ActionsGood idea! I'm under crunch time, so I won't do this right now, but it is absolutely worth a TODO in the code to remember the idea. Marking 'done', having added the TODO. Please let me know if you think this is crucial enough to attack now. matthew.bryan_isilon.com: Good idea! I'm under crunch time, so I won't do this right now, but it is absolutely worth a… | |||||
Not Done Inline ActionsAdding this later is an incompatible ABI and API change, so it should be done soon and definitely before MFC or heavier use. jilles: Adding this later is an incompatible ABI and API change, so it should be done soon and… | |||||
Not Done Inline ActionsI actually asked for the flags mechanism only, without the actual flags like renameat2(). However, having it will be useful. jilles: I actually asked for the flags mechanism only, without the actual flags like renameat2(). | |||||
.Ft int | |||||
.Fn shm_unlink "const char *path" | .Fn shm_unlink "const char *path" | ||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | The | ||||
.Fn shm_open | .Fn shm_open | ||||
system call opens (or optionally creates) a | system call opens (or optionally creates) a | ||||
.Tn POSIX | .Tn POSIX | ||||
shared memory object named | shared memory object named | ||||
.Fa path . | .Fa path . | ||||
▲ Show 20 Lines • Show All 61 Lines • ▼ Show 20 Lines | |||||
.Dv SHM_ANON | .Dv SHM_ANON | ||||
may be used for the | may be used for the | ||||
.Fa path | .Fa path | ||||
argument to | argument to | ||||
.Fn shm_open . | .Fn shm_open . | ||||
In this case, an anonymous, unnamed shared memory object is created. | In this case, an anonymous, unnamed shared memory object is created. | ||||
Since the object has no name, | Since the object has no name, | ||||
it cannot be removed via a subsequent call to | it cannot be removed via a subsequent call to | ||||
.Fn shm_unlink . | .Fn shm_unlink , | ||||
Not Done Inline ActionsThe period (.) following shm_unlink should be replaced by a comma (,). Alternatively, just delete the period; a comma really isn't needed between the two clauses in this sentence. dab: The period (.) following shm_unlink should be replaced by a comma (,). Alternatively, just… | |||||
or moved with a call to | |||||
.Fn shm_rename . | |||||
Instead, | Instead, | ||||
the shared memory object will be garbage collected when the last reference to | the shared memory object will be garbage collected when the last reference to | ||||
the shared memory object is removed. | the shared memory object is removed. | ||||
The shared memory object may be shared with other processes by sharing the | The shared memory object may be shared with other processes by sharing the | ||||
file descriptor via | file descriptor via | ||||
.Xr fork 2 | .Xr fork 2 | ||||
or | or | ||||
.Xr sendmsg 2 . | .Xr sendmsg 2 . | ||||
Attempting to open an anonymous shared memory object with | Attempting to open an anonymous shared memory object with | ||||
.Dv O_RDONLY | .Dv O_RDONLY | ||||
will fail with | will fail with | ||||
.Er EINVAL . | .Er EINVAL . | ||||
All other flags are ignored. | All other flags are ignored. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn shm_rename | |||||
system call atomically removes a shared memory object named | |||||
.Fa path_from | |||||
and relinks it at | |||||
.Fa path_to . | |||||
If another object is already linked at | |||||
.Fa path_to , | |||||
that object will be unlinked, unless one of the following flags are provided: | |||||
.Bl -tag -offset indent -width Er | |||||
.It Er SHM_RENAME_EXCHANGE | |||||
Atomically exchange the shms at | |||||
.Fa path_from | |||||
and | |||||
.Fa path_to. | |||||
.It Er SHM_RENAME_NOREPLACE | |||||
Return an error if an shm exists at | |||||
.Fa path_to , | |||||
rather than unlinking it. | |||||
.El | |||||
.Fn shm_rename | |||||
is also a FreeBSD extension. | |||||
bruefferUnsubmitted Not Done Inline ActionsPlease use the .Fx macro instead of FreeBSD. brueffer: Please use the .Fx macro instead of FreeBSD. | |||||
.Pp | |||||
The | |||||
.Fn shm_unlink | .Fn shm_unlink | ||||
system call removes a shared memory object named | system call removes a shared memory object named | ||||
.Fa path . | .Fa path . | ||||
.Sh RETURN VALUES | .Sh RETURN VALUES | ||||
If successful, | If successful, | ||||
.Fn shm_open | .Fn shm_open | ||||
returns a non-negative integer, | returns a non-negative integer, | ||||
and | and | ||||
.Fn shm_rename | |||||
and | |||||
.Fn shm_unlink | .Fn shm_unlink | ||||
returns zero. | return zero. | ||||
Both functions return -1 on failure, and set | All functions return -1 on failure, and set | ||||
.Va errno | .Va errno | ||||
to indicate the error. | to indicate the error. | ||||
.Sh COMPATIBILITY | .Sh COMPATIBILITY | ||||
The | The | ||||
.Fa path | .Fa path , | ||||
argument does not necessarily represent a pathname (although it does in | .Fa path_from , | ||||
and | |||||
.Fa path_to | |||||
arguments do not necessarily represent a pathname (although they do in | |||||
most other implementations). | most other implementations). | ||||
Two processes opening the same | Two processes opening the same | ||||
.Fa path | .Fa path | ||||
are guaranteed to access the same shared memory object if and only if | are guaranteed to access the same shared memory object if and only if | ||||
.Fa path | .Fa path | ||||
begins with a slash | begins with a slash | ||||
.Pq Ql \&/ | .Pq Ql \&/ | ||||
character. | character. | ||||
▲ Show 20 Lines • Show All 77 Lines • ▼ Show 20 Lines | |||||
.Dv O_RDONLY | .Dv O_RDONLY | ||||
was specified while creating an anonymous shared memory object via | was specified while creating an anonymous shared memory object via | ||||
.Dv SHM_ANON . | .Dv SHM_ANON . | ||||
.It Bq Er EFAULT | .It Bq Er EFAULT | ||||
The | The | ||||
.Fa path | .Fa path | ||||
argument points outside the process' allocated address space. | argument points outside the process' allocated address space. | ||||
.It Bq Er ENAMETOOLONG | .It Bq Er ENAMETOOLONG | ||||
The entire pathname exceeded 1023 characters. | The entire pathname exceeds 1023 characters. | ||||
.It Bq Er EINVAL | .It Bq Er EINVAL | ||||
The | The | ||||
.Fa path | .Fa path | ||||
does not begin with a slash | does not begin with a slash | ||||
.Pq Ql \&/ | .Pq Ql \&/ | ||||
character. | character. | ||||
.It Bq Er ENOENT | .It Bq Er ENOENT | ||||
.Dv O_CREAT | .Dv O_CREAT | ||||
is specified and the named shared memory object does not exist. | is specified and the named shared memory object does not exist. | ||||
.It Bq Er EEXIST | .It Bq Er EEXIST | ||||
.Dv O_CREAT | .Dv O_CREAT | ||||
and | and | ||||
.Dv O_EXCL | .Dv O_EXCL | ||||
are specified and the named shared memory object does exist. | are specified and the named shared memory object does exist. | ||||
.It Bq Er EACCES | .It Bq Er EACCES | ||||
The required permissions (for reading or reading and writing) are denied. | The required permissions (for reading or reading and writing) are denied. | ||||
.El | .El | ||||
.Pp | .Pp | ||||
The following errors are defined for | |||||
Done Inline Actions.Fa path_from jilles: `.Fa path_from` | |||||
.Fn shm_rename : | |||||
.Bl -tag -width Er | |||||
.It Bq Er EFAULT | |||||
The | |||||
.Fa path_from | |||||
or | |||||
.Fa path_to | |||||
argument points outside the process' allocated address space. | |||||
.It Bq Er ENAMETOOLONG | |||||
The entire pathname exceeds 1023 characters. | |||||
Not Done Inline Actionss/exceeded/exceeds/ dab: s/exceeded/exceeds/ | |||||
.It Bq Er ENOENT | |||||
The shared memory object at | |||||
.Fa path_from | |||||
does not exist. | |||||
.It Bq Er EACCES | |||||
The required permissions are denied. | |||||
.It Bq Er EEXIST | |||||
An shm exists at | |||||
.Fa path_to , | |||||
and the | |||||
.Dv SHM_RENAME_NOREPLACE | |||||
flag was provided. | |||||
.El | |||||
.Pp | |||||
.Fn shm_unlink | .Fn shm_unlink | ||||
fails with these error codes for these conditions: | fails with these error codes for these conditions: | ||||
.Bl -tag -width Er | .Bl -tag -width Er | ||||
.It Bq Er EFAULT | .It Bq Er EFAULT | ||||
The | The | ||||
.Fa path | .Fa path | ||||
argument points outside the process' allocated address space. | argument points outside the process' allocated address space. | ||||
.It Bq Er ENAMETOOLONG | .It Bq Er ENAMETOOLONG | ||||
The entire pathname exceeded 1023 characters. | The entire pathname exceeds 1023 characters. | ||||
.It Bq Er ENOENT | .It Bq Er ENOENT | ||||
The named shared memory object does not exist. | The named shared memory object does not exist. | ||||
.It Bq Er EACCES | .It Bq Er EACCES | ||||
The required permissions are denied. | The required permissions are denied. | ||||
.Fn shm_unlink | .Fn shm_unlink | ||||
requires write permission to the shared memory object. | requires write permission to the shared memory object. | ||||
.El | .El | ||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
Show All 15 Lines | |||||
.Fn shm_open | .Fn shm_open | ||||
and | and | ||||
.Fn shm_unlink | .Fn shm_unlink | ||||
functions first appeared in | functions first appeared in | ||||
.Fx 4.3 . | .Fx 4.3 . | ||||
The functions were reimplemented as system calls using shared memory objects | The functions were reimplemented as system calls using shared memory objects | ||||
directly rather than files in | directly rather than files in | ||||
.Fx 8.0 . | .Fx 8.0 . | ||||
.Pp | |||||
.Fn shm_rename | |||||
first appeared in FreeBSD 13.0 as a FreeBSD-specific extension. | |||||
bruefferUnsubmitted Not Done Inline ActionsPlease use the .Fx macro instead of FreeBSD. brueffer: Please use the .Fx macro instead of FreeBSD. | |||||
.Sh AUTHORS | .Sh AUTHORS | ||||
.An Garrett A. Wollman Aq Mt wollman@FreeBSD.org | .An Garrett A. Wollman Aq Mt wollman@FreeBSD.org | ||||
(C library support and this manual page) | (C library support and this manual page) | ||||
.Pp | .Pp | ||||
.An Matthew Dillon Aq Mt dillon@FreeBSD.org | .An Matthew Dillon Aq Mt dillon@FreeBSD.org | ||||
.Pq Dv MAP_NOSYNC | .Pq Dv MAP_NOSYNC | ||||
.Pp | |||||
.An Matthew Bryan Aq Mt matthew.bryan@isilon.com | |||||
.Pq Dv shm_rename implementation |
I recommend adding an int flags here (for example, compare Linux's renameat2()). Since no flags are defined yet, any non-zero flags argument should cause the call to return error [EINVAL].