pmfstring(3) — Linux manual page


PMFSTRING(3)            Library Functions Manual            PMFSTRING(3)

NAME         top

       pmfstring - safe string scanning

C SYNOPSIS         top

       #include <pcp/pmapi.h>

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

       cc ... -lpcp

DESCRIPTION         top

       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

       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


       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         top

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

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at 
       ⟨⟩.  If you have a bug report for this manual
       page, send it to  This page was obtained from the
       project's upstream Git repository
       ⟨⟩ on 2024-06-14.
       (At that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

Performance Co-Pilot               PCP                      PMFSTRING(3)