shm_open()

open a shared memory object

Synopsis:

#include <fcntl.h>
#include <sys/mman.h>
int shm_open( const char *name,
              int oflag,
              mode_t mode );

The shm_open() function returns a file descriptor that is associated with the shared "memory object" specified by name. This file descriptor is used by other functions (such as mmap() and mprotect()) to refer to the shared memory object. The FD_CLOEXEC file descriptor flag is set for this file descriptor.

The state of the shared memory object, including all data associated with it, persists until the shared memory object is unlinked and all other references are gone.

The value of oflag is constructed by the bitwise ORing of the following flags. At least the following flag bits are defined in <fcntl.h>:

O_RDONLY: Open for read access only.
O_RDWR: Open for read and write access.
O_CREAT: If the shared memory object exists, this flag has no effect, except as noted under O_EXCL below. Otherwise the shared memory object is created, and its permissions are set in accordance with the value of mode and the file mode creation mask of the process.
O_EXCL: If O_EXCL and O_CREAT are set, then shm_open() will fail if the shared memory segment exists.
The check for the existence of the shared memory object, and the creation of the object if it doesn't exist, are atomic with respect to other processes executing shm_open(), naming the same shared memory object with O_EXCL and O_CREAT set.
O_TRUNC: If the shared memory object exists, and it is successfully opened O_RDWR, the object is truncated to zero length and the mode and owner are unchanged.

The permission bits for the memory object will be set to the value of mode, except those bits set in the process's file creation mask (see the umask() function and <sys/stat.h>).

Returns:

On success, the shm_open() function returns a nonnegative integer, which is the lowest numbered unused file descriptor. Otherwise, -1 is returned, and errno is set.

Errors:

EACCES: Permission to create the shared memory object is denied.
The shared memory object exists and the permissions specified by oflag are denied, or O_TRUNC is specified and write permission is denied.
EEXIST: O_CREAT and O_EXCL are set, and the named shared memory object already exists.
EINTR: The shm_open() call was interrupted by a signal.
EMFILE: Too many file descriptors are currently in use by this process.
ENAMETOOLONG: The length of the name argument exceeds NAME_MAX.
ENFILE: Too many shared memory objects are currently open in the system.
ENOENT: O_CREAT isn't set, and the named shared memory object doesn't exist, or O_CREAT is set and either the name prefix doesn't exist or the name argument points to an empty string.
ENOSPC: There's insufficient space for the creation of the new shared memory object.
ENOSYS: The shm_open() function isn't supported by this implementation.

Examples:

/*
 * EXAMPLE 1:
 */
#include <stdio.h>
#include <string.h>
#include <fcntl.h>
#include <errno.h>
#include <stdlib.h>
#include <sys/mman.h>

main()
{
  int          fd, i;
  char         *addr, c;

  /* Open physical memory */
  fd = shm_open("Physical", O_RDWR, 0777);
  if (fd == -1) {
    fprintf(stderr, "Open failed:%s\n", strerror(errno));
    exit(1);
  }

  /* Map BIOS ROM */
  addr = mmap(0, PAGESIZE, PROT_READ | PROT_WRITE,
               MAP_SHARED, fd, 0xf0000);
  if (addr == (void *) -1) {
    fprintf(stderr, "mmap failed : %s\n",
     strerror(errno));
    exit(1);
  }
  printf("Map addr is %6.6X\n", addr);

  for (i = 0; i < 3 * 80; ++i) {
     c = *addr++;
     if (c >= ' ' && c <= 0x7f)
       putchar(c);
     else
       putchar('.');
  }

  exit(0);
}

/*
 * EXAMPLE 2:
 */
#include <stdio.h>
#include <string.h>
#include <fcntl.h>
#include <errno.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/mman.h>

main(int argc, char *argv[])
{
  int          fd;
  char         *addr;

  /*
   * In case the unlink code is
   * not executed at the end
   */
  if (argc != 1) {
     shm_unlink("bolts");
     exit(0);
  }

  /* Create a new memory object */
  fd = shm_open("bolts", O_RDWR | O_CREAT, 0777);
  if (fd == -1) {
     fprintf(stderr, "Open failed:%s\n",
       strerror(errno));
     exit(1);
  }

  /* Set memory objects size */
  if (ltrunc(fd, PAGESIZE, SEEK_SET) == -1) {
    fprintf(stderr, "ltrunc : %s\n", strerror(errno));
    exit(1);
  }

  /* Map memory object */
  addr = mmap(0, PAGESIZE, PROT_READ | PROT_WRITE,
               MAP_SHARED, fd, 0);
  if (addr == (void *) -1) {
     fprintf(stderr, "mmap failed : %s\n",
     strerror(errno));
     exit(1);
  }
  printf("Map addr is %6.6X\n", addr);

  /* Write to shared memory */
  *addr = 1;

  /*
   * The memory object remains in
   * the system after the close
   */
  close(fd);

  /*
   * To remove a memory object
   * you must unlink it like a file.
   */
  /*
   * This may be done by another process.
   */
  shm_unlink("bolts");

  exit(0);
}

/*
 * EXAMPLE 3:
 */
#include <stdio.h>
#include <string.h>
#include <fcntl.h>
#include <errno.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/mman.h>
#include <sys/kernel.h>

main(int argc, char *argv[])
{
int        fd;
char       *addr;

  /*
   * In case the unlink code isn't executed at the end
   */
  if (argc != 1) {
     shm_unlink("bolts");
     exit(0);
  }

  /* Create a new memory object */
  fd = shm_open("bolts", O_RDWR | O_CREAT, 0777);
  if (fd == -1) {
     fprintf(stderr, "Open failed : %s\n",
       strerror(errno));
     exit(1);
  }

  /* Set memory objects size */
  if (ltrunc(fd, PAGESIZE, SEEK_SET) == -1) {
     fprintf(stderr, "ltrunc : %s\n", strerror(errno));
     exit(1);
  }

  /* Map memory object */
  addr = mmap(0, PAGESIZE, PROT_READ | PROT_WRITE,
               MAP_SHARED, fd, 0);
  if (addr == (void *) -1) {
    fprintf(stderr, "mmap failed:%s\n",strerror(errno));
    exit(1);
  }

  printf("Map addr is %6.6X\n", addr);
  printf("Hit break to stop.\n");
  sleep(3);    /* So you can read above message */

  /*
   * We unlink so object goes away on last close.
   */
  shm_unlink("bolts");

  *addr = '0';
  if (fork())
     for (;;)
       if (*addr == '0')
         putc(*addr = '1', stderr);
       else
         Yield();
  else
    for (;;)
       if (*addr == '1')
         putc(*addr = '0', stderr);
       else
         Yield();
}

Classification:

POSIX 1003.4

Safety:
Interrupt handler	No
Signal handler	Yes, but modifies errno
Thread	Yes