.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "" "" "2023-05-26" "PMDK - " "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2021-2022, Intel Corporation
.SH NAME
.PP
\f[B]pmem2_source_pread_mcsafe\f[R](),
\f[B]pmem2_source_pwrite_mcsafe\f[R]() - read source contents or write
to the source in a safe manner
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <libpmem2.h>

struct pmem2_source;
int pmem2_source_pread_mcsafe(struct pmem2_source *src, void *buf, size_t size,
        size_t offset);
int pmem2_source_pwrite_mcsafe(struct pmem2_source *src, void *buf, size_t size,
        size_t offset);
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmem2_source_pread_mcsafe\f[R]() function reads \f[I]size\f[R]
bytes from the source \f[I]src\f[R] starting at offset \f[I]offset\f[R]
into the buffer \f[I]buf\f[R].
The \f[B]pmem2_source_pwrite_mcsafe\f[R]() function writes
\f[I]size\f[R] bytes from the buffer \f[I]buf\f[R] to the source
\f[I]src\f[R] starting at the offset \f[I]offset\f[R].
.PP
Above functions are capable of detecting bad blocks and handling the
\f[I]SIGBUS\f[R] signal thrown when accessing a bad block.
When a bad block is encountered, \f[B]pmem2_source_pread_mcsafe\f[R]()
and \f[B]pmem2_source_pwrite_mcsafe\f[R]() functions return
corresponding error.
A signal handler for \f[I]SIGBUS\f[R] signal is registered using
\f[B]sigaction\f[R](2) for the running time of those operations.
This capability is limited to POSIX systems.
.PP
For bad block detection and clearing, see
\f[B]pmem2_badblock_context_new\f[R](3),
\f[B]pmem2_badblock_next\f[R](3) and \f[B]pmem2_badblock_clear\f[R](3).
.SH RETURN VALUE
.PP
The \f[B]pmem2_source_pread_mcsafe\f[R]() and
\f[B]pmem2_source_pwrite_mcsafe\f[R]() functions return 0 on success or
a negative error code on failure.
.SH ERRORS
.PP
The \f[B]pmem2_source_pread_mcsafe\f[R]() and
\f[B]pmem2_source_pwrite_mcsafe\f[R]() can fail with the following
errors:
.IP \[bu] 2
\f[B]PMEM2_E_IO_FAIL\f[R] - a physical I/O error occurred during the
read/write operation, a possible bad block encountered.
.IP \[bu] 2
\f[B]PMEM2_E_LENGTH_OUT_OF_RANGE\f[R] - read/write operation size
\f[I]size\f[R] from offset \f[I]offset\f[R] goes beyond the file length.
.IP \[bu] 2
\f[B]PMEM2_E_SOURCE_TYPE_NOT_SUPPORTED\f[R] - read/write operation
doesn\[cq]t support provided source, only sources created with
\f[B]pmem2_source_from_fd\f[R](3) and
\f[B]pmem2_source_from_handle\f[R](3) are supported.
.PP
Those operations can also return all errors from the underlying
\f[B]pread\f[R](2), \f[B]pwrite\f[R](2), \f[B]sigaction\f[R](2)
functions on POSIX systems and \f[B]ReadFile\f[R](),
\f[B]WriteFile\f[R]() functions on Windows.
.SH SEE ALSO
.PP
\f[B]pread\f[R](2), \f[B]pwrite\f[R](2), \f[B]ReadFile\f[R](),
\f[B]WriteFile\f[R](), \f[B]pmem2_badblock_clear\f[R](3),
\f[B]pmem2_badblock_context_new\f[R](3),
\f[B]pmem2_badblock_next\f[R](3), \f[B]pmem2_source_from_fd\f[R](3),
\f[B]pmem2_source_from_handle\f[R](3), \f[B]libpmem2\f[R](7) and
\f[B]<https://pmem.io>\f[R]