shmctl64_time64()--Perform Shared Memory Control Operations (64-Bit time64_t Enabled)

Syntax

 #include <sys/shm.h>

 int shmctl64_time64(int shmid, int cmd, struct shmid_ds64_time64 *buf);

  Service Program Name: QP0ZUSHR

  Default Public Authority: *USE

  Threadsafe: Yes

The shmctl64_time64() function allows the caller to control the shared memory segment specified by the shmid parameter.

The shmctl64_time64() function is enabled to support 64-bit time64_t timestamp.

For additional information about authorities required, error conditions, and examples, see shmctl64()--Perform Shared Memory Control Operations(64-Bit Enabled).

A shared memory segment is controlled by setting the cmd parameter to one of the following values:

IPC_RMID (0x00000000)

Remove the shared memory segment identifier shmid from the system and destroy the shared memory segment.

The IPC_RMID command can be run only by a thread with appropriate privileges or one that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the shared memory segment. The structure pointed to by *buf is ignored and can be NULL.

IPC_SET (0x00000001)

Set the user ID of the owner, the group ID of the owner, and the permissions for the shared memory segment to the values in the shm_perm.uid, shm_perm.gid, and shm_perm.mode members of the shmid_ds64_time64 data structure pointed to by *buf.

The IPC_SET command can be run only by a thread with appropriate privileges or one that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the shared memory segment.

IPC_STAT (0x00000002)

Store the current value of each member of the shmid_ds64_time64 data structure into the structure pointed to by *buf. The IPC_STAT command requires read permission to the shared memory segment.

SHM_SIZE (0x00000006)

Set the size of the shared memory segment using the shm_segsz member of the shmid_ds64_time64 data structure pointed to by *buf. This value may be larger or smaller than the current size. This command is valid for nonteraspace shared memory segments and for teraspace shared memory segments created using the SHM_RESIZE_NP option on the shmget() or shmget64() function. The maximum size to which a nonteraspace shared memory segment may be expanded is 16 773 120 bytes (16 MB minus 4096 bytes). The maximum size of a resizable teraspace shared memory segment is 268 435 456 bytes (256 MB).

The SHM_SIZE command can be run only by a thread with appropriate privileges or a thread that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the shared memory segment.

If a shared memory segment is resized to a smaller size, other threads using the memory that is being removed from the shared memory segment may experience memory exceptions when accessing that memory.

SHM_PAGESIZE (0x000000C8)

Set the page size of the storage backing the teraspace shared memory segment using the shm_pagesize field of the shmid_ds64 data structure pointed to by *buf. The shm_pagesize field is interpreted as a page size in bytes. This command is only valid for teraspace shared memory segments. Changing the page size of a nonteraspace shared memory segment will fail with the [ENOTSUP] error.

This command must be called after the teraspace shared memory segment has been created but before any process has attached to the teraspace shared memory segment. Setting the page size of a teraspace shared memory segment after it has been attached to a process will fail with the [EBUSY] error.

Valid values for the shm_pagesize field are:

SHM_4KB_PAGESIZE (0x0000000000001000): Use a 4KB (4096 bytes) page size. This is the default page size for teraspace shared memory segments when they are created.
SHM_64KB_PAGESIZE (0x0000000000010000): Use a 64KB (65536 bytes) page size. This page size is only supported on systems with IBM^? POWER5+? or later hardware.

Setting the page size to a value that is not valid or not supported will fail with the [EINVAL] error.

The SHM_PAGESIZE command can be run only by a thread with appropriate privileges or a thread that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the teraspace shared memory segment.

Parameters

shmid: (Input) Shared memory identifier, a positive integer. It is returned by the shmget() or shmget64() function and is used to identify the shared memory segment on which to perform the control operation.
cmd: (Input) Command, the control operation to perform on the shared memory segment. Valid values are listed above.
buf: (I/O) Buffer, the pointer to the shmid_ds64_time64 structure to be used to get or set shared memory information.
The members of the shmid_ds64_time64 structure are as follows:

struct ipc_perm shm_perm

The members of the ipc_perm structure are as follows:

uid_t uid

The user ID of the owner of the segment.

gid_t gid

The group ID of the owner of the segment.

uid_t cuid

The user ID of the creator of the segment.

gid_t cgid

The group ID of the creator of the segment.

mode_t mode

The permissions for the segment.

pid_t shm_lpid

The process ID of the last job to attach to or detach from the segment using shmat() or shmdt().

pid_t shm_cpid

The process ID of the job that created the segment using shmget() or shmget64().

shmatt_t shm_nattch

The number of jobs attached to the segment.

size64_t shm_segsz

The size of the segment in bytes.

time64_t shm_atime

The time the last job attached to the segment using shmat().

time64_t shm_dtime

The time the last job detached from the segment using shmdt().

time64_t shm_ctime

The time the last job changed the segment using shmctl() ,shmctl64() or shmctl64_time64().

psize_t shm_pagesize

The page size of the storage backing the segment.

char shm_reserved4[24]

Reserved. This field must be set to binary zero on input.

Usage Notes

The prototype for the 64-bit timestamp API could be invoked directly in C_based languages. If you want to map the shmctl64() API to shmctl64_time64() API, you must compile the source with _64_BIT_TIME defined.
The API will not return dates beyond June 8th, 2062.
All of the usage notes for shmctl64_time64() also apply to shmctl() and to shmctl64(). See usage Notes in the shmctl64() API.

API introduced: V7R2

[ Back to top | UNIX-Type APIs | APIs by category ]