.TH LC_MMAPFILE 3 2023-07-24 "LIBRECAST" "Librecast Programmer's Manual"
.SH NAME
lc_mmapfile \- map or unmap files or devices into memory
.SH LIBRARY
Librecast library
.RI ( liblibrecast ", " \-llibrecast )
.SH SYNOPSIS
.nf
.B #include <librecast/sync.h>
.PP
.BI "void *lc_mmapfile(const char " *pathname ", size_t " *len ", int " prot ", int " flags ",
.BI "                  off_t " offset ", struct stat " *sb ");"
.fi
.PP
Compile and link with \fI\-llibrecast\fP.
.SH DESCRIPTION
The
.BR lc_mmapfile ()
function is a convenience wrapper for
.BR mmap (2)
which
.BR open (2)s
and maps a file in a single call. See
.BR mmap (2)
for a full description.
.PP
If
.IR prot
has the
.BR PROT_WRITE
flag set,
.IR pathname
is
.BR open (2)'ed
with the
.BR O_RDWR
and
.BR O_CREAT
flags set (the file is created and opened read-write), otherwise it is opened
.BR O_RDONLY .
The mode for the created file can be set by setting
.IR st_mode
in
.IR sb
when calling
.BR lc_mmapfile ().
.PP
If
.IR len
points to a value greater than zero,
.BR ftruncate (2)
is called to truncate the file to the specified length. Otherwise, the variable
.IR len
points to is set to the size of the file.
.PP
When done, the file can be unmapped and the memory freed by calling
.BR munmap (3).
.PP
.SH RETURN VALUE
On success,
.BR lc_mmapfile ()
returns a pointer to the mapped area. On error, the value
.BR MAP_FAILED
(that is,
.IR (void *) -1
) is returned, and
.IR errno
is set to indicate the error.
.SH ERRORS
.TP
.BR ENODATA
File is zero length.
.PP
See also
.BR open (2),
.BR mmap (2),
.BR fstat (2),
and
.BR ftruncate (2).
.PP
.SH SEE ALSO
.BR mmap (2),
.BR msync (2),
.BR munmap (2),
.BR open (2),
.BR fstat (2),
.BR ftruncate (2)