shmop - shared memory operations


SYNOPSIS

       # include <sys/types.h>
       # include <sys/shm.h>

       void *shmat ( int shmid, const void *shmaddr, int shmflg )

       int shmdt ( const void *shmaddr)


DESCRIPTION

       The function shmat  attaches  the  shared  memory  segment
       identified  by  shmid  to  the data segment of the calling
       process.  The attaching address is  specified  by  shmaddr
       with one of the following criteria:

              If  shmaddr  is  0,  the  system  tries  to find an
              unmapped region in the range 1 - 1.5G starting from
              the upper value and coming down from there.

              If  shmaddr isn't 0 and SHM_RND is asserted in shm­
              flg, the attach occurs  at  address  equal  to  the
              rounding  down  of shmaddr to a multiple of SHMLBA.
              Otherwise shmaddr must be a page aligned address at
              which the attach occurs.

       If  SHM_RDONLY  is  asserted  in  shmflg,  the  segment is
       attached for reading and the process must have read access
       permissions  to  the  segment.   Otherwise  the segment is
       attached for read and write and the process must have read
       and  write access permissions to the segment.  There is no
       notion of write-only shared memory segment.

       The brk value of the calling process is not altered by the
       attach.   The  segment will automatically detached at pro­
       cess exit.  The same segment may be attached as a read and
       as  a read-write one, and more than once, in the process's
       address space.

       On a successful shmat call the system updates the  members
       of  the structure shmid_ds associated to the shared memory
       segment as follows:

              shm_atime is set to the current time.

              shm_lpid is set to the process-ID  of  the  calling
              process.

              shm_nattch is incremented by one.

       Note  that  the  attach succeeds also if the shared memory
       segment is marked as to be deleted.

       data  segment  the  shared  memory  segment located at the
       address specified by shmaddr.  The detaching shared memory
       segment  must be one among the currently attached ones (to
       the process's address space) with  shmaddr  equal  to  the
       value returned by the its attaching shmat call.

       On  a successful shmdt call the system updates the members
       of the structure shmid_ds associated to the shared  memory
       segment as follows:

              shm_dtime is set to the current time.

              shm_lpid  is  set  to the process-ID of the calling
              process.

              shm_nattch is decremented by one.  If it becomes  0
              and the segment is marked for deletion, the segment
              is deleted.

       The occupied region in the user space of the calling  pro­
       cess is unmapped.


SYSTEM CALLS

       fork() After  a  fork()  the  child  inherits the attached
              shared memory segments.

       exec() After an exec() all attached shared memory segments
              are detached (not destroyed).

       exit() Upon exit() all attached shared memory segments are
              detached (not destroyed).


RETURN VALUE

       On a failure both functions return -1 with errno  indicat­
       ing  the error, otherwise shmat returns the address of the
       attached shared memory segment, and shmdt returns 0.


ERRORS

       When shmat fails, at return errno will be set to one among
       the following values:

       EACCES     The  calling  process has no access permissions
                  for the requested attach type.

       EINVAL     Invalid shmid value, unaligned (i.e., not page-
                  aligned  and  SHM_RND  was  not  specified)  or
                  invalid shmaddr value,  or  failing  attach  at
                  brk.

       ENOMEM     Could not allocate memory for the descriptor or
                  for the page tables.

       memory  segment  attached  at  shmaddr,  in such a case at
       return errno will be set to EINVAL.


NOTES

       On executing a fork(2) system call, the child inherits all
       the attached shared memory segments.

       The shared memory segments attached to a process executing
       an execve(2) system call  will  not  be  attached  to  the
       resulting process.

       The following is a system parameter affecting a shmat sys­
       tem call:

       SHMLBA     Segment low boundary address multiple.  Must be
                  page  aligned.   For the current implementation
                  the SHMBLA value is PAGE_SIZE.

       The implementation has no intrinsic limit to the per  pro­
       cess maximum number of shared memory segments (SHMSEG)


CONFORMING TO

       SVr4,  SVID.  SVr4 documents an additional error condition
       EMFILE.  In SVID-v4 the type of the shmaddr  argument  was
       changed  from  char  * into const void *, and the returned
       type of shmat() from char * into void *.  (Linux libc4 and
       libc5 have the char * prototypes; glibc2 has void *.)


SEE ALSO

       ipc(5), shmctl(2), shmget(2)


Man(1) output converted with man2html