shmat()--Attach Shared Memory Segment to Current Process

 #include <sys/shm.h>

 void *shmat(int shmid, const void *shmaddr, 
            int shmflg);

The shmat() function attaches to the shared memory segment specified by shmid and returns the address of the shared memory segment.

The address specified by shmaddr is only used when shmat() is called from a program that uses data model *LLP64 and attaches to a teraspace shared memory segment. Otherwise the address specified by shmaddr is ignored and the actual shared memory segment address is returned regardless of the value of shmaddr.

The system maintains status information about a shared memory segment which can be retrieved with the shmctl() function. When a shared memory segment is successfully attached, the system sets the members of the shmid_ds structure as follows:

• shm_nattch is incremented by 1.

• shm_lpid is set to the process ID of the calling thread.

• shm_atime is set to the current time.

Parameters

shmid

(Input) Shared memory identifier, a positive integer. It is returned by the shmget() function and used to identify the shared memory segment.

shmaddr

(Input) Shared memory address. The address at which the calling thread would like the shared memory segment attached.

shmflg

(Input) Operations flags. The value of the shmflg parameter is either zero or is obtained by performing an OR operation on one or more of the following constants:

SHM_RDONLY (0x00001000)

Attach the shared memory segment in read-only mode. This flag is valid only for teraspace shared memory segments.

Authorities

Authorization Required for shmat()

Return Value

Error Conditions

If shmat() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

[EACCES]

Permission denied.

An attempt was made to access an object in a way forbidden by its object access permissions.

The thread does not have access to the specified file, directory, component, or path.

Operation permission is denied to the calling thread.

Shared memory operations are not permitted because the QSHRMEMCTL system value is set to 0.

The shared memory segment is to be attached in read/write mode and the calling thread does not read and write permission to the shared memory segment.

The shared memory segment is to be attached in read-only mode and the calling thread does not read permission to the shared memory segment.

[EADDRINUSE]

A damaged object was encountered.

Address already in use.

An attempt was made to attach to a teraspace shared memory segment with the SHM_MAP_FIXED_NP attribute and the address range is not available in the teraspace of the current job.

[EDAMAGE]

A damaged object was encountered.

The shared memory segment has been damaged by a previous shared memory operation.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL.

The shmid parameter is not a valid shared memory identifier.

[EOPNOTSUPP]

Operation not supported.

The operation, though supported in general, is not supported for the requested object or the requested arguments.

The SHM_RDONLY flag is set in the shmflg parameter. Read-only shared memory segments are not supported for nonteraspace shared memory segments and for shared memory segments created with the SHM_MAP_FIXED_NP attribute.

[ENOMEM]

Storage allocation request failed.

A function needed to allocate storage, but no storage is available.

The available data space is not large enough to accommodate the shared memory segment.

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

Error Messages

None.

Usage Notes

1. The only supported operation flag is SHM_RDONLY. This operation flag is supported only when you attach to a teraspace shared memory segment. If shmflg specifies SHM_RDONLY for a nonteraspace shared memory segment, then an [EOPNOTSUPP] error is returned. All other values for shmflg are ignored.
   
   
2. A module that was not created with teraspace memory enabled should not attach to a teraspace shared memory segment. The call to shmat() will succeed and return a pointer. Any attempt, however, by a module not created with teraspace memory enabled to use the returned pointer will result in an MCH3601 (Pointer not set for location referenced) exception.
   
   
3. When a job attaches to a shared memory segment that was created with the SHM_MAP_FIXED_NP attribute, an address range within the job's teraspace is used for the shared memory mapping. When a subsequent job attaches to the shared memory segment, the same address range within its teraspace must be available. If the address range is not available, the call to shmat() will fail with an [EADDRINUSE] error.
   
   
4. The storage for a shared memory segment is allocated when the first job attaches to the shared memory segment. The storage is charged against the job's temporary storage limit. If the job does not have enough temporary storage to satisfy the request, the call to shmat() will fail with an [ENOMEM] error.

Related Information

• The <sys/shm.h> file (see Header Files for UNIX-Type Functions)
  
  
• shmctl()--Perform Shared Memory Control Operations
  
  
• shmget()--Get ID of Shared Memory Segment with Key
  
  
• shmdt()--Detach Shared Memory Segment from Calling Process

Example

See Code disclaimer information for information pertaining to code examples.

For an example of using this function, see Using Semaphores and Shared Memory in Examples: APIs.