sd-journal: add comments that journal_file_move_to() may break previous read data

We have already made similar mistakes several times, e.g.
b8478c14c7367c3ec5d47d2680a3390b0dedecb1, and
b596d06c385e104fc330288b791a56661f0c2d17. Let's document the function
invalidates previously read objects.

diff --git a/src/libsystemd/sd-journal/journal-file.c b/src/libsystemd/sd-journal/journal-file.c
index 54bad925b2af28091c7b448c3d5e716e51b06450..02e9b9a6742d8e5bddd3c893253a9e60a60008fd 100644 (file)
--- a/src/libsystemd/sd-journal/journal-file.c
+++ b/src/libsystemd/sd-journal/journal-file.c
@@ -643,6 +643,10 @@ static int journal_file_move_to(
         assert(f);
         assert(ret);
 
+        /* This function may clear, overwrite, or alter previously cached entries. After this function has
+         * been called, all objects except for one obtained by this function are invalidated and must be
+         * re-read before use. */
+
         if (size <= 0)
                 return -EINVAL;
 
@@ -878,6 +882,10 @@ int journal_file_move_to_object(JournalFile *f, ObjectType type, uint64_t offset
 
         assert(f);
 
+        /* Even if this function fails, it may clear, overwrite, or alter previously cached entries. After
+         * this function has been called, all objects except for one obtained by this function are
+         * invalidated and must be re-read before use.. */
+
         /* Objects may only be located at multiple of 64 bit */
         if (!VALID64(offset))
                 return log_debug_errno(SYNTHETIC_ERRNO(EBADMSG),