.\"
.\" Copyright (C) 2014 - 2018 Intel Corporation.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are met:
.\" 1. Redistributions of source code must retain the above copyright notice(s),
.\"    this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright notice(s),
.\"    this list of conditions and the following disclaimer in the documentation
.\"    and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY EXPRESS
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO
.\" EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.TH "MEMKIND_PMEM" 3 "2015-04-21" "Intel Corporation" "MEMKIND_PMEM" \" -*- nroff -*-
.SH "NAME"
memkind_pmem.h \- file-backed memory memkind operations.
.br
Note: This is EXPERIMENTAL API. The functionality and the header file itself can be changed (including non-backward compatible changes) or removed.
.SH "SYNOPSIS"
.nf
.B #include <memkind/internal/memkind_pmem.h>
.sp
.B Link with -lmemkind
.sp
.BI "int memkind_pmem_create(struct memkind " "*kind" ", struct memkind_ops " "*ops" ", const char " "*name" );
.br
.BI "int memkind_pmem_destroy(struct memkind " "*kind" );
.br
.BI "void *memkind_pmem_mmap(struct memkind " "*kind" ", void " "*addr" ", size_t " "size" );
.br
.BI "int memkind_pmem_get_mmap_flags(struct memkind " "*kind" ", int " "*flags" );
.br
.SH DESCRIPTION
.PP
The pmem memory memkind operations enable memory kinds built on memory-mapped
files.  These support traditional
.B volatile
memory allocation in a fashion similar to
.BR libvmem (3)
library.  It uses the
.BR mmap (2)
system call to create a pool of volatile memory.  Such memory may have different
attributes, depending on the file system containing the memory-mapped files.
(See also
.IR http://pmem.io/pmdk/libvmem ).
.PP
The pmem memkinds are most useful when used with
.I Direct Access
storage (DAX), which is memory-addressable persistent storage
that supports load/store access without being paged via the system page cache.
A Persistent Memory-aware file system is typically used to provide this
type of access.
.PP
The most convenient way to create pmem memkinds is to use
.BR memkind_create_pmem ()
(see
.BR memkind (3)).
.PP
.BR memkind_pmem_create ()
is an implementation of the memkind "create" operation for file-backed memory
kinds.  This allocates a space for some pmem-specific metadata, then calls
.BR memkind_arena_create ()
(see
.BR memkind_arena (3))
.PP
.BR memkind_pmem_destroy ()
is an implementation of the memkind "destroy" operation for file-backed memory
kinds.  This releases all of the resources
allocated by
.BR memkind_pmem_create ()
and allows the file system space to be reclaimed.
.PP
.BR memkind_pmem_mmap ()
allocates the file system space for a block of
.I size
bytes in the memory-mapped file associated with given kind.
The
.I addr
hint is ignored.  The return value is the address of mapped memory region or
.B MAP_FAILED
in the case of an error.
.PP
.BR memkind_pmem_get_mmap_flags ()
sets
.I flags
to
.BR "MAP_SHARED" .
See
.BR mmap (2)
for more information about these flags.
.TP
.B MEMKIND_PMEM_CHUNK_SIZE
The size of the PMEM chunk size.
.SH "COPYRIGHT"
Copyright (C) 2015 - 2018 Intel Corporation. All rights reserved.
.SH "SEE ALSO"
.BR memkind (3),
.BR memkind_arena (3),
.BR memkind_default (3),
.BR memkind_hbw (3),
.BR memkind_hugetlb (3),
.BR libvmem (3),
.BR jemalloc (3),
.BR mbind (2),
.BR mmap (2)