Merge pull request #1731 from zanzaben/Fix1730_explain_fs_offset

Fix #1730, Explain FS Header offset & add offset functional tests.

modules/cfe_testcase/src/fs_header_test.c

@@ -56,6 +56,7 @@ void TestCreateHeader(void)
 
     cFE_FTAssert_VOIDCALL(CFE_FS_InitHeader(&Header, TestDescription, CFE_FS_SubType_ES_ERLOG));
     UtAssert_INT32_EQ(CFE_FS_WriteHeader(fd, &Header), sizeof(CFE_FS_Header_t));
+    UtAssert_INT32_EQ(OS_lseek(fd, 0, OS_SEEK_CUR), sizeof(CFE_FS_Header_t));
 
     UtAssert_INT32_EQ(CFE_FS_WriteHeader(fd, NULL), CFE_FS_BAD_ARGUMENT);
     cFE_FTAssert_NOT_CFE_SUCCESS(CFE_FS_WriteHeader(OS_OBJECT_ID_UNDEFINED, &Header));
@@ -80,6 +81,7 @@ void TestReadHeader(void)
     cFE_FTAssert_VOIDCALL(CFE_FS_InitHeader(&Header, TestDescription, CFE_FS_SubType_ES_ERLOG));
     UtAssert_INT32_EQ(CFE_FS_WriteHeader(fd, &Header), sizeof(CFE_FS_Header_t));
     UtAssert_INT32_EQ(CFE_FS_ReadHeader(&ReadHeader, fd), sizeof(CFE_FS_Header_t));
+    UtAssert_INT32_EQ(OS_lseek(fd, 0, OS_SEEK_CUR), sizeof(CFE_FS_Header_t));
 
     UtAssert_INT32_EQ(Header.ContentType, ReadHeader.ContentType);
     UtAssert_INT32_EQ(Header.SubType, ReadHeader.SubType);
@@ -105,6 +107,8 @@ void TestTimeStamp(void)
     cFE_FTAssert_VOIDCALL(CFE_FS_InitHeader(&Header, TestDescription, CFE_FS_SubType_ES_ERLOG));
     UtAssert_INT32_EQ(CFE_FS_WriteHeader(fd, &Header), sizeof(CFE_FS_Header_t));
     UtAssert_INT32_EQ(CFE_FS_SetTimestamp(fd, NewTimestamp), CFE_SUCCESS);
+    UtAssert_INT32_EQ(OS_lseek(fd, 0, OS_SEEK_CUR), (offsetof(CFE_FS_Header_t, TimeSeconds) + sizeof(NewTimestamp)));
+
     UtAssert_INT32_EQ(CFE_FS_ReadHeader(&ReadHeader, fd), sizeof(CFE_FS_Header_t));
 
     UtAssert_UINT32_EQ(0xFFFFFFFF, ReadHeader.TimeSeconds);

modules/core_api/fsw/inc/cfe_fs.h

@@ -57,6 +57,8 @@
 ** \par Assumptions, External Events, and Notes:
 **        -# The File has already been successfully opened using #OS_OpenCreate and
 **           the caller has a legitimate File Descriptor.
+**        -# File offset behavior: Agnostic on entry since it will move the offset to the start of the file,
+**           on success the offset will be at the end of the header, undefined offset behavior for error cases.
 **
 ** \param[in, out] Hdr     Pointer to a variable of type #CFE_FS_Header_t that will be
 **                         filled with the contents of the Standard cFE File Header. *Hdr is the contents of the
@@ -120,6 +122,8 @@ void CFE_FS_InitHeader(CFE_FS_Header_t *Hdr, const char *Description, uint32 Sub
 **           the caller has a legitimate File Descriptor.
 **        -# The \c SubType field has been filled appropriately by the Application.
 **        -# The \c Description field has been filled appropriately by the Application.
+**        -# File offset behavior: Agnostic on entry since it will move the offset to the start of the file,
+**           on success the offset will be at the end of the header, undefined offset behavior for error cases.
 **
 ** \param[in] FileDes File Descriptor obtained from a previous call to #OS_OpenCreate
 **                    that is associated with the file whose header is to be read.
@@ -152,6 +156,8 @@ CFE_Status_t CFE_FS_WriteHeader(osal_id_t FileDes, CFE_FS_Header_t *Hdr);
 **        -# The File has already been successfully opened using #OS_OpenCreate and
 **           the caller has a legitimate File Descriptor.
 **        -# The \c NewTimestamp field has been filled appropriately by the Application.
+**        -# File offset behavior: Agnostic on entry since it will move the offset,
+**           on success the offset will be at the end of the time stamp, undefined offset behavior for error cases.
 **
 ** \param[in] FileDes File Descriptor obtained from a previous call to #OS_OpenCreate
 **                    that is associated with the file whose header is to be read.