.\" Automatically generated by Pandoc 2.0.6
.\"
.TH "PMEM2_SOURCE_PREAD_MCSAFE" "3" "2022-08-25" "PMDK - pmem2 API version 1.0" "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[](),
\f[B]pmem2_source_pwrite_mcsafe\f[]() \- 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[]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmem2_source_pread_mcsafe\f[]() function reads \f[I]size\f[]
bytes from the source \f[I]src\f[] starting at offset \f[I]offset\f[]
into the buffer \f[I]buf\f[].
The \f[B]pmem2_source_pwrite_mcsafe\f[]() function writes \f[I]size\f[]
bytes from the buffer \f[I]buf\f[] to the source \f[I]src\f[] starting
at the offset \f[I]offset\f[].
.PP
Above functions are capable of detecting bad blocks and handling the
\f[I]SIGBUS\f[] signal thrown when accessing a bad block.
When a bad block is encountered, \f[B]pmem2_source_pread_mcsafe\f[]()
and \f[B]pmem2_source_pwrite_mcsafe\f[]() functions return corresponding
error.
A signal handler for \f[I]SIGBUS\f[] signal is registered using
\f[B]sigaction\f[](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[](3), \f[B]pmem2_badblock_next\f[](3)
and \f[B]pmem2_badblock_clear\f[](3).
.SH RETURN VALUE
.PP
The \f[B]pmem2_source_pread_mcsafe\f[]() and
\f[B]pmem2_source_pwrite_mcsafe\f[]() functions return 0 on success or a
negative error code on failure.
.SH ERRORS
.PP
The \f[B]pmem2_source_pread_mcsafe\f[]() and
\f[B]pmem2_source_pwrite_mcsafe\f[]() can fail with the following
errors:
.IP \[bu] 2
\f[B]PMEM2_E_IO_FAIL\f[] \- 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[] \- read/write operation size
\f[I]size\f[] from offset \f[I]offset\f[] goes beyond the file length.
.IP \[bu] 2
\f[B]PMEM2_E_SOURCE_TYPE_NOT_SUPPORTED\f[] \- read/write operation
doesn't support provided source, only sources created with
\f[B]pmem2_source_from_fd\f[](3) and
\f[B]pmem2_source_from_handle\f[](3) are supported.
.PP
Those operations can also return all errors from the underlying
\f[B]pread\f[](2), \f[B]pwrite\f[](2), \f[B]sigaction\f[](2) functions
on POSIX systems and \f[B]ReadFile\f[](), \f[B]WriteFile\f[]() functions
on Windows.
.SH SEE ALSO
.PP
\f[B]pread\f[](2), \f[B]pwrite\f[](2), \f[B]ReadFile\f[](),
\f[B]WriteFile\f[](), \f[B]pmem2_badblock_clear\f[](3),
\f[B]pmem2_badblock_context_new\f[](3), \f[B]pmem2_badblock_next\f[](3),
\f[B]pmem2_source_from_fd\f[](3), \f[B]pmem2_source_from_handle\f[](3),
\f[B]libpmem2\f[](7) and \f[B]<https://pmem.io>\f[]