le_atomFile.h File Reference
Go to the source code of this file.
Functions | |
int | le_atomFile_Open (const char *pathNamePtr, le_flock_AccessMode_t accessMode) |
int | le_atomFile_Create (const char *pathNamePtr, le_flock_AccessMode_t accessMode, le_flock_CreateMode_t createMode, mode_t permissions) |
int | le_atomFile_TryOpen (const char *pathNamePtr, le_flock_AccessMode_t accessMode) |
int | le_atomFile_TryCreate (const char *pathNamePtr, le_flock_AccessMode_t accessMode, le_flock_CreateMode_t createMode, mode_t permissions) |
void | le_atomFile_Cancel (int fd) |
le_result_t | le_atomFile_Close (int fd) |
FILE * | le_atomFile_OpenStream (const char *pathNamePtr, le_flock_AccessMode_t accessMode, le_result_t *resultPtr) |
FILE * | le_atomFile_CreateStream (const char *pathNamePtr, le_flock_AccessMode_t accessMode, le_flock_CreateMode_t createMode, mode_t permissions, le_result_t *resultPtr) |
FILE * | le_atomFile_TryOpenStream (const char *pathNamePtr, le_flock_AccessMode_t accessMode, le_result_t *resultPtr) |
FILE * | le_atomFile_TryCreateStream (const char *pathNamePtr, le_flock_AccessMode_t accessMode, le_flock_CreateMode_t createMode, mode_t permissions, le_result_t *resultPtr) |
void | le_atomFile_CancelStream (FILE *fileStreamPtr) |
le_result_t | le_atomFile_CloseStream (FILE *fileStreamPtr) |
le_result_t | le_atomFile_Delete (const char *pathNamePtr) |
le_result_t | le_atomFile_TryDelete (const char *pathNamePtr) |
Detailed Description
Legato Atomic File Operation API include file.
Copyright (C) Sierra Wireless Inc.
Function Documentation
void le_atomFile_Cancel | ( | int | fd | ) |
Cancels all changes and closes the file descriptor.
- Parameters
-
[in] fd The file descriptor to close.
void le_atomFile_CancelStream | ( | FILE * | fileStreamPtr | ) |
Cancels all changes and closes the file stream.
- Parameters
-
[in] fileStreamPtr File stream pointer to close
le_result_t le_atomFile_Close | ( | int | fd | ) |
Commits all changes and closes the file descriptor. No need to close the file descriptor again if this function returns error (i.e. file descriptor is closed in both success and error scenario).
- Returns
- LE_OK if successful. LE_FAULT if there was an error
- Parameters
-
[in] fd The file descriptor to close.
le_result_t le_atomFile_CloseStream | ( | FILE * | fileStreamPtr | ) |
Commits all changes and closes the file stream. No need to close the file stream again if this function returns error (i.e. file stream is closed in both success and error scenario).
- Returns
- LE_OK if successful. LE_FAULT if there was an error
- Parameters
-
[in] fileStreamPtr File stream pointer to close
int le_atomFile_Create | ( | const char * | pathNamePtr, |
le_flock_AccessMode_t | accessMode, | ||
le_flock_CreateMode_t | createMode, | ||
mode_t | permissions | ||
) |
Creates and opens file for atomic operation.
If the file does not exist it will be created with the file permissions specified in the argument permissions (modified by the process's umask). Refer to the POSIX function open(2) for details of mode_t:
http://man7.org/linux/man-pages/man2/open.2.html
The file can be opened for reading, writing or both as specified in the accessMode argument. Parameter accessMode specifies the lock to be applied on the file (read lock will be applied for LE_FLOCK_READ and write lock will be placed for all other cases).
This is a blocking call. It will block until it can create and open the target file with specified parameters(i.e. accessMode, createMode, permissions).
- Returns
- A file descriptor if successful. LE_DUPLICATE if the file already exists and LE_FLOCK_FAIL_IF_EXIST is specified in createMode LE_FAULT if there was an error.
- Note
- File must be closed using le_atomFile_Close() or le_atomFile_Cancel() function.
- Parameters
-
[in] pathNamePtr Path of the file to open [in] accessMode Access mode to open the file. [in] createMode Action to take if the file already exists. [in] permissions File permissions used when creating the file. See the function header comments for more details.
FILE* le_atomFile_CreateStream | ( | const char * | pathNamePtr, |
le_flock_AccessMode_t | accessMode, | ||
le_flock_CreateMode_t | createMode, | ||
mode_t | permissions, | ||
le_result_t * | resultPtr | ||
) |
Creates and open a file via C standard library buffered file stream for atomic operation.
If the file does not exist it will be created with the file permissions specified in the argument permissions (modified by the process's umask). Refer to the POSIX function open(2) for details of mode_t:
http://man7.org/linux/man-pages/man2/open.2.html
The file can be opened for reading, writing or both as specified in the accessMode argument. Parameter accessMode specifies the lock to be applied on the file (read lock will be applied for LE_FLOCK_READ and write lock will be placed for all other cases).
This is a blocking call. It will block until it can create and open the target file with specified parameters(i.e. accessMode, createMode, permissions).
If there was an error NULL is returned and resultPtr is set to:
- LE_DUPLICATE if the file already exists and LE_FLOCK_FAIL_IF_EXIST is specified in createMode.
- LE_FAULT if there was an error.
- Returns
- Buffered file stream handle to the file if successful. NULL if there was an error.
- Note
- Stream must be closed using le_atomFile_CloseStream() or le_atomFile_CancelStream() function.
- Parameters
-
[in] pathNamePtr Path of the file to open [in] accessMode Access mode to open the file. [in] createMode Action to take if the file already exists. [in] permissions File permissions used when creating the file. See the function header comments for more details. [out] resultPtr Pointer to result code. This can be NULL if the result code is not wanted.
le_result_t le_atomFile_Delete | ( | const char * | pathNamePtr | ) |
Atomically deletes a file. This function also ensures safe deletion of file (i.e. if any other process/thread is using the file by acquiring file lock, it won't delete the file unless lock is released). This is a blocking call. It will block until lock on file is released.
- Returns
- LE_OK if successful. LE_NOT_FOUND if file doesn't exists. LE_FAULT if there was an error.
- Parameters
-
[in] pathNamePtr Path of the file to delete
int le_atomFile_Open | ( | const char * | pathNamePtr, |
le_flock_AccessMode_t | accessMode | ||
) |
Opens an existing file for atomic access operation.
The file can be open for reading, writing or both as specified in the accessMode argument. Parameter accessMode specifies the lock to be applied on the file (read lock will be applied for LE_FLOCK_READ and write lock will be placed for all other cases).
This is a blocking call. It will block until it can open the target file with specified accessMode.
- Returns
- A file descriptor if successful. LE_NOT_FOUND if the file does not exist. LE_FAULT if there was an error.
- Note
- File must be closed using le_atomFile_Close() or le_atomFile_Cancel() function.
- Parameters
-
[in] pathNamePtr Path of the file to open [in] accessMode Access mode to open the file.
FILE* le_atomFile_OpenStream | ( | const char * | pathNamePtr, |
le_flock_AccessMode_t | accessMode, | ||
le_result_t * | resultPtr | ||
) |
Opens an existing file via C standard library buffered file stream for atomic operation.
The file can be open for reading, writing or both as specified in the accessMode argument. Parameter accessMode specifies the lock to be applied on the file (read lock will be applied for LE_FLOCK_READ and write lock will be placed for all other cases).
This is a blocking call. It will block until it can open the target file with specified accessMode.
If there was an error NULL is returned and resultPtr is set to:
- LE_NOT_FOUND if the file does not exist.
- LE_FAULT if there was an error.
- Returns
- Buffered file stream handle to the file if successful. NULL if there was an error.
- Note
- Stream must be closed using le_atomFile_CloseStream() or le_atomFile_CancelStream() function.
- Parameters
-
[in] pathNamePtr Path of the file to open [in] accessMode Access mode to open the file. [out] resultPtr Pointer to result code. This can be NULL if the result code is not wanted.
int le_atomFile_TryCreate | ( | const char * | pathNamePtr, |
le_flock_AccessMode_t | accessMode, | ||
le_flock_CreateMode_t | createMode, | ||
mode_t | permissions | ||
) |
Same as le_atomFile_Create()
except that it is non-blocking function and it will fail and return LE_WOULD_BLOCK immediately if target file has incompatible lock.
- Returns
- A file descriptor if successful. LE_DUPLICATE if the file already exists and LE_FLOCK_FAIL_IF_EXIST is specified in createMode LE_WOULD_BLOCK if there is already an incompatible lock on the file. LE_FAULT if there was an error.
- Note
- File must be closed using le_atomFile_Close() or le_atomFile_Cancel() function.
- Parameters
-
[in] pathNamePtr Path of the file to open [in] accessMode Access mode to open the file. [in] createMode Action to take if the file already exists. [in] permissions File permissions used when creating the file.
FILE* le_atomFile_TryCreateStream | ( | const char * | pathNamePtr, |
le_flock_AccessMode_t | accessMode, | ||
le_flock_CreateMode_t | createMode, | ||
mode_t | permissions, | ||
le_result_t * | resultPtr | ||
) |
Same as le_atomFile_CreateStream()
except that it is non-blocking function and it will fail and return LE_WOULD_BLOCK immediately if target file has incompatible lock.
If there was an error NULL is returned and resultPtr is set to:
- LE_DUPLICATE if the file already exists and LE_FLOCK_FAIL_IF_EXIST is specified in createMode.
- LE_WOULD_BLOCK if there is already an incompatible lock on the file.
- LE_FAULT if there was an error.
- Returns
- Buffered file stream handle to the file if successful. NULL if there was an error.
- Note
- Stream must be closed using le_atomFile_CloseStream() or le_atomFile_CancelStream() function.
- Parameters
-
[in] pathNamePtr Path of the file to open [in] accessMode Access mode to open the file. [in] createMode Action to take if the file already exists. [in] permissions File permissions used when creating the file. [out] resultPtr Pointer to result code.
le_result_t le_atomFile_TryDelete | ( | const char * | pathNamePtr | ) |
Same as le_atomFile_Delete()
except that it is non-blocking function and it will fail and return LE_WOULD_BLOCK immediately if target file is locked.
- Returns
- LE_OK if successful. LE_NOT_FOUND if file doesn't exists. LE_WOULD_BLOCK if file is already locked (i.e. someone is using it). LE_FAULT if there was an error.
- Parameters
-
[in] pathNamePtr Path of the file to delete
int le_atomFile_TryOpen | ( | const char * | pathNamePtr, |
le_flock_AccessMode_t | accessMode | ||
) |
Same as le_atomFile_Open()
except that it is non-blocking function and it will fail and return LE_WOULD_BLOCK immediately if target file has incompatible lock.
- Returns
- A file descriptor if successful. LE_NOT_FOUND if the file does not exist. LE_WOULD_BLOCK if there is already an incompatible lock on the file. LE_FAULT if there was an error.
- Note
- File must be closed using le_atomFile_Close() or le_atomFile_Cancel() function.
- Parameters
-
[in] pathNamePtr Path of the file to open [in] accessMode Access mode to open the file.
FILE* le_atomFile_TryOpenStream | ( | const char * | pathNamePtr, |
le_flock_AccessMode_t | accessMode, | ||
le_result_t * | resultPtr | ||
) |
Same as le_atomFile_OpenStream()
except that it is non-blocking function and it will fail and return LE_WOULD_BLOCK immediately if target file has incompatible lock.
If there was an error NULL is returned and resultPtr is set to:
- LE_NOT_FOUND if the file does not exist.
- LE_WOULD_BLOCK if there is already an incompatible lock on the file.
- LE_FAULT if there was an error.
- Returns
- Buffered file stream handle to the file if successful. NULL if there was an error.
- Note
- Stream must be closed using le_atomFile_CloseStream() or le_atomFile_CancelStream() function.
- Parameters
-
[in] pathNamePtr Path of the file to open [in] accessMode Access mode to open the file. [out] resultPtr Pointer to result code.