NAME

       cl_hp_get_field - Execute header parser

SYNOPSIS

       #include <libcanlock-3/canlock-hp.h>

       char *cl_hp_get_field(const char *data, size_t data_len,
                             const char *field);

DESCRIPTION

       Note: Consider the function cl_hp_unfold_field() if the header field was already extracted
       by another header parser (but may still contain folding).

       The cl_hp_get_field() function executes the header parser to extract and unfold  a  single
       header field.
       This implementation executes the canlock-mhp utility in a separate process.

       The parameter data should point to the beginning of the input data.
       Specify the length of the input data with the data_len parameter.
       The name of a single header field must be specified with the field parameter.

       The  input  data  must  be  a message in canonical format (with US-ASCII encoded CRLF line
       breaks). If the message is in some local format (e.g.  EBCDIC  encoded  or  with  LF  line
       breaks), it must be converted to canonical format before it can be used as input.

       The  input  data  may be a naked header without message body, but the empty line separator
       after the header must always be present.  The syntax of the extracted header field is  not
       checked beyond the folding.  The rest of the message need not be fully RFC 5536 conformant
       too, as long as all header fields start on new lines (and are correctly  folded,  so  that
       there  is  no  ambiguity).  Common syntax errors (like 8-bit characters in the header) are
       ignored.

RETURN VALUE

       If the parser reports success, a pointer to the NUL-terminated output  data  is  returned.
       Otherwise, NULL is returned.

       On  success, the caller is responsible to free() the memory block allocated for the output
       data.

AUTHORS

       Michael Baeuerle

REPORTING BUGS

       Report bugs to <mailto:michael.baeuerle@gmx.net>.

STANDARDS

       cl_hp_get_field() tries to comply with the following standards:

       RFC 5322, RFC 5536

SEE ALSO

       free(3),  cl_hp_parse_field(3),  cl_hp_unfold_field(3),  canlock-hfp(1),   canlock-mhp(1),
       canlock(1)