OpenSolaris 2009.06 - man page for madvise (opensolaris section 3C)

Linux & Unix Commands - Search Man Pages

Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


madvise(3C)			   Standard C Library Functions 		      madvise(3C)

NAME
       madvise - provide advice to VM system

SYNOPSIS
       #include <sys/types.h>
       #include <sys/mman.h>

       int madvise(caddr_t addr, size_t len, int advice);

DESCRIPTION
       The madvise() function advises the kernel that a region of user mapped memory in the range
       [addr, addr + len) will be accessed following a type of	pattern.  The  kernel  uses  this
       information to optimize the procedure for manipulating and maintaining the resources asso-
       ciated with the specified mapping range.

       Values for advice are defined in <sys/mman.h> as:

	 #define MADV_NORMAL	       0x0  /* No further special treatment */
	 #define MADV_RANDOM	       0x1  /* Expect random page references */
	 #define MADV_SEQUENTIAL       0x2  /* Expect sequential page references */
	 #define MADV_WILLNEED	       0x3  /* Will need these pages */
	 #define MADV_DONTNEED	       0x4  /* Don't need these pages */
	 #define MADV_FREE	       0x5  /* Contents can be freed */
	 #define MADV_ACCESS_DEFAULT   0x6  /* default access */
	 #define MADV_ACCESS_LWP       0x7  /* next LWP to access heavily */
	 #define MADV_ACCESS_MANY      0x8  /* many processes to access heavily */

       MADV_NORMAL	      This is the default system characteristic  where	accessing  memory
			      within  the  address  range causes the system to read data from the
			      mapped file. The kernel reads all data from files into pages  which
			      are retained for a period of time as a "cache." System pages can be
			      a scarce resource, so the kernel steals pages from  other  mappings
			      when  needed.  This  is  a likely occurrence, but adversely affects
			      system performance only if a large amount of memory is accessed.

       MADV_RANDOM	      Tell the kernel to read in a minimum amount of data from	a  mapped
			      file  on any single particular access. If  MADV_NORMAL is in effect
			      when an address of a mapped file is accessed, the system	tries  to
			      read  in	as much data from the file as reasonable, in anticipation
			      of other accesses within a certain locality.

       MADV_SEQUENTIAL	      Tell the system that addresses in  this  range  are  likely  to  be
			      accessed	only  once, so the system will free the resources mapping
			      the address range as quickly as possible.

       MADV_WILLNEED	      Tell the system that a certain address range is  definitely  needed
			      so  the  kernel will start reading the specified range into memory.
			      This can benefit programs wanting to minimize the  time  needed  to
			      access  memory  the first time, as the kernel would need to read in
			      from the file.

       MADV_DONTNEED	      Tell the kernel that the	specified  address  range  is  no  longer
			      needed,  so the system starts to free the resources associated with
			      the address range.

       MADV_FREE	      Tell the kernel that contents in the specified address range are no
			      longer  important  and the range will be overwritten. When there is
			      demand for memory, the system will free pages associated	with  the
			      specified  address range. In this instance, the next time a page in
			      the address range is referenced, it will contain all zeroes.   Oth-
			      erwise,  it  will  contain  the  data  that  was there prior to the
			      MADV_FREE call. References made to the address range will not  make
			      the  system  read from backing store (swap space) until the page is
			      modified again.

			      This value cannot be used on mappings  that  have  underlying  file
			      objects.

       MADV_ACCESS_LWP	      Tell  the  kernel  that the next LWP to touch the specified address
			      range will access it most heavily, so  the  kernel  should  try  to
			      allocate	the memory and other resources for this range and the LWP
			      accordingly.

       MADV_ACCESS_MANY       Tell the kernel that many processes and/or  LWPs	will  access  the
			      specified  address range randomly across the machine, so the kernel
			      should try to allocate the memory  and  other  resources	for  this
			      range accordingly.

       MADV_ACCESS_DEFAULT    Reset  the kernel's expectation for how the specified range will be
			      accessed to the default.

       The madvise() function should be used by applications with  specific  knowledge	of  their
       access  patterns  over  a memory object, such as a mapped file, to increase system perfor-
       mance.

RETURN VALUES
       Upon successful completion, madvise() returns 0; otherwise, it returns -1 and  sets  errno
       to indicate the error.

ERRORS
       EAGAIN	 Some  or  all	mappings  in the  address  range [addr,  addr  +  len) are locked
		 for I/O.

       EBUSY	 Some or all of the addresses in the range [addr, addr	+  len)  are  locked  and
		 MS_SYNC with the MS_INVALIDATE option is specified.

       EFAULT	 Some  or all of the addresses in the specified range could not be read into mem-
		 ory from the underlying object  when  performing  MADV_WILLNEED.  The	madvise()
		 function  could  return  prior  to  this condition being detected, in which case
		 errno will not be set to EFAULT.

       EINVAL	 The addr argument is not a multiple of the page size as returned by sysconf(3C),
		 the  length of the specified address range is equal to 0, or the advice argument
		 was invalid.

       EIO	 An I/O error occurred while reading from or writing to the file system.

       ENOMEM	 Addresses in the range [addr, addr + len) are outside the valid  range  for  the
		 address space of a process, or specify one or more pages that are not mapped.

       ESTALE	 Stale NFS file handle.

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Stable			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       meminfo(2), mmap(2), sysconf(3C), attributes(5)

SunOS 5.11				   23 Feb 2005				      madvise(3C)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:54 AM.

Unix & Linux Forums Content Copyright©1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password





Not a Forum Member?
Forgot Password?