shmadv

- shared memory advice

Synopsis

#include <sys/shm.h>
#include <sys/shm_impl.h>
#include <sys/syscall.h>

int shmadv(int shmid, uint_t cmd, uint_t *advice);

Description

The shmadv() function enables setting or getting advice for a given shared memory ID, shmid. The cmd argument can be set to SHM_ADV_GET or SHM_ADV_SET to get or set the advice. The advice argument is a pointer to a buffer allocated and given by the application. It is used to pass the value of the advice into or out of the function when setting or getting advice.

The advice argument can take one of the following values:

SHM_ACCESS_DEFAULT

Reset operating system's expectation of how this shared memory segment will be accessed to the default.

SHM_ACCESS_LWP

Tell the operating system that the next LWP to touch the shared memory segment will access it heavily, so the operating system should allocate the memory and other resources for this segment accordingly.

SHM_ACCESS_MANY

Tell the operating system that many processes and/or LWPs will access the specified shared memory segment randomly across the machine, so the operating system should try to allocate the resources for this range accordingly.

SHM_ACCESS_MANY_PSET

Tell the operating system that many processes and/or LWPs in a processor set will access the specified shared memory segment randomly across the machine, so the operating system should try to allocate the resources for this range accordingly.

The SHM_ACCESS advice can be given on the shared memory ID before shmat(2) is called to create the shared memory segment. Doing this is useful for affecting how the memory will be allocated for the shared memory segment before it is allocated. This is especially useful for Intimate Shared Memory (ISM) segments created with the SHM_SHARE_MMU flag to shmat() since all of the memory for ISM segments is allocated during shmat().

The SHM_ACCESS advice is very similar to advice that can be given using madvise(3C). However, madvise() can apply advice only to an existing address range and consequently can be used only to affect a System V shared memory segment after it has been created by shmat().

The shmadv() function can be used only to apply advice to a System V shared memory segment before it is allocated by shmat(). The madvise() function can be used only on a System V shared memory segment after shmat() has been called to create the segment.

Return Values

Upon successful completion, 0 is returned. Otherwise, -1 is returned and errno is set to indicate the error.

Errors

The shmadv() function will fail if:

EACCES

Operation permission is denied to the calling process (see Intro(2)).

EBUSY

It is too late to apply advice to affect the memory allocation of the shared memory segment with the specified shared memory ID because it has been allocated by shmat() already.

EFAULT

The advice argument points to an illegal address.

EINVAL

The shmid, cmd, or advice being set is not valid.

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

Intro(2), shmat(2), shmget(2), attributes(5)