shmat(2)							      shmat(2)

NAME
       shmat - Attach a shared memory region

SYNOPSIS
       #include <sys/shm.h>

       void *shmat(
	       int shmid,
	       const void *shmaddr,
	       int shmflgs );

       If  programs  are  being	 developed for multiple platforms, application
       developers may want to specify #include	statements  for	 <sys/types.h>
       and <sys/ipc.h> before the one for <sys/shm.h>. The additional #include
       statements are not required on Tru64 UNIX systems  or  by  ISO  or  XSH
       standards,  but	may be required on other vendors' systems that conform
       to these standards.

STANDARDS
       Interfaces documented on this reference page conform to industry	 stan‐
       dards as follows:

       shmat(): XSH4.0, XSH4.2, XSH5.0

       Refer  to  the  standards(5)  reference page for more information about
       industry standards and associated tags.

PARAMETERS
       Specifies the ID for the shared memory  region.	The  ID	 is  typically
       returned	 by  a	previous  shmget()  function.	Specifies  the virtual
       address at which the process wants to attach the shared memory  region.
       The  process  can  also	specify	 0 (zero) to have the kernel select an
       appropriate address.  Specifies the  attach  options.  Possible	values
       are:  If	 the addr parameter is not 0 (zero), the kernel rounds off the
       address, if necessary.  If the calling process has read permission, the
       kernel attaches the region for reading only.

DESCRIPTION
       The  shmat()  function  attaches the shared memory region identified by
       the shmid parameter  to	the  virtual  address  space  of  the  calling
       process.	 For  the  addr	 parameter,  the process can specify either an
       explicit address or 0 (zero), to have the kernel select the address. If
       an  explicit  address  is used, the process can set the SHM_RND flag to
       have the kernel round off the address, if necessary.

       Access to the shared memory region is determined by the operation  per‐
       missions	 in  the  shm_perm.mode member in the region's shmid_ds struc‐
       ture. The low-order bits in shm_perm.mode are interpreted  as  follows:
       Read  by user Write by user Read by group Write by group Read by others
       Write by others

       The calling process is  granted	read  and  write  permissions  on  the
       attached region if at least one of the following is true: The effective
       user ID of the process is superuser.  The  effective  user  ID  of  the
       process	is  equal  to  shm_perm.cuid  or  shm_perm.uid and bit 0600 in
       shm_perm.mode is set.  The effective group ID of the process  is	 equal
       to  shm_perm.cgid or shm_perm.gid and bit 0060 in shm_perm.mode is set.
       Bit 0006 in shm_perm.mode is set.

       If the process has read permission, it can attach the  region  as  read
       only by setting the SHM_RDONLY option.

NOTES
       The librt library contains alternative interfaces for interprocess com‐
       munication. The names of these routines adhere to the format shm_*  and
       their reference pages are listed in SEE ALSO.

RETURN VALUES
       Upon successful completion, shmat() increments the value of shm_nattach
       in the data structure associated with  the  shared  memory  ID  of  the
       attached shared memory segment and returns the segment's start address.
       If the  shmat()	function  fails,  the  shared  memory  region  is  not
       attached,  a  value of -1 is returned, and errno is set to indicate the
       error.

ERRORS
       The shmat() function sets errno to the specified values for the follow‐
       ing conditions: The calling process does not have the appropriate priv‐
       ilege.  The shmid parameter does not  specify  a	 valid	shared	memory
       region  ID; the addr parameter is not 0 (zero) and not a valid address;
       or the addr parameter is not 0 (zero) and  not  a  valid	 address,  and
       SHM_RND is not set.

	      [Tru64  UNIX]  The  shmid	 refers	 to  a segmented shared memory
	      region and the addr parameter is not aligned at  SSM_SIZE	 (that
	      is, (addr % SSM_SIZE) != 0).  An attempt to attach a shared mem‐
	      ory region exceeded  the	maximum	 number	 of  attached  regions
	      allowed  for  any	 one process.  There was not enough data space
	      available to attach the shared memory region.

	      [Tru64 UNIX]  The shmid refers  to  a  segmented	shared	memory
	      region  whose  size  is not a multiple of SSM_SIZE and where not
	      enough data space is available for the rounded-up size.

SEE ALSO
       Commands: sysconfig(8)

       Functions: exec(2), exit(2), fork(2), shmctl(2),	 shmdt(2),  shmget(2),
       shm_open(3), shm_unlink(3)

       Data structures: shmid_ds(4)

       Standards: standards(5)

								      shmat(2)

Vote for polarhome