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).