% limb manual
% sanitize_read(3)
% limb 0.1.0
% 2023-07-24

# NAME

sanitize_read, unsanitize_read - (un)sanitize return code from standard I/O
functions

# SYNOPSIS

    #include <limb/allreadwrite.h>

```pre hl
ssize_t sanitize_read(ssize_t <em>r</em>)
ssize_t unsanitize_read(ssize_t <em>r</em>)
```

# DESCRIPTION

Standard I/O functions (such as [read](3) or its safe wrapper [fd_read](3))
return -1 on error and 0 when reaching end-of-file.

A lack of data available when attempting to read in non-blocking mode is treated
as an error (*EWOULDBLOCK*). However, it is sometimes preferable to handle EOF
as the exception and *EWOULDBLOCK* as a normal condition, whilst waiting for
data to become available.

The `sanitize_read`() function aims to "correct" this by turning a value of -1
with *EWOULDBLOCK* or *EAGAIN* into a 0 (as no data was read), whilst turning a
value of 0 into -1 with *EPIPE* to indicate end-of-file.

! NOTE:
! Standard system reading functions never set `errno` to *EPIPE* making it
! thusly a proper candidate for such a case.

The `unsanitize_read`() function does the reverse of `sanitize_read`().

# RETURN VALUE

The `sanitize_read`() returns 0 and sets `errno` to 0 if `r` is -1 and `errno`
is set to *EWOULDBLOCK* or *EAGAIN*; It returns -1 and sets `errno` to *EPIPE*
if `r` if 0; Otherwise it returns `r` leaving `errno` unchanged.

The `unsanitize_read`() returns 0 and sets `errno` to 0 if `r` is -1 and `errno`
is set to *EPIPE*; It returns -1 and sets `errno` to *EWOULDBLOCK* if `r` is 0;
Otherwise it returns `r` leaving `errno` unchanged.