diff options
Diffstat (limited to 'man/man3/shm_open.3')
| -rw-r--r-- | man/man3/shm_open.3 | 521 |
1 files changed, 521 insertions, 0 deletions
diff --git a/man/man3/shm_open.3 b/man/man3/shm_open.3 new file mode 100644 index 000000000..a907df906 --- /dev/null +++ b/man/man3/shm_open.3 @@ -0,0 +1,521 @@ +'\" t +.\" Copyright (C) 2002, 2020 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH shm_open 3 (date) "Linux man-pages (unreleased)" +.SH NAME +shm_open, shm_unlink \- create/open or unlink POSIX shared memory objects +.SH LIBRARY +Real-time library +.RI ( librt ", " \-lrt ) +.SH SYNOPSIS +.nf +.B #include <sys/mman.h> +.BR "#include <sys/stat.h>" " /* For mode constants */" +.BR "#include <fcntl.h>" " /* For O_* constants */" +.P +.BI "int shm_open(const char *" name ", int " oflag ", mode_t " mode ); +.BI "int shm_unlink(const char *" name ); +.fi +.SH DESCRIPTION +.BR shm_open () +creates and opens a new, or opens an existing, POSIX shared memory object. +A POSIX shared memory object is in effect a handle which can +be used by unrelated processes to +.BR mmap (2) +the same region of shared memory. +The +.BR shm_unlink () +function performs the converse operation, +removing an object previously created by +.BR shm_open (). +.P +The operation of +.BR shm_open () +is analogous to that of +.BR open (2). +.I name +specifies the shared memory object to be created or opened. +For portable use, +a shared memory object should be identified by a name of the form +.IR /somename ; +that is, a null-terminated string of up to +.B NAME_MAX +(i.e., 255) characters consisting of an initial slash, +.\" glibc allows the initial slash to be omitted, and makes +.\" multiple initial slashes equivalent to a single slash. +.\" This differs from the implementation of POSIX message queues. +followed by one or more characters, none of which are slashes. +.\" glibc allows subdirectory components in the name, in which +.\" case the subdirectory must exist under /dev/shm, and allow the +.\" required permissions if a user wants to create a shared memory +.\" object in that subdirectory. +.P +.I oflag +is a bit mask created by ORing together exactly one of +.B O_RDONLY +or +.B O_RDWR +and any of the other flags listed here: +.TP +.B O_RDONLY +Open the object for read access. +A shared memory object opened in this way can be +.BR mmap (2)ed +only for read +.RB ( PROT_READ ) +access. +.TP +.B O_RDWR +Open the object for read-write access. +.TP +.B O_CREAT +Create the shared memory object if it does not exist. +The user and group ownership of the object are taken +from the corresponding effective IDs of the calling process, +.\" In truth it is actually the filesystem IDs on Linux, but these +.\" are nearly always the same as the effective IDs. (MTK, Jul 05) +and the object's +permission bits are set according to the low-order 9 bits of +.IR mode , +except that those bits set in the process file mode +creation mask (see +.BR umask (2)) +are cleared for the new object. +A set of macro constants which can be used to define +.I mode +is listed in +.BR open (2). +(Symbolic definitions of these constants can be obtained by including +.IR <sys/stat.h> .) +.IP +A new shared memory object initially has zero length\[em]the size of the +object can be set using +.BR ftruncate (2). +The newly allocated bytes of a shared memory +object are automatically initialized to 0. +.TP +.B O_EXCL +If +.B O_CREAT +was also specified, and a shared memory object with the given +.I name +already exists, return an error. +The check for the existence of the object, and its creation if it +does not exist, are performed atomically. +.TP +.B O_TRUNC +If the shared memory object already exists, truncate it to zero bytes. +.P +Definitions of these flag values can be obtained by including +.IR <fcntl.h> . +.P +On successful completion +.BR shm_open () +returns a new file descriptor referring to the shared memory object. +This file descriptor is guaranteed to be the lowest-numbered file descriptor +not previously opened within the process. +The +.B FD_CLOEXEC +flag (see +.BR fcntl (2)) +is set for the file descriptor. +.P +The file descriptor is normally used in subsequent calls +to +.BR ftruncate (2) +(for a newly created object) and +.BR mmap (2). +After a call to +.BR mmap (2) +the file descriptor may be closed without affecting the memory mapping. +.P +The operation +of +.BR shm_unlink () +is analogous to +.BR unlink (2): +it removes a shared memory object name, and, once all processes +have unmapped the object, deallocates and +destroys the contents of the associated memory region. +After a successful +.BR shm_unlink (), +attempts to +.BR shm_open () +an object with the same +.I name +fail (unless +.B O_CREAT +was specified, in which case a new, distinct object is created). +.SH RETURN VALUE +On success, +.BR shm_open () +returns a file descriptor (a nonnegative integer). +On success, +.BR shm_unlink () +returns 0. +On failure, both functions return \-1 and set +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EACCES +Permission to +.BR shm_unlink () +the shared memory object was denied. +.TP +.B EACCES +Permission was denied to +.BR shm_open () +.I name +in the specified +.IR mode , +or +.B O_TRUNC +was specified and the caller does not have write permission on the object. +.TP +.B EEXIST +Both +.B O_CREAT +and +.B O_EXCL +were specified to +.BR shm_open () +and the shared memory object specified by +.I name +already exists. +.TP +.B EINVAL +The +.I name +argument to +.BR shm_open () +was invalid. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENAMETOOLONG +The length of +.I name +exceeds +.BR PATH_MAX . +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOENT +An attempt was made to +.BR shm_open () +a +.I name +that did not exist, and +.B O_CREAT +was not specified. +.TP +.B ENOENT +An attempt was to made to +.BR shm_unlink () +a +.I name +that does not exist. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR shm_open (), +.BR shm_unlink () +T} Thread safety MT-Safe locale +.TE +.SH VERSIONS +POSIX leaves the behavior of the combination of +.B O_RDONLY +and +.B O_TRUNC +unspecified. +On Linux, this will successfully truncate an existing +shared memory object\[em]this may not be so on other UNIX systems. +.P +The POSIX shared memory object implementation on Linux makes use +of a dedicated +.BR tmpfs (5) +filesystem that is normally mounted under +.IR /dev/shm . +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.2. +POSIX.1-2001. +.P +POSIX.1-2001 says that the group ownership of a newly created shared +memory object is set to either the calling process's effective group ID +or "a system default group ID". +POSIX.1-2008 says that the group ownership +may be set to either the calling process's effective group ID +or, if the object is visible in the filesystem, +the group ID of the parent directory. +.SH EXAMPLES +The programs below employ POSIX shared memory and POSIX unnamed semaphores +to exchange a piece of data. +The "bounce" program (which must be run first) raises the case +of a string that is placed into the shared memory by the "send" program. +Once the data has been modified, the "send" program then prints +the contents of the modified shared memory. +An example execution of the two programs is the following: +.P +.in +4n +.EX +$ \fB./pshm_ucase_bounce /myshm &\fP +[1] 270171 +$ \fB./pshm_ucase_send /myshm hello\fP +HELLO +.EE +.in +.P +Further detail about these programs is provided below. +.\" +.SS Program source: pshm_ucase.h +The following header file is included by both programs below. +Its primary purpose is to define a structure that will be imposed +on the memory object that is shared between the two programs. +.P +.in +4n +.\" SRC BEGIN (pshm_ucase.h) +.EX +#ifndef PSHM_UCASE_H +#define PSHM_UCASE_H +\& +#include <semaphore.h> +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +#define BUF_SIZE 1024 /* Maximum size for exchanged string */ +\& +/* Define a structure that will be imposed on the shared + memory object */ +\& +struct shmbuf { + sem_t sem1; /* POSIX unnamed semaphore */ + sem_t sem2; /* POSIX unnamed semaphore */ + size_t cnt; /* Number of bytes used in \[aq]buf\[aq] */ + char buf[BUF_SIZE]; /* Data being transferred */ +}; +\& +#endif // include guard +.EE +.\" SRC END +.in +.\" +.SS Program source: pshm_ucase_bounce.c +The "bounce" program creates a new shared memory object with the name +given in its command-line argument and sizes the object to +match the size of the +.I shmbuf +structure defined in the header file. +It then maps the object into the process's address space, +and initializes two POSIX semaphores inside the object to 0. +.P +After the "send" program has posted the first of the semaphores, +the "bounce" program upper cases the data that has been placed +in the memory by the "send" program and then posts the second semaphore +to tell the "send" program that it may now access the shared memory. +.P +.in +4n +.\" SRC BEGIN (pshm_ucase_bounce.c) +.EX +/* pshm_ucase_bounce.c +\& + Licensed under GNU General Public License v2 or later. +*/ +#include <ctype.h> +#include <fcntl.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/mman.h> +#include <unistd.h> +\& +#include "pshm_ucase.h" +\& +int +main(int argc, char *argv[]) +{ + int fd; + char *shmpath; + struct shmbuf *shmp; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s /shm\-path\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + shmpath = argv[1]; +\& + /* Create shared memory object and set its size to the size + of our structure. */ +\& + fd = shm_open(shmpath, O_CREAT | O_EXCL | O_RDWR, 0600); + if (fd == \-1) + errExit("shm_open"); +\& + if (ftruncate(fd, sizeof(struct shmbuf)) == \-1) + errExit("ftruncate"); +\& + /* Map the object into the caller\[aq]s address space. */ +\& + shmp = mmap(NULL, sizeof(*shmp), PROT_READ | PROT_WRITE, + MAP_SHARED, fd, 0); + if (shmp == MAP_FAILED) + errExit("mmap"); +\& + /* Initialize semaphores as process\-shared, with value 0. */ +\& + if (sem_init(&shmp\->sem1, 1, 0) == \-1) + errExit("sem_init\-sem1"); + if (sem_init(&shmp\->sem2, 1, 0) == \-1) + errExit("sem_init\-sem2"); +\& + /* Wait for \[aq]sem1\[aq] to be posted by peer before touching + shared memory. */ +\& + if (sem_wait(&shmp\->sem1) == \-1) + errExit("sem_wait"); +\& + /* Convert data in shared memory into upper case. */ +\& + for (size_t j = 0; j < shmp\->cnt; j++) + shmp\->buf[j] = toupper((unsigned char) shmp\->buf[j]); +\& + /* Post \[aq]sem2\[aq] to tell the peer that it can now + access the modified data in shared memory. */ +\& + if (sem_post(&shmp\->sem2) == \-1) + errExit("sem_post"); +\& + /* Unlink the shared memory object. Even if the peer process + is still using the object, this is okay. The object will + be removed only after all open references are closed. */ +\& + shm_unlink(shmpath); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.\" +.SS Program source: pshm_ucase_send.c +The "send" program takes two command-line arguments: +the pathname of a shared memory object previously created by the "bounce" +program and a string that is to be copied into that object. +.P +The program opens the shared memory object +and maps the object into its address space. +It then copies the data specified in its second argument +into the shared memory, +and posts the first semaphore, +which tells the "bounce" program that it can now access that data. +After the "bounce" program posts the second semaphore, +the "send" program prints the contents of the shared memory +on standard output. +.P +.in +4n +.\" SRC BEGIN (pshm_ucase_send.c) +.EX +/* pshm_ucase_send.c +\& + Licensed under GNU General Public License v2 or later. +*/ +#include <fcntl.h> +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <sys/mman.h> +#include <unistd.h> +\& +#include "pshm_ucase.h" +\& +int +main(int argc, char *argv[]) +{ + int fd; + char *shmpath, *string; + size_t len; + struct shmbuf *shmp; +\& + if (argc != 3) { + fprintf(stderr, "Usage: %s /shm\-path string\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + shmpath = argv[1]; + string = argv[2]; + len = strlen(string); +\& + if (len > BUF_SIZE) { + fprintf(stderr, "String is too long\en"); + exit(EXIT_FAILURE); + } +\& + /* Open the existing shared memory object and map it + into the caller\[aq]s address space. */ +\& + fd = shm_open(shmpath, O_RDWR, 0); + if (fd == \-1) + errExit("shm_open"); +\& + shmp = mmap(NULL, sizeof(*shmp), PROT_READ | PROT_WRITE, + MAP_SHARED, fd, 0); + if (shmp == MAP_FAILED) + errExit("mmap"); +\& + /* Copy data into the shared memory object. */ +\& + shmp\->cnt = len; + memcpy(&shmp\->buf, string, len); +\& + /* Tell peer that it can now access shared memory. */ +\& + if (sem_post(&shmp\->sem1) == \-1) + errExit("sem_post"); +\& + /* Wait until peer says that it has finished accessing + the shared memory. */ +\& + if (sem_wait(&shmp\->sem2) == \-1) + errExit("sem_wait"); +\& + /* Write modified data in shared memory to standard output. */ +\& + write(STDOUT_FILENO, &shmp\->buf, len); + write(STDOUT_FILENO, "\en", 1); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.SH SEE ALSO +.BR close (2), +.BR fchmod (2), +.BR fchown (2), +.BR fcntl (2), +.BR fstat (2), +.BR ftruncate (2), +.BR memfd_create (2), +.BR mmap (2), +.BR open (2), +.BR umask (2), +.BR shm_overview (7) |