28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
46 .\" Copyright 2013 OmniTI Computer Consulting, Inc. All Rights Reserved.
47 .\" Copyright 2016 James S Blachly, MD. All Rights Reserved.
48 .\"
49 .TH MMAP 2 "August 29, 2016"
50 .SH NAME
51 mmap \- map pages of memory
52 .SH SYNOPSIS
53 .LP
54 .nf
55 #include <sys/mman.h>
56
57 \fBvoid *\fR\fBmmap\fR(\fBvoid *\fR\fIaddr\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIprot\fR, \fBint\fR \fIflags\fR,
58 \fBint\fR \fIfildes\fR, \fBoff_t\fR \fIoff\fR);
59 .fi
60
61 .SH DESCRIPTION
62 .LP
63 The \fBmmap()\fR function establishes a mapping between a process's address
64 space and a file or shared memory object. The format of the call is as follows:
65 .sp
66 .LP
67 \fIpa\fR = \fBmmap(\fR\fIaddr\fR\fB, \fR\fIlen\fR\fB, \fR\fIprot\fR\fB,
68 \fR\fIflags\fR\fB, \fR\fIfildes\fR\fB, \fR\fIoff\fR\fB);\fR
69 .sp
70 .LP
71 The \fBmmap()\fR function establishes a mapping between the address space of
72 the process at an address \fIpa\fR for \fIlen\fR bytes to the memory object
73 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
75 argument and values of \fIflags\fR, further described below. A successful
76 \fBmmap()\fR call returns \fIpa\fR as its result. The address range starting at
77 \fIpa\fR and continuing for \fIlen\fR bytes will be legitimate for the possible
78 (not necessarily current) address space of the process. The range of bytes
79 starting at \fIoff\fR and continuing for \fIlen\fR bytes will be legitimate for
80 the possible (not necessarily current) offsets in the file or shared memory
81 object represented by \fIfildes\fR.
82 .sp
695 .sp .6
696 .RS 4n
697 8-Mbyte delta between starting addresses
698 .RE
699
700 .sp
701 .ne 2
702 .na
703 \fBmap 4080 Kbytes: \fB0xffffffff7d400000\fR\fR
704 .ad
705 .br
706 .na
707 \fBmap 4080 Kbytes: \fB0xffffffff7d000000\fR\fR
708 .ad
709 .sp .6
710 .RS 4n
711 4-Mbyte delta between starting addresses
712 .RE
713
714 .SH RETURN VALUES
715 .LP
716 Upon successful completion, the \fBmmap()\fR function returns the address at
717 which the mapping was placed (\fIpa\fR); otherwise, it returns a value of
718 \fBMAP_FAILED\fR and sets \fBerrno\fR to indicate the error. The symbol
719 \fBMAP_FAILED\fR is defined in the header <\fBsys/mman.h\fR>. No successful
720 return from \fBmmap()\fR will return the value \fBMAP_FAILED\fR.
721 .sp
722 .LP
723 If \fBmmap()\fR fails for reasons other than \fBEBADF\fR, \fBEINVAL\fR or
724 \fBENOTSUP\fR, some of the mappings in the address range starting at \fIaddr\fR
725 and continuing for \fIlen\fR bytes may have been unmapped.
726 .SH ERRORS
727 .LP
728 The \fBmmap()\fR function will fail if:
729 .sp
730 .ne 2
731 .na
732 \fB\fBEACCES\fR\fR
733 .ad
734 .RS 13n
735 The \fIfildes\fR file descriptor is not open for read, regardless of the
736 protection specified; or \fIfildes\fR is not open for write and
737 \fBPROT_WRITE\fR was specified for a \fBMAP_SHARED\fR type mapping.
738 .RE
739
740 .sp
741 .ne 2
742 .na
743 \fB\fBEAGAIN\fR\fR
744 .ad
745 .RS 13n
746 The mapping could not be locked in memory.
747 .sp
855 .RS 13n
856 The file is a regular file and the value of \fIoff\fR plus \fIlen\fR exceeds
857 the offset maximum establish in the open file description associated with
858 \fIfildes\fR.
859 .RE
860
861 .sp
862 .LP
863 The \fBmmap()\fR function may fail if:
864 .sp
865 .ne 2
866 .na
867 \fB\fBEAGAIN\fR\fR
868 .ad
869 .RS 10n
870 The file to be mapped is already locked using advisory or mandatory record
871 locking. See \fBfcntl\fR(2).
872 .RE
873
874 .SH USAGE
875 .LP
876 Use of \fBmmap()\fR may reduce the amount of memory available to other memory
877 allocation functions.
878 .sp
879 .LP
880 \fBMAP_ALIGN\fR is useful to assure a properly aligned value of \fIpa\fR for
881 subsequent use with \fBmemcntl\fR(2) and the \fBMC_HAT_ADVISE\fR command. This
882 is best used for large, long-lived, and heavily referenced regions.
883 \fBMAP_FIXED\fR and \fBMAP_ALIGN\fR are always mutually-exclusive.
884 .sp
885 .LP
886 Use of \fBMAP_FIXED\fR may result in unspecified behavior in further use of
887 \fBbrk\fR(2), \fBsbrk\fR(2), \fBmalloc\fR(3C), and \fBshmat\fR(2). The use of
888 \fBMAP_FIXED\fR is discouraged, as it may prevent an implementation from making
889 the most effective use of resources.
890 .sp
891 .LP
892 The application must ensure correct synchronization when using \fBmmap()\fR in
893 conjunction with any other file access method, such as \fBread\fR(2) and
894 \fBwrite\fR(2), standard input/output, and \fBshmat\fR(2).
895 .sp
912 lseek(fildes, offset, whence)
913 read(fildes, buf, len)
914 /* use data in buf */
915 .fi
916 .in -2
917
918 .sp
919 .LP
920 The following is a rewrite using \fBmmap()\fR:
921 .sp
922 .in +2
923 .nf
924 fildes = open(\|.\|.\|.)
925 address = mmap((caddr_t) 0, len, (PROT_READ | PROT_WRITE),
926 MAP_PRIVATE, fildes, offset)
927 /* use data at address */
928 .fi
929 .in -2
930
931 .SH ATTRIBUTES
932 .LP
933 See \fBattributes\fR(5) for descriptions of the following attributes:
934 .sp
935
936 .sp
937 .TS
938 box;
939 c | c
940 l | l .
941 ATTRIBUTE TYPE ATTRIBUTE VALUE
942 _
943 Interface Stability Standard
944 _
945 MT-Level Async-Signal-Safe
946 .TE
947
948 .SH SEE ALSO
949 .LP
950 \fBclose\fR(2), \fBexec\fR(2), \fBfcntl\fR(2), \fBfork\fR(2),
951 \fBgetrlimit\fR(2), \fBmemcntl\fR(2), \fBmmapobj\fR(2), \fBmprotect\fR(2),
952 \fBmunmap\fR(2), \fBshmat\fR(2), \fBlockf\fR(3C), \fBmlockall\fR(3C),
953 \fBmsync\fR(3C), \fBplock\fR(3C), \fBsysconf\fR(3C), \fBattributes\fR(5),
954 \fBlf64\fR(5), \fBstandards\fR(5), \fBnull\fR(7D), \fBzero\fR(7D)
|
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
46 .\" Copyright 2013 OmniTI Computer Consulting, Inc. All Rights Reserved.
47 .\" Copyright 2016 James S Blachly, MD. All Rights Reserved.
48 .\" Copyright 2019 Joyent, Inc.
49 .\"
50 .TH MMAP 2 "Nov 19, 2019"
51 .SH NAME
52 mmap \- map pages of memory
53 .SH SYNOPSIS
54 .nf
55 #include <sys/mman.h>
56
57 \fBvoid *\fR\fBmmap\fR(\fBvoid *\fR\fIaddr\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIprot\fR, \fBint\fR \fIflags\fR,
58 \fBint\fR \fIfildes\fR, \fBoff_t\fR \fIoff\fR);
59 .fi
60
61 .SH DESCRIPTION
62 The \fBmmap()\fR function establishes a mapping between a process's address
63 space and a file or shared memory object. The format of the call is as follows:
64 .sp
65 .LP
66 \fIpa\fR = \fBmmap(\fR\fIaddr\fR\fB, \fR\fIlen\fR\fB, \fR\fIprot\fR\fB,
67 \fR\fIflags\fR\fB, \fR\fIfildes\fR\fB, \fR\fIoff\fR\fB);\fR
68 .sp
69 .LP
70 The \fBmmap()\fR function establishes a mapping between the address space of
71 the process at an address \fIpa\fR for \fIlen\fR bytes to the memory object
72 represented by the file descriptor \fIfildes\fR at offset \fIoff\fR for
73 \fIlen\fR bytes. The value of \fIpa\fR is a function of the \fIaddr\fR
74 argument and values of \fIflags\fR, further described below. A successful
75 \fBmmap()\fR call returns \fIpa\fR as its result. The address range starting at
76 \fIpa\fR and continuing for \fIlen\fR bytes will be legitimate for the possible
77 (not necessarily current) address space of the process. The range of bytes
78 starting at \fIoff\fR and continuing for \fIlen\fR bytes will be legitimate for
79 the possible (not necessarily current) offsets in the file or shared memory
80 object represented by \fIfildes\fR.
81 .sp
694 .sp .6
695 .RS 4n
696 8-Mbyte delta between starting addresses
697 .RE
698
699 .sp
700 .ne 2
701 .na
702 \fBmap 4080 Kbytes: \fB0xffffffff7d400000\fR\fR
703 .ad
704 .br
705 .na
706 \fBmap 4080 Kbytes: \fB0xffffffff7d000000\fR\fR
707 .ad
708 .sp .6
709 .RS 4n
710 4-Mbyte delta between starting addresses
711 .RE
712
713 .SH RETURN VALUES
714 Upon successful completion, the \fBmmap()\fR function returns the address at
715 which the mapping was placed (\fIpa\fR); otherwise, it returns a value of
716 \fBMAP_FAILED\fR and sets \fBerrno\fR to indicate the error. The symbol
717 \fBMAP_FAILED\fR is defined in the header <\fBsys/mman.h\fR>. No successful
718 return from \fBmmap()\fR will return the value \fBMAP_FAILED\fR.
719 .sp
720 .LP
721 If \fBmmap()\fR fails for reasons other than \fBEBADF\fR, \fBEINVAL\fR or
722 \fBENOTSUP\fR, some of the mappings in the address range starting at \fIaddr\fR
723 and continuing for \fIlen\fR bytes may have been unmapped.
724 .SH ERRORS
725 The \fBmmap()\fR function will fail if:
726 .sp
727 .ne 2
728 .na
729 \fB\fBEACCES\fR\fR
730 .ad
731 .RS 13n
732 The \fIfildes\fR file descriptor is not open for read, regardless of the
733 protection specified; or \fIfildes\fR is not open for write and
734 \fBPROT_WRITE\fR was specified for a \fBMAP_SHARED\fR type mapping.
735 .RE
736
737 .sp
738 .ne 2
739 .na
740 \fB\fBEAGAIN\fR\fR
741 .ad
742 .RS 13n
743 The mapping could not be locked in memory.
744 .sp
852 .RS 13n
853 The file is a regular file and the value of \fIoff\fR plus \fIlen\fR exceeds
854 the offset maximum establish in the open file description associated with
855 \fIfildes\fR.
856 .RE
857
858 .sp
859 .LP
860 The \fBmmap()\fR function may fail if:
861 .sp
862 .ne 2
863 .na
864 \fB\fBEAGAIN\fR\fR
865 .ad
866 .RS 10n
867 The file to be mapped is already locked using advisory or mandatory record
868 locking. See \fBfcntl\fR(2).
869 .RE
870
871 .SH USAGE
872 Use of \fBmmap()\fR may reduce the amount of memory available to other memory
873 allocation functions.
874 .sp
875 .LP
876 \fBMAP_ALIGN\fR is useful to assure a properly aligned value of \fIpa\fR for
877 subsequent use with \fBmemcntl\fR(2) and the \fBMC_HAT_ADVISE\fR command. This
878 is best used for large, long-lived, and heavily referenced regions.
879 \fBMAP_FIXED\fR and \fBMAP_ALIGN\fR are always mutually-exclusive.
880 .sp
881 .LP
882 Use of \fBMAP_FIXED\fR may result in unspecified behavior in further use of
883 \fBbrk\fR(2), \fBsbrk\fR(2), \fBmalloc\fR(3C), and \fBshmat\fR(2). The use of
884 \fBMAP_FIXED\fR is discouraged, as it may prevent an implementation from making
885 the most effective use of resources.
886 .sp
887 .LP
888 The application must ensure correct synchronization when using \fBmmap()\fR in
889 conjunction with any other file access method, such as \fBread\fR(2) and
890 \fBwrite\fR(2), standard input/output, and \fBshmat\fR(2).
891 .sp
908 lseek(fildes, offset, whence)
909 read(fildes, buf, len)
910 /* use data in buf */
911 .fi
912 .in -2
913
914 .sp
915 .LP
916 The following is a rewrite using \fBmmap()\fR:
917 .sp
918 .in +2
919 .nf
920 fildes = open(\|.\|.\|.)
921 address = mmap((caddr_t) 0, len, (PROT_READ | PROT_WRITE),
922 MAP_PRIVATE, fildes, offset)
923 /* use data at address */
924 .fi
925 .in -2
926
927 .SH ATTRIBUTES
928 See \fBattributes\fR(5) for descriptions of the following attributes:
929 .sp
930
931 .sp
932 .TS
933 box;
934 c | c
935 l | l .
936 ATTRIBUTE TYPE ATTRIBUTE VALUE
937 _
938 Interface Stability Standard
939 _
940 MT-Level Async-Signal-Safe
941 .TE
942
943 .SH SEE ALSO
944 \fBclose\fR(2), \fBexec\fR(2), \fBfcntl\fR(2), \fBfork\fR(2),
945 \fBgetrlimit\fR(2), \fBmemcntl\fR(2), \fBmmapobj\fR(2), \fBmprotect\fR(2),
946 \fBmunmap\fR(2), \fBshmat\fR(2), \fBlockf\fR(3C), \fBmlockall\fR(3C),
947 \fBmsync\fR(3C), \fBplock\fR(3C), \fBsysconf\fR(3C), \fBattributes\fR(5),
948 \fBlf64\fR(5), \fBstandards\fR(5), \fBnull\fR(7D), \fBzero\fR(7D)
|