diff --git a/doc/src/Developer_utils.rst b/doc/src/Developer_utils.rst index 17b4715dc7..00a8b43a24 100644 --- a/doc/src/Developer_utils.rst +++ b/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 diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index da69cc4edc..c93685c221 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/doc/utils/sphinx-config/false_positives.txt @@ -2190,6 +2190,7 @@ nl nlayers nlen Nlines +nlines nlo nlocal Nlocal diff --git a/src/utils.cpp b/src/utils.cpp index 9aa8e2f7ee..00510984fd 100644 --- a/src/utils.cpp +++ b/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); diff --git a/src/utils.h b/src/utils.h index b393f89ffa..770c0b527a 100644 --- a/src/utils.h +++ b/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