% limb manual
% escall_fmt(3)
% limb 0.2.0
% 2024-01-09

# NAME

escall_fmt, escall_scan, esc_fmt, esc_scan - (un)escape given text/data

# SYNOPSIS

    #include <limb/esc.h>

```pre hl
int escall_fmt(char *<em>dst</em>, size_t <em>dlen</em>, const char *<em>sce</em>, size_t <em>slen</em>, size_t *<em>w</em>, size_t *<em>r</em>)
int escall_scan(char *<em>dst</em>, size_t <em>dlen</em>, const char *<em>sce</em>, size_t <em>slen</em>, size_t *<em>w</em>, size_t *<em>r</em>)

ssize_t esc_fmt(char *<em>dst</em>, size_t <em>dlen</em>, const char *<em>sce</em>, size_t <em>slen</em>)
ssize_t esc_scan(char *<em>dst</em>, size_t <em>dlen</em>, const char *<em>sce</em>, size_t <em>slen</em>)
```

# DESCRIPTION

The `escall_fmt`() function will write the content of `sce` of length `slen`
bytes, starting at offset pointed by `r` (usually 0), into the memory area
pointed by `dst` starting at position `w` (usually 0) and never going past
`dlen`, whilst taking care of escaping characters as needed. This means more
characters might be written into `dst` than present in `sce`.

The values pointed to by `r` and `w` are updated accordingly to reflect the
positions of the last read in `sce` and write in `dst`, respectively.
Specifically, if a byte couldn't be escaped for lack of space in `dst`, the
value pointed to by `r` would remain on the last successfully processed byte,
and no "partial write" would have occurred in `dst`.

If `dst` is *NULL* then nothing is written, the data in `sce` is still processed
and both `r` and `w` (/both/ mandatory) updated accordingly.

The `esc_fmt`() function is similar, only without the `r` and `w` arguments, and
different return values.

The `escall_scan`() function will read the data pointed to be `sce` of length
`slen` bytes, starting at offset pointed by `r` (usually 0), and write in the
memory area pointed by `dst` (up to `dlen` bytes) starting at offset pointed by
`w` the result of unescaping said data, expected by have been previously
escaped via `escall_fmt`().

Similarly to `escall_fmt`() the values pointed to by `r` and `w` are updated
accordingly.

! INFO: Stream mode
! It is possible to use `escall_scan`() without having the full data stream yet.
! That is, if it is not possible to perform an unescaping it will fail with
! *ENODATA* and both `r` and `w` will be updated as expected.
! That is notably `r` will be set to the offset of the last byte actually read
! and successfully processed, and `w` the corresponding last byte written.

The `esc_scan`() function is similar to `escall_scan`() only without the `r` and
`w` argument, and different return values.

! NOTE:
! The `escall_scan`() function supports the same memory location given in `sce`
! and `dst` with different offsets in `r` and `w`.
! Similarly, the `esc_scan`() function supports overlapping memory locations in
! `sce` and `dst`.

# ESCAPING

The escaping performed is intended to have the written value inside
double-quotes. Bytes with special escaping are as follow :

: double-quote (`"`)
:: Escaped by prefixing with a backslash (`\`)

: backslash (`\`)
:: Escaped by prefixing with a backslash (`\`)

: bell (`0x07`)
:: Escaped as `\a`

: backspace (`0x08`)
:: Escaped as `\b`

: tabulation (`0x09`)
:: Escaped as `\t`

: line feed (`0x0a`)
:: Escaped as `\n`

: vertical tabulation (`0x0b`)
:: Escaped as `\v`

: form feed (`0x0c`)
:: Escaped as `\f`

: carriage return (`0x0d`)
:: Escaped as `\r`

Anything else will either be written as-in if recognized as a printable
character in the current locale, else escaped in hex-mode, that is `\x` followed
by the hexadecimal code of the byte. (For example, character 127 would be
escaped as `\x7f`)

# RETURN VALUE

The `escall_fmt`() and `escall_scan`() functions return 1 on success. Otherwise
they return 0 and set `errno` to indicate the error.

In either case, values pointed to by `r` and `w` will have been updated to
reflect the positions of the last read in `sce` and write in `dst`,
respectively.

The `esc_fmt`() and `esc_scan`() functions return the number of bytes written
into `dst` on success. Otherwise they return -1 and set `errno` to indicate the
error.

# ERRORS

The `escall_fmt`(), `esc_fmt`(), `escall_scan`() and `esc_scan`() function may
fail if :

: *ENOBUFS*
:: Not enough space in `dst`.

The `escall_fmt`() and `escall_scan`() functions may also fail if :

: *EINVAL*
:: Either `r` or `w` was too high (more than `slen` or `dlen`, respectively).

The `escall_scan`() and `esc_scan`() functions may also fail if :

: *EINVAL*
:: Data in `sce` is malformed/invalid. E.g. a backslash followed by other than
:: an allowed byte or a non-escaped quote.

: *ENODATA*
:: Not enough data available in `sce`. E.g. a backslash as last byte, or
:: followed by an `x` and less than 2 bytes.

# NOTES

The behavior of the `escall_fmt`() and `esc_fmt`() functions depend on the
*LC_CTYPE* category of the current locale.

# SEE ALSO

[buffer_putesc](3)