logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

mmap.3p (23113B)


  1. '\" et
  2. .TH MMAP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. mmap
  12. \(em map pages of memory
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/mman.h>
  17. .P
  18. void *mmap(void *\fIaddr\fP, size_t \fIlen\fP, int \fIprot\fP, int \fIflags\fP,
  19. int \fIfildes\fP, off_t \fIoff\fP);
  20. .fi
  21. .SH DESCRIPTION
  22. The
  23. \fImmap\fR()
  24. function shall establish a mapping between an address space
  25. of a process and a memory object.
  26. .P
  27. The
  28. \fImmap\fR()
  29. function shall be supported for the following memory objects:
  30. .IP " *" 4
  31. Regular files
  32. .IP " *" 4
  33. Shared memory objects
  34. .IP " *" 4
  35. Typed memory objects
  36. .P
  37. Support for any other type of file is unspecified.
  38. .P
  39. The format of the call is as follows:
  40. .sp
  41. .RS 4
  42. .nf
  43. \fIpa\fR=\fImmap\fR(\fIaddr\fP, \fIlen\fP, \fIprot\fP, \fIflags\fP, \fIfildes\fP, \fIoff\fP);
  44. .fi
  45. .P
  46. .RE
  47. .P
  48. The
  49. \fImmap\fR()
  50. function shall establish a mapping between the address space of the
  51. process at an address
  52. .IR pa
  53. for
  54. .IR len
  55. bytes to the memory object represented by the file descriptor
  56. .IR fildes
  57. at offset
  58. .IR off
  59. for
  60. .IR len
  61. bytes. The value of
  62. .IR pa
  63. is an implementation-defined function of the parameter
  64. .IR addr
  65. and the values of
  66. .IR flags ,
  67. further described below. A successful
  68. \fImmap\fR()
  69. call shall return
  70. .IR pa
  71. as its result. The address range starting at
  72. .IR pa
  73. and continuing for
  74. .IR len
  75. bytes shall be legitimate for the possible (not necessarily current)
  76. address space of the process. The range of bytes starting at
  77. .IR off
  78. and continuing for
  79. .IR len
  80. bytes shall be legitimate for the possible (not necessarily current)
  81. offsets in the memory object represented by
  82. .IR fildes .
  83. .P
  84. If
  85. .IR fildes
  86. represents a typed memory object opened with either the
  87. POSIX_TYPED_MEM_ALLOCATE flag or the POSIX_TYPED_MEM_ALLOCATE_CONTIG
  88. flag, the memory object to be mapped
  89. shall be that portion of the typed memory object allocated by the
  90. implementation as specified below. In this case, if
  91. .IR off
  92. is non-zero, the behavior of
  93. \fImmap\fR()
  94. is undefined. If
  95. .IR fildes
  96. refers to a valid typed memory object that is not accessible from the
  97. calling process,
  98. \fImmap\fR()
  99. shall fail.
  100. .P
  101. The mapping established by
  102. \fImmap\fR()
  103. shall replace any previous mappings for those whole pages containing
  104. any part of the address space of the process starting at
  105. .IR pa
  106. and continuing for
  107. .IR len
  108. bytes.
  109. .P
  110. If the size of the mapped file changes after the call to
  111. \fImmap\fR()
  112. as a result of some other operation on the mapped file, the effect of
  113. references to portions of the mapped region that correspond to added or
  114. removed portions of the file is unspecified.
  115. .P
  116. If
  117. .IR len
  118. is zero,
  119. \fImmap\fR()
  120. shall fail and no mapping shall be established.
  121. .P
  122. The parameter
  123. .IR prot
  124. determines whether read, write, execute, or some combination of
  125. accesses are permitted to the data being mapped. The
  126. .IR prot
  127. shall be either PROT_NONE
  128. or the bitwise-inclusive OR of one or more of the other flags in
  129. the following table, defined in the
  130. .IR <sys/mman.h>
  131. header.
  132. .TS
  133. center box tab(!);
  134. cB | cB
  135. lw(1.5i) | lw(2i).
  136. Symbolic Constant!Description
  137. _
  138. PROT_READ!Data can be read.
  139. PROT_WRITE!Data can be written.
  140. PROT_EXEC!Data can be executed.
  141. PROT_NONE!Data cannot be accessed.
  142. .TE
  143. .P
  144. If an implementation cannot support the combination of access types
  145. specified by
  146. .IR prot ,
  147. the call to
  148. \fImmap\fR()
  149. shall fail.
  150. .P
  151. An implementation may permit accesses other than those specified by
  152. .IR prot ;
  153. however, the implementation shall not permit a write to succeed
  154. where PROT_WRITE has not been set and shall not permit any access where
  155. PROT_NONE alone has been set. The implementation shall support at least
  156. the following values of
  157. .IR prot :
  158. PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-inclusive OR of
  159. PROT_READ and PROT_WRITE. The file descriptor
  160. .IR fildes
  161. shall have been opened with read permission, regardless of the
  162. protection options specified. If PROT_WRITE is specified, the
  163. application shall ensure that it has opened the file descriptor
  164. .IR fildes
  165. with write permission unless MAP_PRIVATE is specified in the
  166. .IR flags
  167. parameter as described below.
  168. .P
  169. The parameter
  170. .IR flags
  171. provides other information about the handling of the mapped data.
  172. The value of
  173. .IR flags
  174. is the bitwise-inclusive OR of these options, defined in
  175. .IR <sys/mman.h> :
  176. .TS
  177. center box tab(!);
  178. cB | cB
  179. lw(1.5i) | lw(2i).
  180. Symbolic Constant!Description
  181. _
  182. MAP_SHARED!Changes are shared.
  183. MAP_PRIVATE!Changes are private.
  184. MAP_FIXED!Interpret \fIaddr\fP exactly.
  185. .TE
  186. .P
  187. It is implementation-defined whether MAP_FIXED shall be supported.
  188. MAP_FIXED shall be supported on XSI-conformant systems.
  189. .P
  190. MAP_SHARED and MAP_PRIVATE describe the disposition of write references
  191. to the memory object. If MAP_SHARED is specified, write references
  192. shall change the underlying object. If MAP_PRIVATE is specified,
  193. modifications to the mapped data by the calling process shall be visible
  194. only to the calling process and shall not change the underlying object.
  195. It is unspecified whether modifications to the underlying object done
  196. after the MAP_PRIVATE mapping is established are visible through the
  197. MAP_PRIVATE mapping. Either MAP_SHARED or MAP_PRIVATE can be
  198. specified, but not both. The mapping type is retained across
  199. \fIfork\fR().
  200. .P
  201. The state of synchronization objects such as mutexes, semaphores,
  202. barriers, and conditional variables placed in shared memory mapped with
  203. MAP_SHARED becomes undefined when the last region in any process
  204. containing the synchronization object is unmapped.
  205. .P
  206. When
  207. .IR fildes
  208. represents a typed memory object opened with either the
  209. POSIX_TYPED_MEM_ALLOCATE flag or the
  210. POSIX_TYPED_MEM_ALLOCATE_CONTIG flag,
  211. \fImmap\fR()
  212. shall, if there are enough resources available, map
  213. .IR len
  214. bytes allocated from the corresponding typed memory object which were
  215. not previously allocated to any process in any processor that may
  216. access that typed memory object. If there are not enough resources
  217. available, the function shall fail. If
  218. .IR fildes
  219. represents a typed memory object opened with the
  220. POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, these allocated bytes shall be
  221. contiguous within the typed memory object. If
  222. .IR fildes
  223. represents a typed memory object opened with the
  224. POSIX_TYPED_MEM_ALLOCATE flag, these allocated bytes may be composed of
  225. non-contiguous fragments within the typed memory object. If
  226. .IR fildes
  227. represents a typed memory object opened with neither the
  228. POSIX_TYPED_MEM_ALLOCATE_CONTIG flag nor the POSIX_TYPED_MEM_ALLOCATE
  229. flag,
  230. .IR len
  231. bytes starting at offset
  232. .IR off
  233. within the typed memory object are mapped, exactly as when mapping a
  234. file or shared memory object. In this case, if two processes map an
  235. area of typed memory using the same
  236. .IR off
  237. and
  238. .IR len
  239. values and using file descriptors that refer to the same memory pool
  240. (either from the same port or from a different port), both processes
  241. shall map the same region of storage.
  242. .P
  243. When MAP_FIXED is set in the
  244. .IR flags
  245. argument, the implementation is informed that the value of
  246. .IR pa
  247. shall be
  248. .IR addr ,
  249. exactly. If MAP_FIXED is set,
  250. \fImmap\fR()
  251. may return MAP_FAILED and set
  252. .IR errno
  253. to
  254. .BR [EINVAL] .
  255. If a MAP_FIXED request is successful, then any previous mappings
  256. or memory locks
  257. for those whole pages containing any part of the address range
  258. [\fIpa\fP,\fIpa\fP+\fIlen\fR) shall be removed, as if by an
  259. appropriate call to
  260. \fImunmap\fR(),
  261. before the new mapping is established.
  262. .P
  263. When MAP_FIXED is not set, the implementation uses
  264. .IR addr
  265. in an implementation-defined manner to arrive at
  266. .IR pa .
  267. The
  268. .IR pa
  269. so chosen shall be an area of the address space that the implementation
  270. deems suitable for a mapping of
  271. .IR len
  272. bytes to the file. All implementations interpret an
  273. .IR addr
  274. value of 0 as granting the implementation complete freedom in selecting
  275. .IR pa ,
  276. subject to constraints described below. A non-zero value of
  277. .IR addr
  278. is taken to be a suggestion of a process address near which the mapping
  279. should be placed. When the implementation selects a value for
  280. .IR pa ,
  281. it never places a mapping at address 0, nor does it replace any extant
  282. mapping.
  283. .P
  284. If MAP_FIXED is specified and
  285. .IR addr
  286. is non-zero, it shall have the same remainder as the
  287. .IR off
  288. parameter, modulo the page size as returned by
  289. \fIsysconf\fR()
  290. when passed _SC_PAGESIZE or _SC_PAGE_SIZE. The implementation may
  291. require that off is a multiple of the page size. If MAP_FIXED is
  292. specified, the implementation may require that
  293. .IR addr
  294. is a multiple of the page size. The system performs mapping operations
  295. over whole pages. Thus, while the parameter
  296. .IR len
  297. need not meet a size or alignment constraint, the system shall include,
  298. in any mapping operation, any partial page specified by the address
  299. range starting at
  300. .IR pa
  301. and continuing for
  302. .IR len
  303. bytes.
  304. .P
  305. The system shall always zero-fill any partial page at the end of an
  306. object. Further, the system shall never write out any modified
  307. portions of the last page of an object which are beyond its end.
  308. References within the address range starting at
  309. .IR pa
  310. and continuing for
  311. .IR len
  312. bytes to whole pages following the end of an object shall result in
  313. delivery of a SIGBUS signal.
  314. .P
  315. An implementation may generate SIGBUS signals when a reference would
  316. cause an error in the mapped object, such as out-of-space condition.
  317. .P
  318. The
  319. \fImmap\fR()
  320. function shall add an extra reference to the file associated with the
  321. file descriptor
  322. .IR fildes
  323. which is not removed by a subsequent
  324. \fIclose\fR()
  325. on that file descriptor. This reference shall be removed when there are
  326. no more mappings to the file.
  327. .P
  328. The last data access timestamp of the mapped file may be marked for
  329. update at any time between the
  330. \fImmap\fR()
  331. call and the corresponding
  332. \fImunmap\fR()
  333. call. The initial read or write reference to a mapped region shall cause
  334. the file's last data access timestamp to be marked for update if it has
  335. not already been marked for update.
  336. .P
  337. The last data modification and last file status change timestamps
  338. of a file that is mapped with MAP_SHARED and PROT_WRITE shall be
  339. marked
  340. for update at some point in the interval between a write reference to
  341. the mapped region and the next call to
  342. \fImsync\fR()
  343. with MS_ASYNC or MS_SYNC for that portion of the file by any process.
  344. If there is no such call and if the underlying file is modified
  345. as a result of a write reference, then these timestamps shall be marked
  346. for update at some time after the write reference.
  347. .P
  348. There may be implementation-defined limits on the number of memory
  349. regions that can be mapped (per process or per system).
  350. .P
  351. If such a limit is imposed, whether the number of memory regions that
  352. can be mapped by a process is decreased by the use of
  353. \fIshmat\fR()
  354. is implementation-defined.
  355. .P
  356. If
  357. \fImmap\fR()
  358. fails for reasons other than
  359. .BR [EBADF] ,
  360. .BR [EINVAL] ,
  361. or
  362. .BR [ENOTSUP] ,
  363. some of the mappings in the address range starting at
  364. .IR addr
  365. and continuing for
  366. .IR len
  367. bytes may have been unmapped.
  368. .SH "RETURN VALUE"
  369. Upon successful completion, the
  370. \fImmap\fR()
  371. function shall return the address at which the mapping was placed (\c
  372. .IR pa );
  373. otherwise, it shall return a value of MAP_FAILED and set
  374. .IR errno
  375. to indicate the error. The symbol MAP_FAILED is defined in the
  376. .IR <sys/mman.h>
  377. header. No successful return from
  378. \fImmap\fR()
  379. shall return the value MAP_FAILED.
  380. .SH ERRORS
  381. The
  382. \fImmap\fR()
  383. function shall fail if:
  384. .TP
  385. .BR EACCES
  386. The
  387. .IR fildes
  388. argument is not open for read, regardless of the protection specified,
  389. or
  390. .IR fildes
  391. is not open for write and PROT_WRITE was specified for a MAP_SHARED
  392. type mapping.
  393. .TP
  394. .BR EAGAIN
  395. The mapping could not be locked in memory, if required by
  396. \fImlockall\fR(),
  397. due to a lack of resources.
  398. .TP
  399. .BR EBADF
  400. The
  401. .IR fildes
  402. argument is not a valid open file descriptor.
  403. .TP
  404. .BR EINVAL
  405. The value of
  406. .IR len
  407. is zero.
  408. .TP
  409. .BR EINVAL
  410. The value of
  411. .IR flags
  412. is invalid (neither MAP_PRIVATE nor MAP_SHARED is set).
  413. .TP
  414. .BR EMFILE
  415. The number of mapped regions would exceed an implementation-defined
  416. limit (per process or per system).
  417. .TP
  418. .BR ENODEV
  419. The
  420. .IR fildes
  421. argument refers to a file whose type is not supported by
  422. \fImmap\fR().
  423. .TP
  424. .BR ENOMEM
  425. MAP_FIXED was specified, and the range
  426. [\fIaddr\fP,\fIaddr\fP+\fIlen\fR) exceeds that allowed for the
  427. address space of a process; or, if MAP_FIXED was not specified and
  428. there is insufficient room in the address space to effect the mapping.
  429. .TP
  430. .BR ENOMEM
  431. The mapping could not be locked in memory, if required by
  432. \fImlockall\fR(),
  433. because it would require more space than the system is able to supply.
  434. .TP
  435. .BR ENOMEM
  436. Not enough unallocated memory resources remain in the typed memory
  437. object designated by
  438. .IR fildes
  439. to allocate
  440. .IR len
  441. bytes.
  442. .TP
  443. .BR ENOTSUP
  444. MAP_FIXED or MAP_PRIVATE was specified in the
  445. .IR flags
  446. argument and the implementation does not support this functionality.
  447. .RS 12
  448. .P
  449. The implementation does not support the combination of accesses
  450. requested in the
  451. .IR prot
  452. argument.
  453. .RE
  454. .TP
  455. .BR ENXIO
  456. Addresses in the range [\fIoff\fP,\fIoff\fP+\fIlen\fR) are invalid
  457. for the object specified by
  458. .IR fildes .
  459. .TP
  460. .BR ENXIO
  461. MAP_FIXED was specified in
  462. .IR flags
  463. and the combination of
  464. .IR addr ,
  465. .IR len ,
  466. and
  467. .IR off
  468. is invalid for the object specified by
  469. .IR fildes .
  470. .TP
  471. .BR ENXIO
  472. The
  473. .IR fildes
  474. argument refers to a typed memory object that is not accessible from
  475. the calling process.
  476. .TP
  477. .BR EOVERFLOW
  478. The file is a regular file and the value of
  479. .IR off
  480. plus
  481. .IR len
  482. exceeds the offset maximum established in the open file description
  483. associated with
  484. .IR fildes .
  485. .br
  486. .P
  487. The
  488. \fImmap\fR()
  489. function may fail if:
  490. .TP
  491. .BR EINVAL
  492. The
  493. .IR addr
  494. argument (if MAP_FIXED was specified) or
  495. .IR off
  496. is not a multiple of the page size as returned by
  497. \fIsysconf\fR(),
  498. or is considered invalid by the implementation.
  499. .LP
  500. .IR "The following sections are informative."
  501. .SH EXAMPLES
  502. None.
  503. .SH "APPLICATION USAGE"
  504. Use of
  505. \fImmap\fR()
  506. may reduce the amount of memory available to other memory allocation
  507. functions.
  508. .P
  509. Use of MAP_FIXED may result in unspecified behavior in further use of
  510. \fImalloc\fR()
  511. and
  512. \fIshmat\fR().
  513. The use of MAP_FIXED is discouraged, as it may prevent an
  514. implementation from making the most effective use of resources. Most
  515. implementations require that
  516. .IR off
  517. and
  518. .IR addr
  519. are multiples of the page size as returned by
  520. \fIsysconf\fR().
  521. .P
  522. The application must ensure correct synchronization when using
  523. \fImmap\fR()
  524. in conjunction with any other file access method, such as
  525. \fIread\fR()
  526. and
  527. \fIwrite\fR(),
  528. standard input/output, and
  529. \fIshmat\fR().
  530. .P
  531. The
  532. \fImmap\fR()
  533. function allows access to resources via address space manipulations,
  534. instead of
  535. \fIread\fR()/\c
  536. \fIwrite\fR().
  537. Once a file is mapped, all a process has to do to access it is use the
  538. data at the address to which the file was mapped. So, using
  539. pseudo-code to illustrate the way in which an existing program might be
  540. changed to use
  541. \fImmap\fR(),
  542. the following:
  543. .sp
  544. .RS 4
  545. .nf
  546. fildes = open(...)
  547. lseek(fildes, some_offset)
  548. read(fildes, buf, len)
  549. /* Use data in buf. */
  550. .fi
  551. .P
  552. .RE
  553. .P
  554. becomes:
  555. .sp
  556. .RS 4
  557. .nf
  558. fildes = open(...)
  559. address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset)
  560. /* Use data at address. */
  561. .fi
  562. .P
  563. .RE
  564. .SH RATIONALE
  565. After considering several other alternatives, it was decided to adopt
  566. the
  567. \fImmap\fR()
  568. definition found in SVR4 for mapping memory objects into process
  569. address spaces. The SVR4 definition is minimal, in that it describes
  570. only what has been built, and what appears to be necessary for a
  571. general and portable mapping facility.
  572. .P
  573. Note that while
  574. \fImmap\fR()
  575. was first designed for mapping files, it is actually a general-purpose
  576. mapping facility. It can be used to map any appropriate object, such
  577. as memory, files, devices, and so on, into the address space of a
  578. process.
  579. .P
  580. When a mapping is established, it is possible that the implementation
  581. may need to map more than is requested into the address space of the
  582. process because of hardware requirements. An application, however,
  583. cannot count on this behavior. Implementations that do not use a paged
  584. architecture may simply allocate a common memory region and return the
  585. address of it; such implementations probably do not allocate any more
  586. than is necessary. References past the end of the requested area are
  587. unspecified.
  588. .P
  589. If an application requests a mapping that overlaps existing mappings
  590. in the process, it might be desirable that an implementation detect
  591. this and inform the application. However, if the program specifies a
  592. fixed address mapping (which requires some implementation knowledge to
  593. determine a suitable address, if the function is supported at all),
  594. then the program is presumed to be successfully managing its own
  595. address space and should be trusted when it asks to map over existing
  596. data structures. Furthermore, it is also desirable to make as few
  597. system calls as possible, and it might be considered onerous to
  598. require an
  599. \fImunmap\fR()
  600. before an
  601. \fImmap\fR()
  602. to the same address range. This volume of POSIX.1\(hy2017 specifies that the new mapping
  603. replaces any existing mappings (implying an automatic
  604. \fImunmap\fR()
  605. on the address range), following existing practice in this regard.
  606. The standard developers also considered whether there should be a way
  607. for new mappings to overlay existing mappings, but found no existing
  608. practice for this.
  609. .P
  610. It is not expected that all hardware implementations are able to
  611. support all combinations of permissions at all addresses.
  612. Implementations are required to disallow write
  613. access to mappings without write permission and to disallow access to
  614. mappings without any access permission. Other than these restrictions,
  615. implementations may allow access types other than those requested by
  616. the application. For example, if the application requests only
  617. PROT_WRITE, the implementation may also allow read access. A call to
  618. \fImmap\fR()
  619. fails if the implementation cannot support allowing all the access
  620. requested by the application. For example, some implementations
  621. cannot support a request for both write access and execute access
  622. simultaneously. All implementations must support requests for no access,
  623. read access, write access, and both read and write access. Strictly
  624. conforming code must only rely on the required checks. These restrictions
  625. allow for portability across a wide range of hardware.
  626. .P
  627. The MAP_FIXED address treatment is likely to fail for non-page-aligned
  628. values and for certain architecture-dependent address ranges.
  629. Conforming implementations cannot count on being able to choose address
  630. values for MAP_FIXED without utilizing non-portable,
  631. implementation-defined knowledge. Nonetheless, MAP_FIXED is provided
  632. as a standard interface conforming to existing practice for utilizing
  633. such knowledge when it is available.
  634. .P
  635. Similarly, in order to allow implementations that do not support
  636. virtual addresses, support for directly specifying any mapping
  637. addresses via MAP_FIXED is not required and thus a conforming
  638. application may not count on it.
  639. .P
  640. The MAP_PRIVATE
  641. function can be implemented efficiently when memory protection hardware
  642. is available. When such hardware is not available, implementations can
  643. implement such ``mappings''
  644. by simply making a real copy of the relevant data into process private
  645. memory, though this tends to behave similarly to
  646. \fIread\fR().
  647. .P
  648. The function has been defined to allow for many different models of
  649. using shared memory. However, all uses are not equally portable across
  650. all machine architectures. In particular, the
  651. \fImmap\fR()
  652. function allows the system as well as the application to specify the
  653. address at which to map a specific region of a memory object. The most
  654. portable way to use the function is always to let the system choose
  655. the address, specifying NULL as the value for the argument
  656. .IR addr
  657. and not to specify MAP_FIXED.
  658. .P
  659. If it is intended that a particular region of a memory object be mapped
  660. at the same address in a group of processes (on machines where this is
  661. even possible), then MAP_FIXED can be used to pass in the desired
  662. mapping address. The system can still be used to choose the desired
  663. address if the first such mapping is made without specifying MAP_FIXED,
  664. and then the resulting mapping address can be passed to subsequent
  665. processes for them to pass in via MAP_FIXED. The availability of a
  666. specific address range cannot be guaranteed, in general.
  667. .P
  668. The
  669. \fImmap\fR()
  670. function can be used to map a region of memory that is larger than the
  671. current size of the object. Memory access within the mapping but
  672. beyond the current end of the underlying objects may result in SIGBUS
  673. signals being sent to the process. The reason for this is that the
  674. size of the object can be manipulated by other processes and can change
  675. at any moment. The implementation should tell the application that a
  676. memory reference is outside the object where this can be detected;
  677. otherwise, written data may be lost and read data may not reflect
  678. actual data in the object.
  679. .P
  680. Note that references beyond the end of the object do not extend the
  681. object as the new end cannot be determined precisely by most virtual
  682. memory hardware. Instead, the size can be directly manipulated by
  683. \fIftruncate\fR().
  684. .P
  685. Process memory locking does apply to shared memory regions, and the
  686. MCL_FUTURE argument to
  687. \fImlockall\fR()
  688. can be relied upon to cause new shared memory regions to be
  689. automatically locked.
  690. .P
  691. Existing implementations of
  692. \fImmap\fR()
  693. return the value \-1 when unsuccessful. Since the casting of this
  694. value to type
  695. .BR "void *"
  696. cannot be guaranteed by the ISO\ C standard to be distinct from a successful
  697. value, this volume of POSIX.1\(hy2017 defines the symbol MAP_FAILED,
  698. which a conforming implementation does not return as the result of a
  699. successful call.
  700. .SH "FUTURE DIRECTIONS"
  701. None.
  702. .SH "SEE ALSO"
  703. .IR "\fIexec\fR\^",
  704. .IR "\fIfcntl\fR\^(\|)",
  705. .IR "\fIfork\fR\^(\|)",
  706. .IR "\fIlockf\fR\^(\|)",
  707. .IR "\fImsync\fR\^(\|)",
  708. .IR "\fImunmap\fR\^(\|)",
  709. .IR "\fImprotect\fR\^(\|)",
  710. .IR "\fIposix_typed_mem_open\fR\^(\|)",
  711. .IR "\fIshmat\fR\^(\|)",
  712. .IR "\fIsysconf\fR\^(\|)"
  713. .P
  714. The Base Definitions volume of POSIX.1\(hy2017,
  715. .IR "\fB<sys_mman.h>\fP"
  716. .\"
  717. .SH COPYRIGHT
  718. Portions of this text are reprinted and reproduced in electronic form
  719. from IEEE Std 1003.1-2017, Standard for Information Technology
  720. -- Portable Operating System Interface (POSIX), The Open Group Base
  721. Specifications Issue 7, 2018 Edition,
  722. Copyright (C) 2018 by the Institute of
  723. Electrical and Electronics Engineers, Inc and The Open Group.
  724. In the event of any discrepancy between this version and the original IEEE and
  725. The Open Group Standard, the original IEEE and The Open Group Standard
  726. is the referee document. The original Standard can be obtained online at
  727. http://www.opengroup.org/unix/online.html .
  728. .PP
  729. Any typographical or formatting errors that appear
  730. in this page are most likely
  731. to have been introduced during the conversion of the source files to
  732. man page format. To report such errors, see
  733. https://www.kernel.org/doc/man-pages/reporting_bugs.html .