ABCDEFGHIJKLMNOPQRSTUVWXYZ

shmat

SHMOP(2)                   Linux Programmer's Manual                  SHMOP(2)



NAME
       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 address space  of  the  calling  process.   The  attaching
       address is specified by shmaddr with one of the following criteria:

       If  shmaddr  is NULL, the system chooses a suitable (unused) address at
       which to attach the segment.

       If shmaddr isn't NULL and SHM_RND is asserted  in  shmflg,  the  attach
       occurs at the address equal to shmaddr rounded down to the nearest mul-
       tiple 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 read-
       ing and the process must have read permission for the segment.   Other-
       wise  the  segment  is attached for read and write and the process must
       have read and write permission for the segment.  There is no notion  of
       a write-only shared memory segment.

       The brk value of the calling process is not altered by the attach.  The
       segment will automatically be detached at process exit.  The same  seg-
       ment  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
       shmid_ds structure 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 to be deleted.

       The function shmdt detaches the shared memory segment  located  at  the
       address specified by shmaddr from the address space of the calling pro-
       cess.  The to-be-detached  segment  must  be  currently  attached  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
       shmid_ds structure associated with the shared memory  segment  as  fol-
       lows:

              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 seg-
              ment is marked for deletion, the segment is deleted.

       The occupied region in  the  user  space  of  the  calling  process  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
              from the process.

       exit() Upon  exit()  all  attached  shared memory segments are detached
              from the process.

RETURN VALUE
       On failure both functions return -1 with errno  indicating  the  error.
       On success shmat returns the address of the attached shared memory seg-
       ment, and shmdt returns 0.

ERRORS
       When shmat fails, errno is set to one of the following:

       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.

       The function shmdt can fail only if there is no shared  memory  segment
       attached at shmaddr, in such a case at return errno will be set to EIN-
       VAL.

NOTES
       Using shmat with shmaddr equal to NULL is the preferred,  portable  way
       of  attaching a shared memory segment.  Be aware that the shared memory
       segment attached in this way may be attached at different addresses  in
       different  processes.   Therefore,  any  pointers maintained within the
       shared memory must be made relative (typically to the starting  address
       of the segment), rather than absolute.

       The following system parameter affects a shmat system 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-process 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)



Linux 2.5                         2002-01-05                          SHMOP(2)