unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



shmctl(2)							    shmctl(2)



NAME

  shmctl - Performs shared memory control operations

SYNOPSIS

  #include <&lt;sys/shm.h>&gt;

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

  Application developers might want to specify #include	statements for
  <&lt;sys/types.h>&gt;	and <&lt;sys/ipc.h>&gt;	before the one for <&lt;sys/shm.h>&gt; if programs
  are being developed for multiple platforms. The additional #include state-
  ments	are not	required on Tru64 UNIX systems or by ISO or X/Open standards,
  but might be required	on other vendors' systems that conform to these	stan-
  dards.

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  shmctl(): XSH4.2

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

PARAMETERS

  shmid	    Specifies the ID of	the shared memory region.

  cmd	    Specifies the type of command.  The	possible commands are:
	    IPC_STAT, IPC_SET, IPC_RMID, SHM_LOCK, and SHM_UNLOCK.

  buf	    Specifies the address of a shmid_ds	structure.

DESCRIPTION

  The shmctl() function	provides a variety of shared memory control opera-
  tions	as specified by	the cmd	parameter.

  The cmd values and their operations are as follows:

  IPC_STAT  Queries the	shared memory region ID	by copying the contents	of
	    its	associated shmid_ds data structure into	the buf	structure.

  IPC_SET   Sets the shared memory region ID by	copying	values found in	the
	    buf	structure into corresponding fields in the shmid_ds structure
	    associated with the	shared memory region ID.  The fields are set
	    as follows:

	      +	 The shm_perm.uid field	is set to the owner's user ID.

	      +	 The shm_perm.gid field	is set to the owner's group ID.

	      +	 The shm_perm.mode field is set	to the access modes for	the
		 shared	memory region.	Only the low-order nine	bits are set.

	      +	 The shm_ctime field is	set to the time	of the last IPC_SET
		 operation.

  IPC_RMID  Removes the	shared memory region ID	and deallocates	its associ-
	    ated shmid_ds structure.

  SHM_LOCK  [Tru64 UNIX]  Locks	the shared memory segment specified by shmid
	    in memory.

  SHM_UNLOCK
	    [Tru64 UNIX]  Unlocks the shared memory segment specified by
	    shmid in memory.

  The shmid_ds structure is used only with the IPC_STAT	and IPC_SET commands.
  In either case, the calling process must have	allocated the structure
  before making	the call.

  [Tru64 UNIX]	The SHM_LOCK and SHM_UNLOCK commands can be used to lock
  (wire) down a	shared segment in memory to prevent it from being paged	out.

NOTES

  [Tru64 UNIX]	When using the SHM_LOCK	command, make sure that	the system
  has enough physical memory available for the shared segment to be wired
  without exceeding the	system-wide limit or otherwise severely	impacting
  system performance.

  [Tru64 UNIX]	The SHM_LOCK operation wires all the pages in a	global shared
  segment and prevents the pageout daemon from reclaiming any of the pages.
  This can potentially lead to thrashing.

RESTRICTIONS

  The following	restrictions apply to the shared memory	commands:

    +  For the IPC_SET and IPC_RMID commands, the effective user ID of the
       calling process must be equal to	that of	superuser or equal to the
       value of	shm_perm.cuid or shm_perm.uid in the associated	shmid_ds
       structure.

    +  [Tru64 UNIX]  For the SHM_LOCK and SHM_UNLOCK commands, the effective
       user ID of the calling process must be equal to that of superuser.

RETURN VALUES

  Upon successful completion, a	value of 0 (zero) is returned. If the
  shmctl() function fails, a value of -1 is returned and errno is set to
  indicate the error.

ERRORS

  The shmctl() function	sets errno to the specified values for the following
  conditions:

  [EACCES]  The	cmd parameter is IPC_STAT, but the calling process does	not
	    have read permission.

  [EAGAIN]  [Tru64 UNIX]  The cmd parameter is SHM_LOCK, and the system-wide
	    wire limit has been	exceeded.

  [EFAULT]  [Tru64 UNIX]  The cmd parameter is IPC_STAT	or IPC_SET.  An	error
	    occurred in	accessing the buf structure.

  [EINVAL]  The	shmid parameter	does not specify a valid shared	memory region
	    ID,	or cmd is not a	valid command.

	    [Tru64 UNIX]  The cmd parameter is SHM_UNLOCK, and the segment
	    was	not locked.

  [EPERM]   The	cmd parameter is equal to either IPC_RMID or IPC_SET, and the
	    calling process does not have appropriate privilege.

SEE ALSO

  Functions: shmat(2), shmdt(2), shmget(2)

  Data structures: shmid_ds(4)

  Standards: standards(5)