shmat()-Attach Shared Memory Segment to Current Process

#include <sys/shm.h>

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

The shmat() function returns the address of the shared memory segment associated with the specified shared memory identifier.

Parameters

shmid

(Input) Shared memory identifier.

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 the following constant:

'0x1000' or SHM_RDONLY

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

Authorities

Figure 1-14. Authorization Required for shmat()

Object Referred to	Authority Required	errno
Shared memory segment to be attached in read/write memory	Read and Write	EACCES
Shared memory segment to be attached in read-only memory in a process's teraspace.	Read	EACCES

Return Value

value

shmat() was successful. The value returned is a pointer to the shared memory segment associated with the specified identifier.

NULL

shmat() was not successful. The errno variable is set to indicate the error.

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.

[EADDRINUSE]

A damaged object was encountered.

Address already in use.

An attempt was made to attach to a SHM_MAP_FIXED_NP teraspace shared memory segment, but the address range is not available in the teraspace of the current process.

[EDAMAGE]

A damaged object was encountered.

The value of shmid corresponds to a shared memory ID that has been marked as 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 value of shmid 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 value of (shmflg & SHM_RDONLY) is not zero. (& is a bitwise AND.) Read-only shared memory segments are not supported for nonteraspace shared memory segments. Read-only shared memory segments are not supported for shared memory segments created using the SHM_MAP_FIXED_NP option of shmget().

[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

The IPC implementation has the following restrictions over the X/Open single UNIX specification (formerly Spec 1170) definition:

1. The address specified by shmaddr is always ignored. The actual shared memory segment address is returned regardless of the value of shmaddr.

2. The only supported operation flag is SHM_READONLY. 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.

3. 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.

4. When a process attaches to a shared memory segment that was created using SHM_MAP_FIXED_NP, an address range within the process's teraspace is used for the shared memory mapping. When a subsequent process 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.

5. The storage for a shared memory segment is allocated when the first process attaches to the shared memory segment. The storage is charged against the process's temporary storage limit. If the process 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

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