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.

Function Documentation

void le_atomFile_Cancel ( int  fd)

Cancels all changes and closes the file descriptor.

Parameters
[in]fdThe file descriptor to close.
void le_atomFile_CancelStream ( FILE *  fileStreamPtr)

Cancels all changes and closes the file stream.

Parameters
[in]fileStreamPtrFile 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]fdThe 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]fileStreamPtrFile 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]pathNamePtrPath of the file to open
[in]accessModeAccess mode to open the file.
[in]createModeAction to take if the file already exists.
[in]permissionsFile 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]pathNamePtrPath of the file to open
[in]accessModeAccess mode to open the file.
[in]createModeAction to take if the file already exists.
[in]permissionsFile permissions used when creating the file. See the function header comments for more details.
[out]resultPtrPointer 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]pathNamePtrPath 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]pathNamePtrPath of the file to open
[in]accessModeAccess 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]pathNamePtrPath of the file to open
[in]accessModeAccess mode to open the file.
[out]resultPtrPointer 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]pathNamePtrPath of the file to open
[in]accessModeAccess mode to open the file.
[in]createModeAction to take if the file already exists.
[in]permissionsFile 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]pathNamePtrPath of the file to open
[in]accessModeAccess mode to open the file.
[in]createModeAction to take if the file already exists.
[in]permissionsFile permissions used when creating the file.
[out]resultPtrPointer 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]pathNamePtrPath 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]pathNamePtrPath of the file to open
[in]accessModeAccess 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]pathNamePtrPath of the file to open
[in]accessModeAccess mode to open the file.
[out]resultPtrPointer to result code.