All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
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

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.

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]fdFile 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]pathNamePtrPointer to the path name 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_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]pathNamePtrPointer to the path name 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.
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]pathNamePtrPointer to the path name of the file to open.
[in]accessModeAccess 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]pathNamePtrPointer to the path name 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_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]pathNamePtrPointer to the path name 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_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]pathNamePtrPointer to the path name 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.
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]pathNamePtrPointer to the path name of the file to open.
[in]accessModeAccess 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]pathNamePtrPointer to the path name of the file to open.
[in]accessModeAccess mode to open the file.
[out]resultPtrPointer to result code.