Index for Section 2

Alphabetical listing for S

Bottom of page

shmctl(2)
NAME
  shmctl - Perform shared memory control operations

SYNOPSIS
  #include <sys/shm.h>

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

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

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

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

  Refer to the standards(5) reference page for more information about
  industry 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
  operations 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 associated
      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.

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

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), shm_open(3), shm_unlink(3)

  Data structures: shmid_ds(4)

  Standards: standards(5)

Index for Section 2

Alphabetical listing for S

Top of page