'\" te .\" Copyright (c) 2011, Oracle and/or its affiliates. All rights reserved. .TH shmadv 2 "5 May 2011" "SunOS 5.11" "System Calls" .SH NAME shmadv \- shared memory advice .SH SYNOPSIS .LP .nf #include #include #include int shmadv(int shmid, uint_t cmd, uint_t *advice); .fi .SH DESCRIPTION .sp .LP The \fBshmadv()\fR function enables setting or getting advice for a given shared memory ID, \fIshmid\fR. The \fIcmd\fR argument can be set to \fBSHM_ADV_GET\fR or \fBSHM_ADV_SET\fR to get or set the advice. The \fIadvice\fR 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. .sp .LP The \fIadvice\fR argument can take one of the following values: .sp .ne 2 .mk .na \fB\fBSHM_ACCESS_DEFAULT\fR\fR .ad .sp .6 .RS 4n Reset operating system's expectation of how this shared memory segment will be accessed to the default. .RE .sp .ne 2 .mk .na \fB\fBSHM_ACCESS_LWP\fR\fR .ad .sp .6 .RS 4n 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. .RE .sp .ne 2 .mk .na \fB\fBSHM_ACCESS_MANY\fR\fR .ad .sp .6 .RS 4n 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. .RE .sp .ne 2 .mk .na \fB\fBSHM_ACCESS_MANY_PSET\fR\fR .ad .sp .6 .RS 4n 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. .RE .sp .LP The \fBSHM_ACCESS\fR advice can be given on the shared memory ID before \fBshmat\fR(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 \fBSHM_SHARE_MMU\fR flag to \fBshmat()\fR since all of the memory for ISM segments is allocated during \fBshmat()\fR. .sp .LP The \fBSHM_ACCESS\fR advice is very similar to advice that can be given using \fBmadvise\fR(3C). However, \fBmadvise()\fR 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 \fBshmat()\fR. .sp .LP The \fBshmadv()\fR function can be used only to apply advice to a System V shared memory segment before it is allocated by \fBshmat()\fR. The \fBmadvise()\fR function can be used only on a System V shared memory segment after \fBshmat()\fR has been called to create the segment. .SH RETURN VALUES .sp .LP Upon successful completion, 0 is returned. Otherwise, -1 is returned and \fIerrno\fR is set to indicate the error. .SH ERRORS .sp .LP The \fBshmadv()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBEACCES\fR\fR .ad .RS 10n .rt Operation permission is denied to the calling process (see \fBIntro\fR(2)). .RE .sp .ne 2 .mk .na \fB\fBEBUSY\fR\fR .ad .RS 10n .rt 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 \fBshmat()\fR already. .RE .sp .ne 2 .mk .na \fB\fBEFAULT\fR\fR .ad .RS 10n .rt The \fIadvice\fR argument points to an illegal address. .RE .sp .ne 2 .mk .na \fB\fBEINVAL\fR\fR .ad .RS 10n .rt The \fIshmid\fR, \fIcmd\fR, or \fIadvice\fR being set is not valid. .RE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityCommitted .TE .SH SEE ALSO .sp .LP \fBIntro\fR(2), \fBshmat\fR(2), \fBshmget\fR(2), \fBattributes\fR(5)