class ara::per::FileStorage

The synchronous method DeleteFile of class ara::per::FileStorage deletes a file from file storage by its name (fileName) [SWS_PER_00111]. The identifier can correspond to the configured PersistencyFile.fileName [SWS_PER_00111]. The invocation is specified as noexcept, is considered exception safe and thread-safe, and reports the result via ara::core::Result<void> [SWS_PER_00111].

Before the call, all active accesses to the target file must have ended. If the file is currently open, the deletion fails with error PerErrc::kResourceBusy [SWS_PER_00111]. Applications must therefore ensure that UniqueHandle instances previously created via OpenFileReadWrite [SWS_PER_00113], OpenFileReadOnly [SWS_PER_00114], or OpenFileWriteOnly [SWS_PER_00115] have left their scope, thereby closing the file. Likewise, a concurrently running execution of RecoverFile [SWS_PER_00337] or ResetFile [SWS_PER_00338] for the same file name leads to PerErrc::kResourceBusy [SWS_PER_00111].

In case of error, the returned Result type provides specific error causes [SWS_PER_00111]:

• PerErrc::kFileNotFound: The specified file does not exist in the file storage [SWS_PER_00111].
• PerErrc::kIllegalWriteAccess: The file storage is configured as read-only [SWS_PER_00111].
• PerErrc::kPhysicalStorageFailure: Access to the physical storage medium fails (without rollback semantics) [SWS_PER_00111].
• PerErrc::kIntegrityCorrupted, PerErrc::kEncryptionFailed, or PerErrc::kAuthenticationFailed: Errors in structural integrity, encryption/decryption, or MAC verification (each with rollback semantics), as well as vendor-specific errors [SWS_PER_00111].

The synchronous method FileExists of class ara::per::FileStorage checks whether a file exists in the respective file storage [SWS_PER_00112]. The function is declared as noexcept and throws no C++ exceptions [SWS_PER_00112].

use

fileName is passed as ara::core::StringView as a parameter, which can correspond to the identifier PersistencyFile.fileName of a configured file [SWS_PER_00112]. The return value ara::core::Result<bool> returns true if the file could be located, and false otherwise [SWS_PER_00112].

Error handling

If the check fails, the returned Result does not contain a boolean value, but an error code [SWS_PER_00112]. Specified causes of error are:

• PerErrc::kPhysicalStorageFailure on failure of physical storage access [SWS_PER_00112],
• PerErrc::kIntegrityCorrupted in case of damaged structural integrity of the data [SWS_PER_00112],
• PerErrc::kValidationFailed if the validity of stored data cannot be ensured [SWS_PER_00112],
• PerErrc::kEncryptionFailed in case of failed decryption [SWS_PER_00112],
• PerErrc::kAuthenticationFailed in case of failing MAC verification [SWS_PER_00112], as well as possible vendor-specific errors [SWS_PER_00112].

Concurrency and Limitations

The method is declared as thread-safe [SWS_PER_00112]. However, the returned check result is accurate only as long as no files in storage are added or deleted at the same time; for instance, if another thread removes a file immediately after true is returned, the result is already no longer valid [SWS_PER_00112].

The method OpenFileReadOnly of class ara::per::FileStorage (declared in #include "ara/per/file_storage.h") opens a persisted file read-only with a specified access mode [SWS_PER_00114]. Unless specified otherwise via the parameter mode, the read pointer position is set to the beginning of the file (kAtTheBeginning) by default [SWS_PER_00114]. Execution is synchronous and returns a ara::core::Result<UniqueHandle<ReadAccessor>>. The handle uses RAII semantics: As soon as the instance of UniqueHandle leaves its scope, the file is closed automatically [SWS_PER_00114].

Regarding concurrency, the method is specified as thread-safe and exception safe (with noexcept) [SWS_PER_00114]. Nevertheless, functional calling restrictions exist: If the target file is already open or operations such as DeleteFile, RecoverFile, or ResetFile are executed concurrently with the same file name, the call fails with PerErrc::kResourceBusy [SWS_PER_00114].

In the event of an error, the ara::core::Result returns vendor-specific errors or standardized error codes from PerErrc or StorageFailure [SWS_PER_00114]:

• PerErrc::kFileNotFound: The specified file does not exist in the file storage [SWS_PER_00114].
• PerErrc::kInvalidOpenMode: The passed mode contains an invalid combination of flags [SWS_PER_00114].
• StorageFailure: Access to physical storage failed [SWS_PER_00114].
• PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kAuthenticationFailed, or PerErrc::kEncryptionFailed: Structural integrity corrupted, validation insufficient, MAC verification failed, or decryption unsuccessful [SWS_PER_00114].

In interplay with other interfaces, FileStorage offers two related overloads: A variant without a mode parameter that always opens at the beginning of the file [SWS_PER_00376], as well as an overload with a buffer (ara::core::Span<ara::core::Byte> buffer) through which the ReadAccessor implements block-wise reading to accelerate many small accesses [SWS_PER_00430].

use

The method OpenFileReadOnly of class ara::per::FileStorage opens a persisted file read-only for reading [SWS_PER_00376]. The call is made via the header file ara/per/file_storage.h, passing the file name fileName. In doing so, the read position is initially set to the beginning of the file. A ara::core::Result serves as the return value, providing a UniqueHandle<ReadAccessor> on success. The opened file is closed automatically as soon as this handle goes out of scope.

Error handling

If execution fails, the result contains an error code or a vendor-specific error [SWS_PER_00376]:

• PerErrc::kFileNotFound: The specified file does not exist in storage.
• PerErrc::kResourceBusy: The file is already open or is being processed concurrently by DeleteFile, RecoverFile, or ResetFile.
• PerErrc::kPhysicalStorageFailure: Access to the physical storage medium failed.
• PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed, PerErrc::kAuthenticationFailed: Errors in structural integrity, data validation, decryption, or MAC verification.

Concurrency and Interaction

The method is specified as thread-safe, exception safe, and noexcept [SWS_PER_00376]. Overloads are available for advanced requirements: a variant for explicitly specifying an OpenMode [SWS_PER_00114] as well as a signature with an additional user buffer for blockwise acceleration of smaller read accesses [SWS_PER_00430].

The synchronous method OpenFileReadOnly of class ara::per::FileStorage opens a persisted file for read access using a buffer provided by the caller [SWS_PER_00430]. File access is initialized based on the parameters fileName, mode, and buffer (as ara::core::Span<ara::core::Byte>) [SWS_PER_00430]. Unless specified otherwise via mode, the read position is by default at the beginning of the file (kAtTheBeginning) [SWS_PER_00430]. The passed memory area is used by the resulting ReadAccessor to accelerate repeated small read accesses via blockwise reading [SWS_PER_00430]. The resource is protected via RAII: As soon as the returned UniqueHandle goes out of scope, the file is automatically closed [SWS_PER_00430].

Regarding concurrency, the function is specified as thread-safe (thread-safe), exception-safe (exception safe), and noexcept [SWS_PER_00430]. If an error occurs, the ara::core::Result yields vendor-specific errors or standardized error codes from PerErrc [SWS_PER_00430]:

• PerErrc::kResourceBusy: The file is already open or is being processed concurrently by DeleteFile, RecoverFile, or ResetFile [SWS_PER_00430].
• PerErrc::kFileNotFound: The specified file does not exist in the file storage [SWS_PER_00430].
• PerErrc::kInvalidOpenMode: The passed mode contains an invalid combination of options [SWS_PER_00430].
• Integrity and security errors: PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed, or PerErrc::kAuthenticationFailed (failure of the MAC check) as well as StorageFailure in case of physical storage access errors [SWS_PER_00430].

In addition to this buffered variant, the overloads [SWS_PER_00114] (with mode) and [SWS_PER_00376] (with fileName only) are available for use cases without a user-defined buffer.

use

The synchronous method OpenFileReadWrite of class ara::per::FileStorage opens a file for read and write access in the specified mode mode [SWS_PER_00113]. Unless specified otherwise in the mode, the file pointer is placed at the beginning by default (kAtTheBeginning). If the file does not yet exist, it is created automatically [SWS_PER_00113]. The function returns a ara::core::Result with a UniqueHandle<ReadWriteAccessor>, which closes the file automatically as soon as the handle leaves its scope [SWS_PER_00113].

Concurrency and Limitations

The call is thread-safe and throws no exceptions (noexcept) [SWS_PER_00113]. The file must not already be open when called. Furthermore, no concurrent execution of DeleteFile, RecoverFile, or ResetFile with the same file name must take place, otherwise the call fails with PerErrc::kResourceBusy [SWS_PER_00113].

Error handling

In case of error, the ara::core::Result contains specific error codes [SWS_PER_00113]:

• PerErrc::kInvalidOpenMode: Invalid combination of flags in the passed mode.
• PerErrc::kResourceBusy: The target file is already open or is occupied by administrative file operations.
• Access: The storage is configured as read-only or as write-only-once with an already existing key.
• PerErrc::kOutOfStorageSpace or PerErrc::kTooManyFiles: Insufficient physical storage space or exceeded maxNumberOfFiles during creation.
• PerErrc::kPhysicalStorageFailure, PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed, PerErrc::kAuthenticationFailed: Hardware access errors, corrupted data structures, or failed cryptographic validations.

Interaction

As a simplified variant, an overload without mode parameter is available that opens files at the beginning by default [SWS_PER_00375]. For performance optimization with numerous small accesses, an overload with user-defined buffer (buffer) for block-by-block reading and writing also exists [SWS_PER_00429].

The synchronous member function OpenFileReadWrite of class ara::per::FileStorage serves to open a file for combined read and write accesses [SWS_PER_00375]. The file name fileName is passed as a parameter as ara::core::StringView, which may correspond to the modeling PersistencyFile.fileName of a configured file [SWS_PER_00375]. If the specified file does not yet exist, it is automatically created anew [SWS_PER_00375]. Upon opening, the file position is immediately set to the beginning (corresponding to kAtTheBeginning) [SWS_PER_00375]. The caller receives a ara::core::Result<UniqueHandle<ReadWriteAccessor>>; the file is automatically closed as soon as the returned UniqueHandle leaves its scope [SWS_PER_00375].

Regarding concurrency and execution context, the function is specified as thread-safe and exception safe [SWS_PER_00375]. However, it should be noted that simultaneous accesses are regulated: If the file is already open or an operation such as DeleteFile, RecoverFile, or ResetFile is executed concurrently on the same file name, the call fails and returns the error code PerErrc::kResourceBusy [SWS_PER_00375].

In case of an error, the returned Result object encapsulates specific persistence errors or vendor-specific errors [SWS_PER_00375]:

• Configuration and access errors such as Access for read-only storage or already existing data with write-once configuration [SWS_PER_00375].
• Storage space limits through PerErrc::kOutOfStorageSpace or PerErrc::kTooManyFiles when exceeding the configured file upper limit [SWS_PER_00375].
• Integrity and security errors such as PerErrc::kPhysicalStorageFailure, PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed, or PerErrc::kAuthenticationFailed [SWS_PER_00375].

In interaction with further interfaces of FileStorage, AUTOSAR provides alternative overloads: OpenFileReadWrite can be called with an explicit OpenMode [SWS_PER_00113] or with an additional user-side memory area buffer (ara::core::Span<ara::core::Byte>) that enables block-wise buffering to accelerate repeated small accesses [SWS_PER_00429].

use

The method OpenFileReadWrite of class ara::per::FileStorage opens a file synchronously for combined reading and writing while providing a user-defined buffer [SWS_PER_00429]. The passed memory area buffer (as ara::core::Span<ara::core::Byte>) is used internally by the ReadWriteAccessor for blockwise read and write operations in order to handle series of small accesses performantly. If the specified file does not exist yet, it is created automatically anew; the file position is by default at the beginning (kAtTheBeginning), unless specified otherwise in the passed mode [SWS_PER_00429]. The file is closed as soon as the UniqueHandle returned in the ara::core::Result goes out of scope. Interpretation: The underlying memory of the passed buffer span presumably must remain valid for the entire lifetime of the UniqueHandle, since the accessor references it for block accesses. Question Q-e0009b7de17e3597 (open)

Error Handling and Concurrency

The function is specified as noexcept, exception safe, and thread-safe [SWS_PER_00429]. In case of failures, the Result yields vendor-specific errors or defined error codes:

• PerErrc::kResourceBusy: The file is already open or is being processed concurrently by DeleteFile, RecoverFile, or ResetFile with the same name [SWS_PER_00429].
• Access: The storage area is configured as read-only or defined as write-only-once and already occupied [SWS_PER_00429].
• PerErrc::kInvalidOpenMode: The passed mode contains an invalid combination of features [SWS_PER_00429].
• PerErrc::kOutOfStorageSpace or PerErrc::kTooManyFiles: Physical storage is insufficient for creating a new file, or the configured limit maxNumberOfFiles would be exceeded [SWS_PER_00429].
• PerErrc::kPhysicalStorageFailure, PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed, and PerErrc::kAuthenticationFailed: Errors during access, during integrity, MAC, or validation checks, as well as during decryption [SWS_PER_00429].

Interaction

The method represents a performance-optimized variant of opening for reading/writing: While [SWS_PER_00113] processes only the file name and mode and [SWS_PER_00375] exclusively the file name, [SWS_PER_00429] permits the targeted acceleration of small I/O accesses via an explicit memory buffer.

use

The method OpenFileWriteOnly of class ara::per::FileStorage opens a file synchronously for exclusive writing with a defined access mode [SWS_PER_00115]. Unless specified otherwise via the parameter mode, the file is truncated in the process (corresponding to kTruncate). If the file does not yet exist, it is newly created. A ara::core::Result<UniqueHandle<WriteAccessor>> serves as the return value; upon leaving the scope of the UniqueHandle, the file is automatically closed again [SWS_PER_00115].

Error handling

In case of an error, the returned Result contains specific error codes [SWS_PER_00115]: Access indicates that the storage is read-only or configured as write-once and the key already exists. PerErrc::kInvalidOpenMode reports invalid mode combinations, and PerErrc::kOutOfStorageSpace reports insufficient physical storage space. Furthermore, PerErrc::kTooManyFiles, PerErrc::kPhysicalStorageFailure, as well as integrity and security errors such as PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed, or PerErrc::kAuthenticationFailed may occur [SWS_PER_00115].

Concurrency and Limitations

The function is designed to be thread-safe and exception-safe (noexcept) [SWS_PER_00115]. Parallel accesses to the same file fail with the error code PerErrc::kResourceBusy if the file is already open or if operations such as DeleteFile, RecoverFile, or ResetFile are being executed concurrently with the same file name [SWS_PER_00115].

Interaction

In addition to this function, the interface provides a simplified overload without a mode parameter that works with kTruncate by default [SWS_PER_00377], as well as an overload with a user-defined buffer to enable block-wise writing for accelerating many small accesses [SWS_PER_00431].

use

The synchronous method OpenFileWriteOnly of class ara::per::FileStorage opens a file exclusively for writing according to [SWS_PER_00377]. It accepts the name of the target file via the parameter fileName. If the file does not exist, it is created anew; an already existing file is truncated (corresponding to kTruncate) [SWS_PER_00377]. A ara::core::Result serves as the return value, encapsulating a ara::per::UniqueHandle<WriteAccessor> on success. This handle closes the file automatically according to the RAII pattern as soon as it goes out of scope [SWS_PER_00377].

Error Handling and Concurrency

The operation is declared as noexcept, exception-safe, and thread-safe [SWS_PER_00377]. In the event of an error, the Result contains a specific error code from PerErrc or a vendor-specific error [SWS_PER_00377]:

• PerErrc::kResourceBusy: The file is already open or is being edited concurrently by DeleteFile, RecoverFile, or ResetFile.
• PerErrc::kOutOfStorageSpace and PerErrc::kTooManyFiles: Physical storage is insufficient or the maximum number of configured files (maxNumberOfFiles) is exceeded.
• PerErrc::kPhysicalStorageFailure, PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed, or PerErrc::kAuthenticationFailed: Errors during hardware access as well as during integrity, validation, or decryption checks.

Interaction

While this variant firmly predefines truncation, the overload with the parameter OpenMode allows a different open mode [SWS_PER_00115]. For optimized, blockwise write operations with multiple small accesses, a further overload with a user-defined buffer (ara::core::Span<ara::core::Byte>) is available [SWS_PER_00431].

The synchronous method OpenFileWriteOnly of class ara::per::FileStorage opens a file exclusively for writing and, in case of success, returns a ara::core::Result<UniqueHandle<WriteAccessor>> [SWS_PER_00431]. When the returned UniqueHandle goes out of scope, the opened file is automatically closed [SWS_PER_00431]. In addition to the file name fileName and the access mode mode, the call accepts a user-provided buffer buffer (as ara::core::Span<ara::core::Byte>), which is used for blockwise writing to accelerate repeated small write accesses [SWS_PER_00431]. If not configured differently in the mode, the file is truncated upon opening (corresponding to kTruncate); if it does not exist yet, it is created anew [SWS_PER_00431].

Regarding concurrency and safety, the method is specified as thread-safe and exception safe and declared as noexcept [SWS_PER_00431]. However, access fails if the file is already open or if administrative operations such as DeleteFile, RecoverFile, or ResetFile are being executed concurrently on the same file name [SWS_PER_00431].

In the event of an error, a corresponding error code from PerErrc or a vendor-specific error is returned in the result [SWS_PER_00431]:

• PerErrc::kResourceBusy: The file is already open or is occupied by another file operation [SWS_PER_00431].
• PerErrc::kIllegalWriteAccess: The file storage is read-only or configured as write-only-once and the file already exists [SWS_PER_00431].
• PerErrc::kInvalidOpenMode: The passed mode combination is invalid [SWS_PER_00431].
• PerErrc::kOutOfStorageSpace or PerErrc::kTooManyFiles: Storage space is insufficient or the maximum number of configured files is exceeded [SWS_PER_00431].
• PerErrc::kPhysicalStorageFailure, PerErrc::kIntegrityCorrupted, PerErrc::kValidationFailed, PerErrc::kEncryptionFailed, or PerErrc::kAuthenticationFailed: Errors in physical access, integrity, validation, decryption, or authentication [SWS_PER_00431].

In interaction with other interfaces, the function specifically extends the basic methods [SWS_PER_00377] (fileName only) and [SWS_PER_00115] (with mode) by buffer support for optimized write operations [SWS_PER_00431].

use

The synchronous method RecoverFile of class ara::per::FileStorage performs a best-effort recovery of a single file when redundancy checks fail [SWS_PER_00337]. The identifier of the affected file is passed via parameter fileName as ara::core::StringView. After recovery, the file may exhibit outdated states or the initial content, or in the worst case, be lost [SWS_PER_00337].

Concurrency and Interaction

The operation is specified as thread-safe and exception safe [SWS_PER_00337]. However, it must not be executed on open files: Prior to the call, all UniqueHandle instances previously obtained via file opening methods such as [SWS_PER_00113], [SWS_PER_00114], or [SWS_PER_00375] must be closed [SWS_PER_00337]. Otherwise, the call fails with PerErrc::kResourceBusy. The same error is reported if [SWS_PER_00111] (DeleteFile) or [SWS_PER_00338] (ResetFile) is executed concurrently for the same file name [SWS_PER_00337].

Error handling

The function returns a ara::core::Result<void> [SWS_PER_00337]. In addition to PerErrc::kResourceBusy, the following standardized errors can occur:

• PerErrc::kFileNotFound: The specified file does not exist in the file storage [SWS_PER_00337].
• PerErrc::kPhysicalStorageFailure: Access to the physical storage medium fails [SWS_PER_00337].
• PerErrc::kOutOfStorageSpace: Available physical storage space is insufficient for the restored file [SWS_PER_00337].
• PerErrc::kQuotaExceeded: The restored file would exceed the configured limit maximumAllowedSize [SWS_PER_00337].
• PerErrc::kEncryptionFailed and PerErrc::kAuthenticationFailed: Cryptographic decryption or MAC validation of the stored data has failed [SWS_PER_00337].

The synchronous method ResetFile of class ara::per::FileStorage resets a single file to its preconfigured initial state [SWS_PER_00338]. If the file specified via fileName does not yet exist in storage, it is newly created [SWS_PER_00338]. In both cases, the file subsequently has the same content as after a fresh installation from the current target configuration [SWS_PER_00338]; its modification state is maintained in FileModificationState as kModifiedDuringReset [SWS_PER_00436].

The operation is thread-safe as well as exception-safe and returns a ara::core::Result<void> synchronously [SWS_PER_00338]. It fails with PerErrc::kResourceBusy if the file is currently open – for example via [SWS_PER_00113] – or if an execution of [SWS_PER_00111] or [SWS_PER_00337] with the same file name is taking place concurrently [SWS_PER_00338].

In addition, the interface defines specific error cases [SWS_PER_00338]:

• PerErrc::kInitValueNotAvailable: An initial value is configured neither in the Application Design nor in the Target Configuration [SWS_PER_00338].
• PerErrc::kQuotaExceeded or PerErrc::kTooManyFiles: The restored file would exceed the limit AllowedSize or maxNumberOfFiles [SWS_PER_00338].
• PerErrc::kOutOfStorageSpace or StorageFailure: The physical storage space is insufficient or physical access fails [SWS_PER_00338].
• PerErrc::kEncryptionFailed or PerErrc::kAuthenticationFailed: Encryption/decryption or the MAC verification of the stored data fails [SWS_PER_00338].