string.c: Remove an unused local variable in for_each_line().

This set but not used variable existed for a long time, but only now
the first compiler, clang-19 on FreeBSD, started to complain.

Streamline the documentation a bit while at it.

diff --git a/string.c b/string.c
index d8bd027b7010a149be59b8883b3e5ee685fb3c01..eee01aa27a514aea87b36ceda64c37e34aa6d501 100644 (file)
--- a/string.c
+++ b/string.c
@@ -352,30 +352,28 @@ __malloc char *para_hostname(void)
 }
 
 /**
- * Call a custom function for each complete line.
+ * Call a function for each complete line in a buffer.
  *
  * \param flags Any combination of flags defined in \ref for_each_line_flags.
  * \param buf The buffer containing data separated by newlines.
- * \param size The number of bytes in \a buf.
- * \param line_handler The custom function.
- * \param private_data Pointer passed to \a line_handler.
- *
- * For each complete line in \p buf, \p line_handler is called. The first
- * argument to \p line_handler is (a copy of) the current line, and \p
- * private_data is passed as the second argument.  If the \p FELF_READ_ONLY
- * flag is unset, a pointer into \a buf is passed to the line handler,
- * otherwise a pointer to a copy of the current line is passed instead. This
- * copy is freed immediately after the line handler returns.
- *
- * The function returns if \p line_handler returns a negative value or no more
- * lines are in the buffer.  The rest of the buffer (last chunk containing an
- * incomplete line) is moved to the beginning of the buffer if FELF_READ_ONLY is
- * unset.
- *
- * \return On success this function returns the number of bytes not handled to
- * \p line_handler. The only possible error is a negative return value from the
- * line handler. In this case processing stops and the return value of the line
- * handler is returned to indicate failure.
+ * \param size The number of bytes in the buffer.
+ * \param line_handler The callback function.
+ * \param private_data Pointer passed to the line handler.
+ *
+ * If the FELF_READ_ONLY flag is unset, line breaks in the buffer are replaced
+ * by NUL characters and pointers into the thusly modified buffer are passed to
+ * the line handler. Otherwise, at each iteration a temporary NUL-terminated
+ * copy of the current line is made and a pointer to the copy is passed
+ * instead.
+ *
+ * Processing stops if the line handler returns negative or when there are no
+ * more complete lines in the buffer. In the latter case, if FELF_READ_ONLY is
+ * unset, the last chunk containing an incomplete line is moved to the
+ * beginning of the buffer.
+ *
+ * \return The only possible error is a negative return value from the line
+ * handler. The function then returns this negative value to indicate failure.
+ * Otherwise it returns the size of the last incomplete line in bytes.
  *
  * \sa \ref for_each_line_flags.
  */
@@ -383,9 +381,8 @@ int for_each_line(unsigned flags, char *buf, size_t size,
                line_handler_t *line_handler, void *private_data)
 {
        char *start = buf, *end;
-       int ret, i, num_lines = 0;
+       int ret, i;
 
-//     PARA_NOTICE_LOG("buf: %s\n", buf);
        while (start < buf + size) {
                char *next_null;
                char *next_cr;
@@ -399,7 +396,6 @@ int for_each_line(unsigned flags, char *buf, size_t size,
                        end = next_null;
                else
                        end = next_cr;
-               num_lines++;
                if (!(flags & FELF_DISCARD_FIRST) || start != buf) {
                        if (flags & FELF_READ_ONLY) {
                                size_t s = end - start;