le_fileLock.h File Reference

Go to the source code of this file.

Enumerations
enum	le_flock_AccessMode_t {   LE_FLOCK_READ, LE_FLOCK_WRITE, LE_FLOCK_APPEND, LE_FLOCK_READ_AND_WRITE,   LE_FLOCK_READ_AND_APPEND }
enum	le_flock_CreateMode_t { LE_FLOCK_OPEN_IF_EXIST, LE_FLOCK_REPLACE_IF_EXIST, LE_FLOCK_FAIL_IF_EXIST }

Functions
int	le_flock_Open (const char *pathNamePtr, le_flock_AccessMode_t accessMode)
int	le_flock_Create (const char *pathNamePtr, le_flock_AccessMode_t accessMode, le_flock_CreateMode_t createMode, mode_t permissions)
int	le_flock_TryOpen (const char *pathNamePtr, le_flock_AccessMode_t accessMode)
int	le_flock_TryCreate (const char *pathNamePtr, le_flock_AccessMode_t accessMode, le_flock_CreateMode_t createMode, mode_t permissions)
void	le_flock_Close (int fd)
FILE *	le_flock_OpenStream (const char *pathNamePtr, le_flock_AccessMode_t accessMode, le_result_t *resultPtr)
FILE *	le_flock_CreateStream (const char *pathNamePtr, le_flock_AccessMode_t accessMode, le_flock_CreateMode_t createMode, mode_t permissions, le_result_t *resultPtr)
FILE *	le_flock_TryOpenStream (const char *pathNamePtr, le_flock_AccessMode_t accessMode, le_result_t *resultPtr)
FILE *	le_flock_TryCreateStream (const char *pathNamePtr, le_flock_AccessMode_t accessMode, le_flock_CreateMode_t createMode, mode_t permissions, le_result_t *resultPtr)
void	le_flock_CloseStream (FILE *fileStreamPtr)

Detailed Description

Legato File Locking API include file.

Copyright (C) Sierra Wireless, Inc. 2013. All rights reserved. Use of this work is subject to license.

Enumeration Type Documentation

enum le_flock_AccessMode_t

File access modes.

Note

When writing to a file, the writes are always appended to the end of the file by default. When reading from a file, the reads always starts at the beginning of the file by default.

Enumerator
LE_FLOCK_READ	Opens the file for reading.
LE_FLOCK_WRITE	Opens the file for writing.
LE_FLOCK_APPEND	Opens the file for writing. Writes will be appended to the end of the file.
LE_FLOCK_READ_AND_WRITE	Opens the file for reading and writing.
LE_FLOCK_READ_AND_APPEND	Opens the file for reading and writing. Writes will be appended to the end of the file.

enum le_flock_CreateMode_t

File creation modes specify the action to take when creating a file that already exists.

Enumerator
LE_FLOCK_OPEN_IF_EXIST	Opens the file if it already exists.
LE_FLOCK_REPLACE_IF_EXIST	Replaces the file if it already exists.
LE_FLOCK_FAIL_IF_EXIST	Fails if the file already exists.

Function Documentation

void le_flock_Close

(

int

fd

)

Closes the file and releases the lock.

Parameters

[in]

fd

File descriptor of the file to close.

void le_flock_CloseStream

(

FILE *

fileStreamPtr

)

Closes the file stream and releases the lock.

int le_flock_Create	(	const char *	pathNamePtr,
		le_flock_AccessMode_t	accessMode,
		le_flock_CreateMode_t	createMode,
		mode_t	permissions
	)

Creates, opens and locks file.

If the file does not exist, it will be created with the file permissions specified in the arugment 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

If the file already exists, then this function will either replace the existing file, open the existing file or fail depending on the createMode argument. The permissions argument is ignored if the file already exists.

The file can be opened for reading, writing or both as specified in the accessMode argument. If accessMode is either LE_FLOCK_WRITE or LE_FLOCK_READ_AND_WRITE, a write lock will be placed on the file, otherwise a read lock will be placed on the file.

If attempting to lock a file that already has an incompatible lock on it, this function will block until the lock can be obtained. This function may block even if it creates the file because creating the file and locking it is not atomic.

Returns

File descriptor to the file specified in pathNamePtr. LE_DUPLICATE if the file already exists and LE_FLOCK_FAIL_IF_EXIST is specified in createMode LE_FAULT if there was an error.

Parameters

[in]	pathNamePtr	Pointer to the path name 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_flock_CreateStream	(	const char *	pathNamePtr,
		le_flock_AccessMode_t	accessMode,
		le_flock_CreateMode_t	createMode,
		mode_t	permissions,
		le_result_t *	resultPtr
	)

Creates a file, locks it and opens a C standard library buffered file stream to it.

If the file does not exist it will be created with the file permissions specified in the arugment 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

If the file already exists then this function will either replace the existing file, open the existing file or fail depending on the createMode argument.

The file can be opened for reading, writing or both as specified in the accessMode argument. If accessMode is either LE_FLOCK_WRITE or LE_FLOCK_READ_AND_WRITE then a write lock will be placed on the file, otherwise a read lock will be placed on the file.

If attempting to lock a file that already has an incompatible lock on it this function will block until the lock can be obtained. This function may block even if it creates the file because creating the file and locking it is not atomic.

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.

Parameters

[in]	pathNamePtr	Pointer to the path name 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.

int le_flock_Open	(	const char *	pathNamePtr,
		le_flock_AccessMode_t	accessMode
	)

Opens and locks an existing file.

The file can be open for reading, writing or both as specified in the accessMode argument. If accessMode is either LE_FLOCK_WRITE or LE_FLOCK_READ_AND_WRITE then a write lock will be placed on the file, otherwise a read lock will be placed on the file.

If attempting to lock a file that already has an incompatible lock on it this function will block until the lock can be obtained.

Returns

File descriptor to the file specified in pathNamePtr. LE_NOT_FOUND if the file does not exist. LE_FAULT if there was an error.

Parameters

[in]	pathNamePtr	Pointer to the path name of the file to open.
[in]	accessMode	Access mode to open the file.

FILE* le_flock_OpenStream	(	const char *	pathNamePtr,
		le_flock_AccessMode_t	accessMode,
		le_result_t *	resultPtr
	)

Locks an existing file and opens a C standard library buffered file stream to it.

The file can be open for reading, writing or both read and write as specified in the accessMode argument. If accessMode is either LE_FLOCK_WRITE or LE_FLOCK_READ_AND_WRITE then a write lock will be placed on the file, otherwise a read lock will be placed on the file.

If attempting to lock a file that already has an incompatible lock on it, this function will block until the lock can be obtained.

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.

Parameters

[in]	pathNamePtr	Pointer to the path name 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_flock_TryCreate	(	const char *	pathNamePtr,
		le_flock_AccessMode_t	accessMode,
		le_flock_CreateMode_t	createMode,
		mode_t	permissions
	)

Creates, opens and locks file.

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

If the file already exists, this function will either replace the existing file, open the existing file or fail depending on the createMode argument. The permissions argument is ignored if the file already exists.

The file can be opened for reading, writing or both as specified in the accessMode argument. f accessMode is either LE_FLOCK_WRITE or LE_FLOCK_READ_AND_WRITE, a write lock will be placed on the file, otherwise a read lock will be placed on the file.

If attempting to lock a file that already has an incompatible lock on it, this function will fail and return LE_WOULD_BLOCK immediately. This function may fail with LE_WOULD_BLOCK even if it creates the file because creating the file and locking it is not atomic.

Returns

File descriptor to the file specified in pathNamePtr. 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.

Parameters

[in]	pathNamePtr	Pointer to the path name 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_flock_TryCreateStream	(	const char *	pathNamePtr,
		le_flock_AccessMode_t	accessMode,
		le_flock_CreateMode_t	createMode,
		mode_t	permissions,
		le_result_t *	resultPtr
	)

Creates a file, locks it and opens a C standard library buffered file stream to it.

If the file does not exist, it will be created with the file permissions specified in the arugment 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

If the file already exists, this function will either replace the existing file, open the existing file or fail depending on the createMode argument.

The file can be opened for reading, writing or both as specified in the accessMode argument. If accessMode is either LE_FLOCK_WRITE or LE_FLOCK_READ_AND_WRITE then a write lock will be placed on the file, otherwise a read lock will be placed on the file.

If attempting to lock a file that already has an incompatible lock on it, this function will return NULL immediately and set resultPtr to LE_WOULD_BLOCK. This function may fail with LE_WOULD_BLOCK even if it creates the file because creating the file and locking it is not atomic.

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.

Parameters

[in]	pathNamePtr	Pointer to the path name 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.

int le_flock_TryOpen	(	const char *	pathNamePtr,
		le_flock_AccessMode_t	accessMode
	)

Opens and locks an existing file.

The file can be open for reading, writing or both as specified in the accessMode argument. If accessMode is either LE_FLOCK_WRITE or LE_FLOCK_READ_AND_WRITE, a write lock will be placed on the file, otherwise a read lock will be placed on the file.

If attempting to lock a file that already has an incompatible lock on it, this function will fail and return LE_WOULD_BLOCK immediately.

Returns

File descriptor to the file specified in pathNamePtr. 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.

Parameters

[in]	pathNamePtr	Pointer to the path name of the file to open.
[in]	accessMode	Access mode to open the file.

FILE* le_flock_TryOpenStream	(	const char *	pathNamePtr,
		le_flock_AccessMode_t	accessMode,
		le_result_t *	resultPtr
	)

Locks an existing file and opens a C standard library buffered file stream to it.

The file can be open for reading, writing or both read and write as specified in the accessMode argument. If accessMode is either LE_FLOCK_WRITE or LE_FLOCK_READ_AND_WRITE then a write lock will be placed on the file, otherwise a read lock will be placed on the file.

If attempting to lock a file that already has an incompatible lock on it, this function will return NULL immediately and set resultPtr to LE_WOULD_BLOCK.

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.

Parameters

[in]	pathNamePtr	Pointer to the path name of the file to open.
[in]	accessMode	Access mode to open the file.
[out]	resultPtr	Pointer to result code.