#include "le_fileLock.h"

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

◆ le_atomFile_Cancel()

void le_atomFile_Cancel ( int fd )

Cancels all changes and closes the file descriptor.

Parameters

[in] fd The file descriptor to close.

◆ le_atomFile_CancelStream()

void le_atomFile_CancelStream ( FILE * fileStreamPtr )

Cancels all changes and closes the file stream.

Parameters

[in] fileStreamPtr File stream pointer to close

◆ le_atomFile_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_atomFile_CloseStream()

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

◆ le_atomFile_Create()

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.

◆ le_atomFile_CreateStream()

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_atomFile_Delete()

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

◆ le_atomFile_Open()

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.

◆ le_atomFile_OpenStream()

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.

◆ le_atomFile_TryCreate()

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.

◆ le_atomFile_TryCreateStream()

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_atomFile_TryDelete()

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

◆ le_atomFile_TryOpen()

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.

◆ le_atomFile_TryOpenStream()

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.

/ Build Apps

le_atomFile.h File Reference

Functions

Detailed Description

Function Documentation

◆ le_atomFile_Cancel()

◆ le_atomFile_CancelStream()

◆ le_atomFile_Close()

◆ le_atomFile_CloseStream()

◆ le_atomFile_Create()

◆ le_atomFile_CreateStream()

◆ le_atomFile_Delete()

◆ le_atomFile_Open()

◆ le_atomFile_OpenStream()

◆ le_atomFile_TryCreate()

◆ le_atomFile_TryCreateStream()

◆ le_atomFile_TryDelete()

◆ le_atomFile_TryOpen()

◆ le_atomFile_TryOpenStream()