*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Linux man pages -> shmctl (2)              



NAME    [Toc]    [Back]

       shmctl - shared memory control

SYNOPSIS    [Toc]    [Back]

       #include <sys/ipc.h>

       #include <sys/shm.h>

       int shmctl(int shmid, int cmd, struct shmid_ds *buf);

DESCRIPTION    [Toc]    [Back]

       shmctl() allows the user to receive information on a shared memory segment,
 set the owner, group, and permissions of a shared memory segment,
       or  destroy  a segment. The information about the segment identified by
       shmid is returned in a shmid_ds structure:

	    struct shmid_ds {
		 struct    ipc_perm shm_perm;  /* operation perms */
		 int  shm_segsz;	  /* size of segment (bytes) */
		 time_t    shm_atime;	       /* last attach time */
		 time_t    shm_dtime;	       /* last detach time */
		 time_t    shm_ctime;	       /* last change time */
		 unsigned short shm_cpid; /* pid of creator */
		 unsigned short shm_lpid; /* pid of last operator */
		 short	   shm_nattch;	       /* no. of current attaches */
		 /* the following are private */
		 unsigned short   shm_npages;  /* size of segment (pages) */
		 unsigned long	 *shm_pages;
		 struct shm_desc *attaches;    /* descriptors for attaches */

       The fields in the member shm_perm can be set:

	    struct ipc_perm
	      key_t  key;
	      ushort uid;   /* owner euid and egid */
	      ushort gid;
	      ushort cuid;  /* creator euid and egid */
	      ushort cgid;
	      ushort mode;  /* lower 9 bits of access modes */
	      ushort seq;   /* sequence number */

       The following cmds are available:

       IPC_STAT    is used to copy the information  about  the	shared	memory
		   segment into the buffer buf. The user must have read access
		   to the shared memory segment.

       IPC_SET	   is used to apply the changes the user has made to the  uid,
		   gid, or mode members of the shm_perms field.  Only the lowest
 9 bits of mode are used.  The shm_ctime member is  also
		   updated.   The  user  must  be  the	owner, creator, or the

       IPC_RMID    is used to mark the segment as destroyed. It will  actually
		   be  destroyed  after  the  last  detach.   (I.e.,  when the
		   shm_nattch member of the associated structure  shmid_ds  is
		   zero.)   The user must be the owner, creator, or the superuser.

       The user must ensure that a segment is eventually destroyed;  otherwise
       its pages that were faulted in will remain in memory or swap.

       In  addition,  the super-user can prevent or allow swapping of a shared
       memory segment with the following cmds: (Linux only)

       SHM_LOCK    prevents swapping of a shared memory segment. The user must
		   fault  in  any  pages that are required to be present after
		   locking is enabled.

       SHM_UNLOCK  allows the shared memory segment to be swapped out.

       The IPC_INFO, SHM_STAT and SHM_INFO  control  calls  are  used  by  the
       ipcs(8)	program to provide information on allocated resources.	In the
       future, these man be modified as needed or moved to a proc file	system

SYSTEM CALLS    [Toc]    [Back]

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

       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    [Toc]    [Back]

       0 is returned on success, -1 on error.

ERRORS    [Toc]    [Back]

       On error, errno will be set to one of the following:

       EACCES	   is returned if IPC_STAT  is	requested  and	shm_perm.modes
		   does not allow read access for msqid.

       EFAULT	   The	argument  cmd  has  value  IPC_SET or IPC_STAT but the
		   address pointed to by buf isn't accessible.

       EINVAL	   is returned if shmid is not a valid identifier, or  cmd  is
		   not a valid command.

       EIDRM	   is returned if shmid points to a removed identifier.

       EPERM	   is  returned  if  IPC_SET or IPC_RMID is attempted, and the
		   user is not the creator, the owner, or the super-user,  and
		   the user does not have permission granted to their group or
		   to the world.

NOTE    [Toc]    [Back]

       Various fields in a struct shmid_ds were shorts	under  Linux  2.2  and
       have  become longs under Linux 2.4. To take advantage of this, a recompilation
 under glibc-2.1.91 or later should suffice.  (The kernel  distinguishes
 old and new calls by a IPC_64 flag in cmd.)

CONFORMING TO    [Toc]    [Back]

       SVr4, SVID.  SVr4 documents additional error conditions EINVAL, ENOENT,
       ENOSPC, ENOMEM, EEXIST.	Neither SVr4 nor SVID documents an EIDRM error

SEE ALSO    [Toc]    [Back]

       shmget(2), shmop(2)

Linux 2.4.1			  2001-02-18			     SHMCTL(2)
[ Back ]
 Similar pages
Name OS Title
shmctl IRIX shared memory control operations
shmctl HP-UX shared memory control operations
shmctl NetBSD shared memory control operations
shmctl OpenBSD shared memory control operations
shmctl Tru64 Perform shared memory control operations
shm_open FreeBSD open or create a shared memory object shm_unlink -- remove a shared memory object
shmop HP-UX shared memory operations
shmx Tru64 shared memory exerciser
shmat HP-UX shared memory operations
shmat OpenBSD map/unmap shared memory
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service