Print this page 
12010 extra whitespace in mmap(2)
Split Close
Expand all
Collapse all
          --- old/usr/src/man/man2/mmap.2
          +++ new/usr/src/man/man2/mmap.2
↓ open down ↓ 37 lines elided ↑ open up ↑ 
  38   38  .\" If applicable, add the following below this CDDL HEADER, with the
  39   39  .\" fields enclosed by brackets "[]" replaced with your own identifying
  40   40  .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41   41  .\"
  42   42  .\"
  43   43  .\" Copyright 1989 AT&T
  44   44  .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
  45   45  .\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
  46   46  .\" Copyright 2013 OmniTI Computer Consulting, Inc. All Rights Reserved.
  47   47  .\" Copyright 2016 James S Blachly, MD. All Rights Reserved.
       48 +.\" Copyright 2019 Joyent, Inc.
  48   49  .\"
  49      -.TH MMAP 2 "August 29, 2016"
       50 +.TH MMAP 2 "Nov 19, 2019"
  50   51  .SH NAME
  51   52  mmap \- map pages of memory
  52   53  .SH SYNOPSIS
  53      -.LP
  54   54  .nf
  55   55  #include <sys/mman.h>
  56   56  
  57   57  \fBvoid *\fR\fBmmap\fR(\fBvoid *\fR\fIaddr\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIprot\fR, \fBint\fR \fIflags\fR,
  58   58       \fBint\fR \fIfildes\fR, \fBoff_t\fR \fIoff\fR);
  59   59  .fi
  60   60  
  61   61  .SH DESCRIPTION
  62      -.LP
  63   62  The \fBmmap()\fR function establishes a mapping between a process's address
  64   63  space and a file or shared memory object. The format of the call is as follows:
  65   64  .sp
  66   65  .LP
  67   66  \fIpa\fR = \fBmmap(\fR\fIaddr\fR\fB, \fR\fIlen\fR\fB, \fR\fIprot\fR\fB,
  68   67  \fR\fIflags\fR\fB, \fR\fIfildes\fR\fB, \fR\fIoff\fR\fB);\fR
  69   68  .sp
  70   69  .LP
  71   70  The \fBmmap()\fR function establishes a mapping between the address space of
  72   71  the process at an address \fIpa\fR for \fIlen\fR bytes to the memory object
  73   72  represented by the file descriptor \fIfildes\fR at offset \fIoff\fR for
  74      -\fIlen\fR bytes. The value of \fIpa\fR is a function of the  \fIaddr\fR
       73 +\fIlen\fR bytes. The value of \fIpa\fR is a function of the \fIaddr\fR
  75   74  argument and values of \fIflags\fR, further described below. A successful
  76   75  \fBmmap()\fR call returns \fIpa\fR as its result. The address range starting at
  77   76  \fIpa\fR and continuing for \fIlen\fR bytes will be legitimate for the possible
  78   77  (not necessarily current) address space of the process. The range of bytes
  79   78  starting at \fIoff\fR and continuing for \fIlen\fR bytes will be legitimate for
  80   79  the possible (not necessarily current) offsets in the file or shared memory
  81   80  object represented by \fIfildes\fR.
  82   81  .sp
  83   82  .LP
  84   83  The \fBmmap()\fR function allows [\fIpa, pa + len\fR) to extend beyond the end
↓ open down ↓ 13 lines elided ↑ open up ↑ 
  98   97  If the size of the mapped file changes after the call to \fBmmap()\fR as a
  99   98  result of some other operation on the mapped file, the effect of references to
 100   99  portions of the mapped region that correspond to added or removed portions of
 101  100  the file is unspecified.
 102  101  .sp
 103  102  .LP
 104  103  The \fBmmap()\fR function is supported for regular files and shared memory
 105  104  objects. Support for any other type of file is unspecified.
 106  105  .sp
 107  106  .LP
 108      -The  \fIprot\fR argument determines whether read, write, execute, or some
      107 +The \fIprot\fR argument determines whether read, write, execute, or some
 109  108  combination of accesses are permitted to the data being mapped. The \fIprot\fR
 110  109  argument should be either \fBPROT_NONE\fR or the bitwise inclusive \fBOR\fR of
 111  110  one or more of the other flags in the following table, defined in the header
 112  111  <\fBsys/mman.h\fR>.
 113  112  .sp
 114  113  .ne 2
 115  114  .na
 116  115  \fB\fBPROT_READ\fR\fR
 117  116  .ad
 118  117  .RS 14n
↓ open down ↓ 39 lines elided ↑ open up ↑ 
 158  157  \fBPROT_READ\fR, \fBPROT_WRITE\fR, and the inclusive \fBOR\fR of
 159  158  \fBPROT_READ\fR and \fBPROT_WRITE\fR. On some platforms, the \fBPROT_WRITE\fR
 160  159  protection option is implemented as \fBPROT_READ|PROT_WRITE\fR and
 161  160  \fBPROT_EXEC\fR as \fBPROT_READ|PROT_EXEC\fR. The file descriptor \fIfildes\fR
 162  161  is opened with read permission, regardless of the protection options specified.
 163  162  If \fBPROT_WRITE\fR is specified, the application must have opened the file
 164  163  descriptor \fIfildes\fR with write permission unless \fBMAP_PRIVATE\fR is
 165  164  specified in the \fIflags\fR argument as described below.
 166  165  .sp
 167  166  .LP
 168      -The  \fIflags\fR argument provides other information about the handling of the
      167 +The \fIflags\fR argument provides other information about the handling of the
 169  168  mapped data. The value of \fIflags\fR is the bitwise inclusive \fBOR\fR of
 170  169  these options, defined in <\fBsys/mman.h\fR>:
 171  170  .sp
 172  171  .ne 2
 173  172  .na
 174  173  \fB\fBMAP_SHARED\fR\fR
 175  174  .ad
 176  175  .RS 17n
 177  176  Changes are shared.
 178  177  .RE
↓ open down ↓ 118 lines elided ↑ open up ↑ 
 297  296  below. A non-zero value of \fIaddr\fR is taken to be a suggestion of a process
 298  297  address near which the mapping should be placed. When the system selects a
 299  298  value for \fIpa\fR, it will never place a mapping at address 0, nor will it
 300  299  replace any extant mapping, nor map into areas considered part of the potential
 301  300  data or stack "segments".
 302  301  .sp
 303  302  .LP
 304  303  When \fBMAP_ALIGN\fR is set, the system is informed that the alignment of
 305  304  \fIpa\fR must be the same as \fIaddr\fR. The alignment value in \fIaddr\fR must
 306  305  be 0 or some power of two multiple of page size as returned by
 307      -\fBsysconf\fR(3C). If addr is 0, the system will choose a suitable  alignment.
      306 +\fBsysconf\fR(3C). If addr is 0, the system will choose a suitable alignment.
 308  307  .sp
 309  308  .LP
 310  309  The \fBMAP_NORESERVE\fR option specifies that no swap space be reserved for a
 311  310  mapping. Without this flag, the creation of a writable \fBMAP_PRIVATE\fR
 312  311  mapping reserves swap space equal to the size of the mapping; when the mapping
 313  312  is written into, the reserved space is employed to hold private copies of the
 314  313  data. A write into a \fBMAP_NORESERVE\fR mapping produces results which depend
 315      -on the current availability of swap  space in the system.  If space is
 316      -available, the write succeeds and a  private copy of the written page is
      314 +on the current availability of swap space in the system.  If space is
      315 +available, the write succeeds and a private copy of the written page is
 317  316  created; if space is not available, the write fails and a \fBSIGBUS\fR or
 318  317  \fBSIGSEGV\fR signal is delivered to the writing process.  \fBMAP_NORESERVE\fR
 319      -mappings are inherited across  \fBfork()\fR; at the time of the \fBfork()\fR,
      318 +mappings are inherited across \fBfork()\fR; at the time of the \fBfork()\fR,
 320  319  swap space is reserved in the child for all private pages that currently exist
 321  320  in the parent; thereafter the child's mapping behaves as described above.
 322  321  .sp
 323  322  .LP
 324  323  When \fBMAP_ANON\fR is set in \fIflags\fR, and \fIfildes\fR is set to -1,
 325  324  \fBmmap()\fR provides a direct path to return anonymous pages to the caller.
 326  325  This operation is equivalent to passing \fBmmap()\fR an open file descriptor on
 327  326  \fB/dev/zero\fR with \fBMAP_ANON\fR elided from the \fIflags\fR argument.
 328  327  .sp
 329  328  .LP
↓ open down ↓ 21 lines elided ↑ open up ↑ 
 351  350  mapping assignment should be limited to the first 32 bits (4 Gbytes) of the
 352  351  caller's address space.  This flag is accepted in both 32-bit and 64-bit
 353  352  process models, but does not alter the mapping strategy when used in a
 354  353  32-bit process model.
 355  354  .sp
 356  355  .LP
 357  356  The \fIoff\fR argument is constrained to be aligned and sized according to the
 358  357  value returned by \fBsysconf()\fR when passed \fB_SC_PAGESIZE\fR or
 359  358  \fB_SC_PAGE_SIZE\fR. When \fBMAP_FIXED\fR is specified, the \fIaddr\fR argument
 360  359  must also meet these constraints. The system performs mapping operations over
 361      -whole pages. Thus, while the  \fIlen\fR argument need not meet a size or
      360 +whole pages. Thus, while the \fIlen\fR argument need not meet a size or
 362  361  alignment constraint, the system will include, in any mapping operation, any
 363  362  partial page specified by the range [\fIpa, pa + len\fR).
 364  363  .sp
 365  364  .LP
 366  365  The system will always zero-fill any partial page at the end of an object.
 367  366  Further, the system will never write out any modified portions of the last page
 368  367  of an object which are beyond its end. References to whole pages following the
 369  368  end of an object will result in the delivery of a \fBSIGBUS\fR or \fBSIGSEGV\fR
 370  369  signal. \fBSIGBUS\fR signals may also be delivered on various file system
 371  370  conditions, including quota exceeded errors.
↓ open down ↓ 333 lines elided ↑ open up ↑ 
 705  704  .br
 706  705  .na
 707  706  \fBmap 4080 Kbytes: \fB0xffffffff7d000000\fR\fR
 708  707  .ad
 709  708  .sp .6
 710  709  .RS 4n
 711  710  4-Mbyte delta between starting addresses
 712  711  .RE
 713  712  
 714  713  .SH RETURN VALUES
 715      -.LP
 716  714  Upon successful completion, the \fBmmap()\fR function returns the address at
 717  715  which the mapping was placed (\fIpa\fR); otherwise, it returns a value of
 718  716  \fBMAP_FAILED\fR and sets \fBerrno\fR to indicate the error. The symbol
 719  717  \fBMAP_FAILED\fR is defined in the header <\fBsys/mman.h\fR>. No successful
 720  718  return from \fBmmap()\fR will return the value \fBMAP_FAILED\fR.
 721  719  .sp
 722  720  .LP
 723  721  If \fBmmap()\fR fails for reasons other than \fBEBADF\fR, \fBEINVAL\fR or
 724  722  \fBENOTSUP\fR, some of the mappings in the address range starting at \fIaddr\fR
 725  723  and continuing for \fIlen\fR bytes may have been unmapped.
 726  724  .SH ERRORS
 727      -.LP
 728  725  The \fBmmap()\fR function will fail if:
 729  726  .sp
 730  727  .ne 2
 731  728  .na
 732  729  \fB\fBEACCES\fR\fR
 733  730  .ad
 734  731  .RS 13n
 735  732  The \fIfildes\fR file descriptor is not open for read, regardless of the
 736  733  protection specified; or \fIfildes\fR is not open for write and
 737  734  \fBPROT_WRITE\fR was specified for a \fBMAP_SHARED\fR type mapping.
↓ open down ↓ 75 lines elided ↑ open up ↑ 
 813  810  The \fBMAP_FIXED\fR option was specified and the range [\fIaddr, addr + len\fR)
 814  811  exceeds that allowed for the address space of a process.
 815  812  .sp
 816  813  The \fBMAP_FIXED\fR option was \fInot\fR specified and there is insufficient
 817  814  room in the address space to effect the mapping.
 818  815  .sp
 819  816  The mapping could not be locked in memory, if required by \fBmlockall\fR(3C),
 820  817  because it would require more space than the system is able to supply.
 821  818  .sp
 822  819  The composite size of \fIlen\fR plus the lengths obtained from all previous
 823      -calls to \fBmmap()\fR exceeds \fBRLIMIT_VMEM\fR (see  \fBgetrlimit\fR(2)).
      820 +calls to \fBmmap()\fR exceeds \fBRLIMIT_VMEM\fR (see \fBgetrlimit\fR(2)).
 824  821  .RE
 825  822  
 826  823  .sp
 827  824  .ne 2
 828  825  .na
 829  826  \fB\fBENOTSUP\fR\fR
 830  827  .ad
 831  828  .RS 13n
 832  829  The system does not support the combination of accesses requested in the
 833  830  \fIprot\fR argument.
↓ open down ↓ 31 lines elided ↑ open up ↑ 
 865  862  .ne 2
 866  863  .na
 867  864  \fB\fBEAGAIN\fR\fR
 868  865  .ad
 869  866  .RS 10n
 870  867  The file to be mapped is already locked using advisory or mandatory record
 871  868  locking. See \fBfcntl\fR(2).
 872  869  .RE
 873  870  
 874  871  .SH USAGE
 875      -.LP
 876  872  Use of \fBmmap()\fR may reduce the amount of memory available to other memory
 877  873  allocation functions.
 878  874  .sp
 879  875  .LP
 880  876  \fBMAP_ALIGN\fR is useful to assure a properly aligned value of \fIpa\fR for
 881  877  subsequent use with \fBmemcntl\fR(2) and the \fBMC_HAT_ADVISE\fR command. This
 882  878  is best used for large, long-lived, and heavily referenced regions.
 883  879  \fBMAP_FIXED\fR and \fBMAP_ALIGN\fR are always mutually-exclusive.
 884  880  .sp
 885  881  .LP
↓ open down ↓ 24 lines elided ↑ open up ↑ 
 910  906  .nf
 911  907  fildes = open(\|.\|.\|.)
 912  908  lseek(fildes, offset, whence)
 913  909  read(fildes, buf, len)
 914  910  /* use data in buf */
 915  911  .fi
 916  912  .in -2
 917  913  
 918  914  .sp
 919  915  .LP
 920      -The following is a rewrite using  \fBmmap()\fR:
      916 +The following is a rewrite using \fBmmap()\fR:
 921  917  .sp
 922  918  .in +2
 923  919  .nf
 924  920  fildes = open(\|.\|.\|.)
 925  921  address = mmap((caddr_t) 0, len, (PROT_READ | PROT_WRITE),
 926  922            MAP_PRIVATE, fildes, offset)
 927  923  /* use data at address */
 928  924  .fi
 929  925  .in -2
 930  926  
 931  927  .SH ATTRIBUTES
 932      -.LP
 933  928  See \fBattributes\fR(5) for descriptions of the following attributes:
 934  929  .sp
 935  930  
 936  931  .sp
 937  932  .TS
 938  933  box;
 939  934  c | c
 940  935  l | l .
 941  936  ATTRIBUTE TYPE  ATTRIBUTE VALUE
 942  937  _
 943  938  Interface Stability     Standard
 944  939  _
 945  940  MT-Level        Async-Signal-Safe
 946  941  .TE
 947  942  
 948  943  .SH SEE ALSO
 949      -.LP
 950  944  \fBclose\fR(2), \fBexec\fR(2), \fBfcntl\fR(2), \fBfork\fR(2),
 951  945  \fBgetrlimit\fR(2), \fBmemcntl\fR(2), \fBmmapobj\fR(2), \fBmprotect\fR(2),
 952  946  \fBmunmap\fR(2), \fBshmat\fR(2), \fBlockf\fR(3C), \fBmlockall\fR(3C),
 953  947  \fBmsync\fR(3C), \fBplock\fR(3C), \fBsysconf\fR(3C), \fBattributes\fR(5),
 954  948  \fBlf64\fR(5), \fBstandards\fR(5), \fBnull\fR(7D), \fBzero\fR(7D)
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX