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



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 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  per-
       mission   for  the  segment.   Otherwise  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 segment may be attached as a  read
       and  as  a read-write one, and more than once, in the pro-
       cess'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 process.  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 mem-
       ory 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 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 segment, 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 EINVAL.

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 pro-
       cesses.  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-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(c), shmctl(l), shmget(t)



Linux 2.5                   2002-01-05                   SHMOP(P)