'\" te .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] .TH MADV.SO.1 1 "Feb 15, 2002" .SH NAME madv.so.1 \- madv library .SH SYNOPSIS .LP .nf \fB/usr/lib/madv.so.1\fR .fi .SH DESCRIPTION .sp .LP The \fBmadv.so.1\fR shared object provides a means by which the VM advice can be selectively configured for a launched process (or processes) and its descendants. To enable \fBmadv.so.1\fR, the following string needs to be present in the environment (see \fBld.so.1\fR(1)) along with one or more \fBMADV\fR environment variables: .sp .in +2 .nf \fBLD_PRELOAD=$LD_PRELOAD:madv.so.1\fR .fi .in -2 .sp .SH ENVIRONMENT VARIABLES .sp .LP If the \fBmadv.so.1\fR shared object is specified in the \fBLD_PRELOAD\fR list, the following environment variables are read by the \fBmadv\fR shared object to determine to which created process(es) to apply the specified advice. .sp .ne 2 .na \fB\fBMADV\fR=\fIadvice\fR \fR .ad .RS 27n \fBMADV\fR specifies the VM advice to use for all heap, shared memory, and mmap regions in the process address space. This advice is applied to all created processes. .sp Values for \fIadvice\fR correspond to values in <sys/mman.h> used in \fBmadvise\fR(3C) to specify memory access patterns: .br .in +2 normal .in -2 .br .in +2 random .in -2 .br .in +2 sequential .in -2 .br .in +2 access_lwp .in -2 .br .in +2 access_many .in -2 .br .in +2 access_default .in -2 .RE .sp .ne 2 .na \fB\fBMADVCFGFILE\fR=\fIconfig-file\fR\fR .ad .RS 27n \fIconfig-file\fR is a text file which contains one or more \fBmadv\fR configuration entries of the form: .sp .in +2 .nf \fIexec-name\fR \fIexec-args\fR:\fIadvice-opts\fR .fi .in -2 .sp Advice specified in \fIconfig-file\fR takes precedence over that specified by the \fBMADV\fR environment variable. When \fBMADVCFGFILE\fR is not set, advice is taken from file \fB/etc/madv.conf\fR if it exists. .sp \fIexec-name\fR specifies the name of an application or executable. The corresponding advice is set for newly created processes (see \fBgetexecname\fR(3C)) that match the first \fIexec-name\fR found in the file. .sp \fIexec-name\fR can be a full pathname, a base name, or a pattern string. See \fBFile Name Generation\fR in \fBsh\fR(1) for a discussion of pattern matching. .sp \fIexec-args\fR is an optionally specified pattern string to match against arguments. Advice is set only if \fIexec-args\fR is not specified or occurs within the arguments to \fIexec-name\fR. .sp \fIadvice-opts\fR is a comma-separated list specifying the advice for various memory region(s): .sp .ne 2 .na \fB\fBmadv\fR=\fIadvice\fR\fR .ad .RS 21n Applies to all heap, shared memory, and mmap regions in the process address space. .RE .sp .ne 2 .na \fB\fBheap\fR=\fIadvice\fR\fR .ad .RS 21n The heap is defined to be the brk area (see \fBbrk\fR(2)). Applies to the existing heap and for any additional heap memory allocated in the future. .RE .sp .ne 2 .na \fB\fBshm\fR=\fIadvice\fR\fR .ad .br .na \fB\fBism\fR=\fIadvice\fR\fR .ad .br .na \fB\fBdism\fR=\fIadvice\fR\fR .ad .RS 21n Shared memory segments (see \fBshmat\fR(2)) attached using any flags, flag \fBSHM_SHARE_MMU\fR, or flag \fBSHM_PAGEABLE\fR respectively. Options \fBism\fR and \fBdism\fR take precedence over option \fBshm\fR. .RE .sp .ne 2 .na \fB\fBmap\fR=\fIadvice\fR\fR .ad .br .na \fB\fBmapshared\fR=\fIadvice\fR\fR .ad .br .na \fB\fBmapprivate\fR=\fIadvice\fR\fR .ad .br .na \fB\fBmapanon\fR=\fIadvice\fR\fR .ad .RS 21n Mappings established through \fBmmap\fR(2) using any flags, flag \fBMAP_SHARED\fR, flag \fBMAP_PRIVATE\fR, or flag \fBMAP_ANON\fR, respectively. Options \fBmapshared\fR, \fBmapprivate\fR, and \fBmapanon\fR take precedence over option \fBmap\fR. Option \fBmapanon\fR takes precedence over \fBmapshared\fR and \fBmapprivate\fR. .RE .RE .sp .ne 2 .na \fB\fBMADVERRFILE\fR=\fIpathname\fR\fR .ad .RS 27n By default, error messages are logged via \fBsyslog\fR(3C) using level \fBLOG_ERR\fR and facility \fBLOG_USER\fR. If \fBMADVERRFILE\fR contains a valid \fIpathname\fR (such as \fB/dev/stderr\fR), error messages will be logged there instead. .RE .SH EXAMPLES .LP \fBExample 1 \fRApplying advice to all ISM segments .sp .LP The following configuration applies advice to all ISM segments for application \fB/usr/bin/foo\fR: .sp .in +2 .nf example$ \fBLD_PRELOAD=$LD_PRELOAD:madv.so.1\fR example$ \fBMADVCFGFILE=madvcfg\fR example$ \fBexport LD_PRELOAD MADVCFGFILE\fR example$ \fBcat $MADVCFGFILE\fR /usr/bin/foo:ism=access_lwp .fi .in -2 .sp .LP \fBExample 2 \fRSetting advice for all applications with exception .sp .LP The following configuration sets advice for all applications with the exception of \fBls\fR. .sp .in +2 .nf example$ \fBLD_PRELOAD=$LD_PRELOAD:madv.so.1\fR example$ \fBMADV=access_many\fR example$ \fBMADVCFGFILE=madvcfg\fR example$ \fBexport LD_PRELOAD MADV MADVCFGFILE\fR example$ \fBcat $MADVCFGFILE\fR ls: .fi .in -2 .sp .LP \fBExample 3 \fRPrecedence rules (continuation from Example 2) .sp .LP Because \fBMADVCFGFILE\fR takes precedence over \fBMADV\fR, specifying '\fB*\fR' (pattern match all) for the \fIexec-name\fR of the last \fBmadv\fR configuration entry would be equivalent to setting \fBMADV\fR. The following is equivalent to example 2: .sp .in +2 .nf example$ \fBLD_PRELOAD=$LD_PRELOAD:madv.so.1\fR example$ \fBMADVCFGFILE=madvcfg\fR example$ \fBexport LD_PRELOAD MADVCFGFILE\fR example$ \fBcat $MADVCFGFILE\fR ls: *:madv=access_many .fi .in -2 .sp .LP \fBExample 4 \fRApplying advice for different regions .sp .LP The following configuration applies one type of advice for mmap regions and different advice for heap and shared memory regions for a select set of applications with exec names that begin with \fBfoo\fR: .sp .in +2 .nf example$ \fBLD_PRELOAD=$LD_PRELOAD:madv.so.1\fR example$ \fBMADVCFGFILE=madvcfg\fR example$ \fBexport LD_PRELOAD MADVCFGFILE\fR example$ \fBcat $MADVCFGFILE\fR foo*:madv=access_many,heap=sequential,shm=access_lwp .fi .in -2 .sp .LP \fBExample 5 \fRApplying advice selectively .sp .LP The following configuration applies advice for the heap of applications beginning with \fBora\fR that have \fBora1\fR as an argument: .sp .in +2 .nf example$ \fBLD_PRELOAD=$LD_PRELOAD:madv.so.1\fR example$ \fBMADVCFGFILE=madvcfg\fR example$ \fBexport LD_PRELOAD MADVCFGFILE\fR example$ \fBcat $MADVCFGFILE\fR ora* ora1:heap=access_many .fi .in -2 .sp .SH FILES .sp .ne 2 .na \fB\fB/etc/madv.conf\fR \fR .ad .RS 19n Configuration file .RE .SH SEE ALSO .sp .LP .BR cat (1), .BR ld.so.1 (1), .BR proc (1), .BR sh (1), .BR brk (2), .BR exec (2), .BR fork (2), .BR memcntl (2), .BR mmap (2), .BR shmat (2), .BR getexecname (3C), .BR madvise (3C), .BR syslog (3C), .BR proc (5), .BR attributes (7) .SH NOTES .sp .LP The advice is inherited. A child process has the same advice as its parent. On \fBexec()\fR (see \fBexec\fR(2)), the advice is set back to the default system advice unless different advice has been configured via the \fBmadv\fR shared object. .sp .LP Advice is only applied to \fBmmap\fR regions explicitly created by the user program. Those regions established by the run-time linker or by system libraries making direct system calls (for example, libthread allocations for thread stacks) are not affected.