NAME

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

SYNOPSIS

#include <limb/esc.h>

int escall_fmt(char *dst, size_t dlen, const char *sce, size_t slen, size_t *w, size_t *r)
int escall_scan(char *dst, size_t dlen, const char *sce, size_t slen, size_t *w, size_t *r)

ssize_t esc_fmt(char *dst, size_t dlen, const char *sce, size_t slen)
ssize_t esc_scan(char *dst, size_t dlen, const char *sce, size_t slen)

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.

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

ESCAPING

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

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 :

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

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

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)