add docs for new utility function

doc/src/Developer_utils.rst

@@ -12,11 +12,16 @@ reduces redundant implementations and encourages consistent behavior.
 I/O with status check
 ^^^^^^^^^^^^^^^^^^^^^
 
-These are wrappers around the corresponding C library calls like
-``fgets()`` or ``fread()``.  They will check if there were errors
-on reading or an unexpected end-of-file state was reached.  In that
-case, the functions will stop the calculation with an error message,
-indicating the name of the problematic file, if possible.
+The the first two functions are wrappers around the corresponding C
+library calls ``fgets()`` or ``fread()``.  They will check if there
+were errors on reading or an unexpected end-of-file state was reached.
+In that case, the functions will stop the calculation with an error
+message, indicating the name of the problematic file, if possible.
+The :cpp:func:`read_lines_from_file` function will read the requested
+number of lines of a maximum length into a buffer and will return 0
+if successful or 1 if not. It also guarantees that all lines are
+terminated with a newline character and the entire buffer with a
+NULL character.
 
 ----------
 
@@ -26,6 +31,9 @@ indicating the name of the problematic file, if possible.
 .. doxygenfunction:: sfread
    :project: progguide
 
+.. doxygenfunction:: read_lines_from_file
+   :project: progguide
+
 ----------
 
 String to number conversions with validity check

doc/utils/sphinx-config/false_positives.txt

@@ -2190,6 +2190,7 @@ nl
 nlayers
 nlen
 Nlines
+nlines
 nlo
 nlocal
 Nlocal

src/utils.cpp

@@ -226,7 +226,7 @@ void utils::sfread(const char *srcname, int srcline, void *s, size_t size,
 /* ------------------------------------------------------------------ */
 
 /* read N lines and broadcast */
-int utils::read_lines_from_file(FILE *fp, int nlines, int maxline,
+int utils::read_lines_from_file(FILE *fp, int nlines, int nmax,
                                 char *buffer, int me, MPI_Comm comm)
 {
   char *ptr = buffer;
@@ -235,7 +235,7 @@ int utils::read_lines_from_file(FILE *fp, int nlines, int maxline,
   if (me == 0) {
     if (fp) {
       for (int i = 0; i < nlines; i++) {
-        ptr = fgets(ptr,maxline,fp);
+        ptr = fgets(ptr,nmax,fp);
         if (!ptr) break; // EOF?
         // advance ptr to end of string and append newline char if needed.
         ptr += strlen(ptr);

src/utils.h

@@ -97,19 +97,19 @@ namespace LAMMPS_NS {
      * This function uses repeated calls to fread() to fill a buffer with
      * newline terminated text.  If a line does not end in a newline (e.g.
      * at the end of a file), it is added.  The caller has to allocate an
-     * nlines by maxline sized buffer for storing the text data.
+     * nlines by nmax sized buffer for storing the text data.
      * Reading is done by MPI rank 0 of the given communicator only, and
      * thus only MPI rank 0 needs to provide a valid file pointer.
      *
      *  \param fp       file pointer used by fread
      *  \param nlines   number of lines to be read
-     *  \param maxline  maximum length of a single line
+     *  \param nmax     maximum length of a single line
      *  \param buffer   buffer for storing the data.
      *  \param me       MPI rank of calling process in MPI communicator
      *  \param comm     MPI communicator for broadcast
-     *  \return         1 if the read was short, 0 if read was succesful */
+     *  \return         1 if the read was short, 0 if read was successful */
 
-    int read_lines_from_file(FILE *fp, int nlines, int maxline,
+    int read_lines_from_file(FILE *fp, int nlines, int nmax,
                              char *buffer, int me, MPI_Comm comm);
 
     /** Report if a requested style is in a package or may have a typo