NAME

       pmfstring - safe string scanning

C SYNOPSIS

       #include <pcp/pmapi.h>

       ssize_t pmfstring(FILE *f, char **str);

       cc ... -lpcp

DESCRIPTION

       pmfstring  is  a  safe  string  scanning  routine  with semantics similar to fscanf(3) with the %s format
       specifier.  It scans the input stream from f skipping initial whitespace  characters,  then  accumulating
       all the subsequent non-whitespace characters.

       The  main  difference  is  that  pmfstring allocates the result buffer str using the malloc(3) family and
       ensures that str is (a) large enough and (b) null-byte terminated.

       Additionally pmfstring does not consider \n to be a whitespace character  in  the  initial  scan  (before
       filling  str)  and so will not scan past the end of the current line, which is different to fscanf(3) and
       better aligned with the PCP use cases.

       The caller is responsible for maintaining a reference to str or calling free(3) to release the associated
       storage.

       On success, pmfstring returns the length of str (the same length  as  strlen(3)  would  return)  that  is
       guaranteed to be not less than 1.

       Failure is indicated by one of the following, and str is not assigned a value:
        • 0  to  indicate  no  non-whitespace  characters were found before the end of the current line from the
          stream f
        • -1 ( aka EOF) to indicate end of file on the stream f
        • -2 to indicate some more serious failure, probably in the malloc(3) routines; refer to errno for  more
          information

COMPATIBILITY

       pmfstring  has  similar  semantics  to the %ms format specifier in some versions of fscanf(3) and the C99
       fscanf_s(3) routine - unfortunately neither of these is portable.

SEE ALSO

       free(3), fscanf(3), malloc(3) and strlen(3).

Performance Co-Pilot                                   PCP                                          PMFSTRING(3)