}
/**
- * Map a file into memory.
+ * Open a file and map it into memory.
*
* \param path Name of the regular file to map.
* \param open_mode Either \p O_RDONLY or \p O_RDWR.
- * \param obj On success, the mapping is returned here.
+ * \param map On success, the mapping is returned here.
+ * \param size size of the mapping.
+ * \param fd_ptr The file descriptor of the mapping.
+ *
+ * If \a fd_ptr is \p NULL, the file descriptor resulting from the underlying
+ * open call is closed after mmap(). Otherwise the file is kept open and the
+ * file descriptor is returned in \a fd_ptr.
*
* \return Positive on success, negative on errors. Possible errors include: \p
* E_FSTAT, any errors returned by para_open(), \p E_EMPTY, \p E_MMAP.