References for shmat services

This section includes the following subroutine references:

The ftok() subroutine

Generates a standard interprocess communication key.

Library

Standard C library (libc.a)

Syntax
#include <sys/types.h>
#include <sys/ipc.h>

key_t ftok(Path, ID)
char *Path;
int ID;

Description

The ftok() subroutine returns a key, based on the Path and ID parameters, to be used to obtain interprocess communication identifiers. The ftok() subroutine returns the same key for linked files if called with the same ID parameter. Different keys are returned for the same file if different ID parameters are used.

All interprocess communication facilities require you to supply a key to the msgget(), semget(), and shmget() subroutines in order to obtain interprocess communication identifiers. The ftok() subroutine provides one method for creating keys, but other methods are possible. For example, you can use the project ID as the most significant byte of the key, and use the remaining portion as a sequence number.

Attention

  • If the Path parameter of the ftok() subroutine names a file that has been removed while keys still refer to it, the ftok() subroutine returns an error. If that file is then re-created, the ftok() subroutine will probably return a key different from the original one.

  • Each installation should define standards for forming keys. If standards are not adhered to, unrelated processes may interfere with each other’s operation.

  • The ftok() subroutine does not guarantee unique key generation. However, the occurrence of key duplication is very rare and mostly for across file systems.


Parameters
PathSpecifies the path name of an existing file that is accessible to the process.
IDSpecifies a character that uniquely identifies a project.

Return values

When successful, the ftok() subroutine returns a key that can be passed to the msgget(), semget(), or shmget() subroutines.

Error codes

The ftok() subroutine returns the value (key_t)-1 if one or more of the following are true:

  • The file named by the Path parameter does not exist.

  • The file named by the Path parameter is not accessible to the process.

  • The ID parameter has a value of 0.

The shmat() routine

The shmat() subroutine attaches a shared memory segment or a mapped file to the current process’s address space.

Library

Standard C library (libc.a)

Syntax
#include <sys/shm.h>
void *shmat(shm_mem_id, shm_mem_addr, shm_mem_flag)
int         shm_mem_id, shm_mem_flag;
const void *shared_mem_addr;

Description

The shmat() subroutine attaches the shared memory segment or mapped file specified by the SharedMemoryID parameter (returned by the shmget() subroutine), or file descriptor specified by the SharedMemoryID parameter (returned by the openx() subroutine) to the address space of the calling process.

The following limits apply to shared memory:

  • The maximum shared-memory segment size is:

    - 256 MB before AIX Version 4.3.1

    - 2 GB for AIX Version 4.3.1 through AIX 5L Version 5.1

    - 64 GB for 64-bit applications for AIX 5L Version 5.1 and later

  • The minimum shared-memory segment size is 1 byte.

  • The maximum number of shared memory IDs is 4096 for operating system releases before AIX Version 4.3.2 and 131072 for AIX Version 4.3.2 and following.

Note

The following applies to AIX Version 4.2.1 and later releases for 32-bit processes only.


An extended shmat capability is available. If an environment variable EXTSHM=ON is defined, then processes executing in that environment will be able to create and attach more than eleven shared memory segments.

The segments can be of size, from 1 byte to 2 GB, although for segments larger than 256 MB in size the environment variable EXTSHM=ON is ignored. The process can attach these segments into the address space for the size of the segment. Another segment could be attached at the end of the first one in the same 256 MB segment region. The address at which a process can attach is at page boundaries (a multiple of SHMLBA_EXTSHM bytes). For segments larger than 256 MB in size, the address at which a process can attach is at 256 MB boundaries, which is a multiple of SHMLBA bytes.

The segments can be of size from 1 byte to 256 MB. The process can attach these segments into the address space for the size of the segment. Another segment could be attached at the end of the first one in the same 256 MB segment region. The address at which a process can attach will be at page boundaries (a multiple of SHMLBA_EXTSHM bytes).

The maximum address space available for shared memory with or without the environment variable and for memory mapping is 2.75 GB. An additional segment register “0xE” is available so that the address space is from 0x30000000 to 0xE0000000. However, a 256 MB region starting from 0xD0000000 will be used by the shared libraries and is therefore unavailable for shared memory regions or mmapped regions.

There are some restrictions on the use of the extended shmat feature. These shared memory regions cannot be used as I/O buffers where the unpinning of the buffer occurs in an interrupt handler. The restrictions on the use are the same as that of mmap buffers.

The smaller region sizes are not supported for mapping files. Regardless of whether EXTSHM=ON or not, mapping a file will consume at least 256 MB of address space.

SHM_SIZE shmctl() is not supported for segments created with EXTSHM=ON.

A segment created with EXTSHM=ON can be attached by a process without EXTSHM=ON. This will consume a 256 MB area of the address space irrespective of the size of the shared memory region.

A segment created without EXTSHM=ON can be attached by a process with EXTSHM=ON. This will consume a 256 MB area of the address space irrespective of the size of the shared memory region.

The environment variable provides the option of executing an application either with the additional functionality of attaching more than 11 segments when EXTSHM=ON, or the higher-performance access to 11 or fewer segments when the environment variable is not set.

Parameter
shm_mem_idSpecifies an identifier for the shared memory segment.
shm_mem_addrIdentifies the segment or file attached at the address specified by the shm_mem_addr parameter, as follows:

If the shm_mem_addr parameter is not equal to 0, and the SHM_RND flag is set in the shm_mem_flag parameter, the segment or file is attached at the next lower segment boundary. This address is given by (shm_mem_addr - (shm_mem_addr modulo SHMLBA_EXTSHM, if environment variable EXTSHM=ON or SHMLBA if not). SHMLBA specifies the low boundary address multiple of a segment.

If the shm_mem_addr parameter is not equal to 0 and the SHM_RND flag is not set in the shm_mem_flag parameter, the segment or file is attached at the address given by the shm_mem_addr parameter. If this address does not point to a SHMLBA_EXTSHM boundary if the environment variable EXTSHM=ON or SHMLBA boundary if not, the shmat() subroutine returns the value -1 and sets the errno global variable to the EINVAL error code. SHMLBA specifies the low boundary address multiple of a segment.
shm_mem_flagSpecify several options. Its value is either 0 or is constructed by logically ORing one or more of the values in Table C-1.

Table C-1. Values for the third parameter of shmat()
ValueDescription
SHM_MAPMaps a file onto the address space instead of a shared memory segment. The shm_mem_id parameter must specify an open file descriptor in this case.
SHM_RDONLYSpecifies read-only mode instead of the default read-write mode.
SHM_RNDRounds the address given by the shm_mem_addr parameter to the next lower segment boundary, if necessary.

The shmat() subroutine makes a shared memory segment addressable by the current process. The segment is attached for reading if the SHM_RDONLY flag is set and the current process has read permission. If the SHM_RDONLY flag is not set and the current process has both read and write permission, it is attached for reading and writing.

If the SHM_MAP flag is set, file mapping takes place. In this case, the shmat subroutine maps the file open on the file descriptor specified by the SharedMemoryID onto a segment. The file must be a regular file. The segment is then mapped into the address space of the process. A file of any size can be mapped if there is enough space in the user address space.

When file mapping is requested, the SharedMemoryFlag parameter specifies how the file should be mapped. If the SHM_RDONLY flag is set, the file is mapped read-only. To map read-write, the file must have been opened for writing.

All processes that map the same file read-only or read-write map to the same segment. This segment remains mapped until the last process mapping the file closes it.

A mapped file opened with the O_DEFER update has a deferred update. That is, changes to the shared segment do not affect the contents of the file resident in the file system until an fsync subroutine is issued to the file descriptor for which the mapping was requested. Setting the SHM_COPY flag changes the file to the deferred state. The file remains in this state until all processes close it. The SHM_COPY flag is provided only for compatibility with Version 2 of the operating system. New programs should use the O_DEFER open flag.

A file descriptor can be used to map the corresponding file only once. To map a file several times requires multiple file descriptors.

When a file is mapped onto a segment, the file is referenced by accessing the segment. The memory paging system automatically takes care of the physical I/O. References beyond the end of the file cause the file to be extended in page-sized increments. The file cannot be extended beyond the next segment boundary.

Return values

When successful, the segment start address of the attached shared memory segment or mapped file is returned. Otherwise, the shared memory segment is not attached, the errno global variable is set to indicate the error, and a value of -1 is returned.

Error codes

The shmat() subroutine is unsuccessful and the shared memory segment or mapped file is not attached if one or more of the following are true:

EACCESThe calling process is denied permission for the specified operation.
EAGAINThe file to be mapped has enforced locking enabled, and the file is currently locked.
EBADFA file descriptor to map does not refer to an open regular file.
EEXISTThe file to be mapped has already been mapped.
EINVALThe SHM_RDONLY and SHM_COPY flags are both set.
EINVALThe shm_mem_id parameter is not a valid shared memory identifier.
EINVALThe shm_mem_addr parameter is not equal to 0, and the value of (shm_mem_addr - (shm_mem_addr - modulo SHMLBA_EXTSHM if the environment variable EXTSHM=ON or SHMLBA if not) points outside the address space of the process.
EINVALThe shm_mem_addr parameter is not equal to 0, the SHM_RND flag is not set in the SharedMemoryFlag parameter, and the shm_mem_addr parameter points to a location outside of the address space of the process.
EMFILEThe number of shared memory segments attached to the calling process exceeds the system-imposed limit.
ENOMEMThe available data space in memory is not large enough to hold the shared memory segment. ENOMEM is always returned if a 32-bit process tries to attach a shared memory segment larger than 2 GB.
ENOMEMThe available data space in memory is not large enough to hold the mapped file data structure.
ENOMEMThe requested address and length crosses a segment boundary. This is not supported when the environment variable EXTSHM=ON.

The shmctl() subroutine

Controls shared memory operations.

Library

Standard C library (libc.a)

Syntax
#include <sys/shm.h>
int shmctl (SharedMemoryID, Command, Buffer)
int SharedMemoryID, Command;
struct shmid_ds * Buffer;

Description

The shmctl() subroutine performs a variety of shared-memory control operations as specified by the Command parameter.

The following limits apply to shared memory:

  • The maximum shared-memory segment size is:

    - 256 MB before AIX Version 4.3.1

    - 2 GB for AIX Version 4.3.1 through AIX 5L Version 5.1

    - 64 GB for 64-bit applications for AIX 5L Version 5.1 and later

  • The minimum shared-memory segment size is 1 byte.

  • The maximum number of shared memory IDs is 4096 for operating system releases before AIX Version 4.3.2 and 131072 for AIX Version 4.3.2 and following.

Parameters
SharedMemoryIDSpecifies an identifier returned by the shmget subroutine.
BufferIndicates a pointer to the shmid_ds structure. The shmid_ds structure is defined in the sys/shm.h file.
CommandThe commands listed in Table C-2 are available.

Table C-2. Values for the third parameter of shmctl()
ValueDescription
IPC_STATObtains status information about the shared memory segment identified by the SharedMemoryID parameter. This information is stored in the area pointed to by the Buffer parameter. The calling process must have read permission to run this command.
IPC_SETSets the user and group IDs of the owner as well as the access permissions for the shared memory segment identified by the SharedMemoryID parameter. This command sets the following fields: 

shm_perm.uid  /* owning user ID       */
shm_perm.gid  /* owning group ID      */
shm_perm.mode /* permission bits only */

You must have an effective user ID equal to root or to the value of the shm_perm.cuid or shm_perm.uid field in the shmid_ds data structure identified by the SharedMemoryID parameter.
IPC_RMIDRemoves the shared memory identifier specified by the SharedMemoryID parameter from the system and erases the shared memory segment and data structure associated with it. This command is only executed by a process that has an effective user ID equal either to that of superuser or to the value of the shm_perm.uid or shm_perm.cuid field in the data structure identified by the SharedMemoryID parameter.
SHM_SIZESets the size of the shared memory segment to the value specified by the shm_segsz field of the structure specified by the Buffer parameter. This value can be larger or smaller than the current size. The limit is the maximum shared-memory segment size. This command is only executed by a process that has an effective user ID equal either to that of a process with the appropriate privileges or to the value of the shm_perm.uid or shm_perm.cuid field in the data structure identified by the SharedMemoryID parameter. This command is not supported for regions created with the environment variable EXTSHM=ON. This results in a return value of -1 with errno set to EINVAL. Attempting to use the SHM_SIZE on a shared memory region larger than 256 MB or attempting to increase the size of a shared memory region larger than 256 MB results in a return value of -1 with errno set to EINVAL.

Return values

When completed successfully, the shmctl() subroutine returns a value of 0. Otherwise, it returns a value of -1 and the errno global variable is set to indicate the error.

Error codes

The shmctl() subroutine is unsuccessful if one or more of the following are true:

EACCESThe Command parameter is equal to the IPC_STAT value and read permission is denied to the calling process.
EFAULTThe Buffer parameter points to a location outside the allocated address space of the process.
EINVALThe SharedMemoryID parameter is not a valid shared memory identifier.
EINVALThe Command parameter is not a valid command.
EINVALThe Command parameter is equal to the SHM_SIZE value and the value of the shm_segsz field of the structure specified by the Buffer parameter is not valid.
EINVALThe Command parameter is equal to the SHM_SIZE value and the shared memory region was created with the environment variable EXTSHM=ON.
ENOMEMThe Command parameter is equal to the SHM_SIZE value, and the attempt to change the segment size is unsuccessful because the system does not have enough memory.
EOVERFLOWThe Command parameter is IPC_STAT and the size of the shared memory region is greater than or equal to 4 GB. This only happens with 32-bit programs.
EPERMThe Command parameter is equal to the IPC_RMID or SHM_SIZE value, and the effective user ID of the calling process is not equal to the value of the shm_perm.uid or shm_perm.cuid field in the data structure identified by the SharedMemoryID parameter. The effective user ID of the calling process is not the root user ID.

The shmget() routine

The shmget() subroutine returns the shared memory identifier associated with the specified key parameter.

Library

Standard C library (libc.a)

Syntax
#include <sys/shm.h>
int shmget(Key, Size, Shm_mem_flag)
key_t       Key;
size_t      Size;
int         Shm_mem_flag;

Description

The shmget() subroutine returns the shared memory identifier associated with the specified Key parameter.

The following limits apply to shared memory:

  • The maximum shared-memory segment size is:

    - 256 MB before AIX Version 4.3.1

    - 2 GB for AIX Version 4.3.1 through AIX 5L Version 5.1

    - 64 GB for 64-bit applications for AIX 5L Version 5.1 and later

  • The minimum shared-memory segment size is 1 byte.

  • The maximum number of shared memory IDs is 4096 for operating system released before AIX Version 4.3.22 and 131072 for AIX Version 4.3.2 and following.

Parameters
KeySpecify either the IPC_PRIVATE value or an IPC key constructed by ftok() routine.
SizeSpecify the number of bytes of shared memory required.
Shm_mem_flagConstructed by logically ORing one or more of the values in Table C-3

Table C-3. Values for the third parameter of shmget()
ValueDescription
IPC_CREATECreates the data structure if it does not already exist.
IPC_EXCLCause the shmget() subroutine to be unsuccessful if the IPC_CREATE flag is also set, and the data structure already exists.
SHM_LGPAGEAttempts to create the region so it can be mapped through hardware-supported, large-page mechanisms, if enabled. This is purely advisory. For the system to consider this flag, it must be used in conjunction with the SHM_PIN flag and enabled with the vmtune command (-L to reserve memory for the region (which requires a reboot) and -S to enable SHM_PIN). To successfully get large-pages, the user requesting large-page shared memory must have CAP_BYPASS_RAC_VMM capability. This has not effect on shared memory regions created with the EXTSHM=ON environment variable.
SHM_PINAttempts to pin the shared memory region if enabled. This is purely advisory. For the system to consider this flag, the system must be enabled with the vmtune command. This has no effect on shared memory regions created with the EXTSHM=ON environment variable.
S_IRUSRPermits the process that owns the data structure to read it.
S_IWUSRPermits the process that owns the data structure to modify it.
S_IRGRPPermits the group associated with the data structure to read it.
S_IWGRPPermits the group associated with the data structure to modify it.
S_IROTHPermits others to read the data structure.
S_IWOTHPermits others to modify the data structure.
Values that begin with S_I prefix are defined in the /usr/include/sys/mode.h file and are a subset of the access permissions that apply to files.

A shared memory identifier, its associated data structure, and a shared memory segment equal in number of bytes to the value of the Size parameter are created for the Key parameter if one of the following is true:

  • The Key parameter is equal to the IPC_PRIVATE value.

  • The Key parameter does not already have a shared memory identifier associated with it, and the IPC_CREAT flag is set in the SharedMemoryFlag parameter.

Upon creation, the data structure associated with the new shared memory identifier is initialized as follows:

  • The shm_perm.cuid and shm_perm.uid fields are set to the effective user ID of the calling process.

  • The shm_perm.cgid and shm_perm.gid fields are set to the effective group ID of the calling process.

  • The low-order 9 bits of the shm_perm.mode field are set to the low-order 9 bits of the SharedMemoryFlag parameter.

  • The shm_segsz field is set to the value of the Size parameter.

  • The shm_lpid, shm_nattch, shm_atime, and shm_dtime fields are set to 0.

  • The shm_ctime field is set to the current time.

Once created, a shared memory segment is deleted only when the system reboots, by issuing the ipcrm command, or by using the following shmctl subroutine:

if (shmctl(id, IPC_RMID, 0) == -1)
    perror("error in closing segment"), exit (1);

Return values

Upon successful completion, a shared memory identifier is returned. Otherwise, the shmget() subroutine returns a value of -1 and sets the errno global variable to indicate the error.

Error codes

The shmget() subroutine is unsuccessful if one or more of the following are true:

EACCESA shared memory identifier exists for the Key parameter, but operation permission, as specified by the low-order 9 bits of the SharedMemoryFlag parameter, is not granted.
EEXISTA shared memory identifier exists for the Key parameter, and both the IPC_CREAT and IPC_EXCL flags are set in the SharedMemoryFlag parameter.
EINVALA shared memory identifier does not exist and the Size parameter is less than the system-imposed minimum or greater than the system-imposed maximum.
EINVALA shared memory identifier exists for the Key parameter, but the size of the segment associated with it is less than the Size parameter, and the Size parameter is not equal to 0.
ENOENTA shared memory identifier does not exist for the Key parameter, and the IPC_CREAT flag is not set in the SharedMemoryFlag parameter.
ENOMEMA shared memory identifier and associated shared memory segment are to be created, but the amount of available physical memory is not sufficient to meet the request.
ENOSPCA shared memory identifier will be created, but the system-imposed maximum of shared memory identifiers allowed will be exceeded.

The shmdt() subroutine

Detaches a shared memory segment.

Library

Standard C library (libc.a)

Syntax
#include <sys/shm.h>
int shmdt (SharedMemoryAddress)
const void * SharedMemoryAddress;

Description

The shmdt() subroutine detaches, from the data segment of the calling process, the shared memory segment located at the address specified by the SharedMemoryAddress parameter.

Mapped file segments are automatically detached when the mapped file is closed. However, you can use the shmdt() subroutine to explicitly release the segment register used to map a file. Shared memory segments must be explicitly detached with the shmdt() subroutine.

If the file was mapped for writing, the shmdt() subroutine updates the mtime and ctime time stamps.

The following limits apply to shared memory:

  • The maximum shared-memory segment size is:

    - 256 MB before AIX Version 4.3.1

    - 2 GB for AIX Version 4.3.1 through AIX 5L Version 5.1

    - 64 GB for 64-bit applications for AIX 5L Version 5.1 and later

  • The minimum shared-memory segment size is 1 byte.

  • The maximum number of shared memory IDs is 4096 for operating system releases before AIX Version 4.3.2 and 131072 for AIX Version 4.3.2 and following.

Parameters
SharedMemoryAddressSpecifies the data segment start address of a shared memory segment.

Return values

When successful, the shmdt subroutine returns a value of 0. Otherwise, the shared memory segment at the address specified by the SharedMemoryAddress parameter is not detached, a value of 1 is returned, and the errno global variable is set to indicate the error.

Error codes

The shmdt() subroutine is unsuccessful if the following condition is true:

EINVALThe value of the SharedMemoryAddress parameter is not the data-segment start address of a shared memory segment.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset