## camel-lock

camel-lock

## Synopsis

    #define             CAMEL_LOCK_DOT_RETRY
    #define             CAMEL_LOCK_DOT_DELAY
    #define             CAMEL_LOCK_DOT_STALE
    #define             CAMEL_LOCK_RETRY
    #define             CAMEL_LOCK_DELAY
    enum                CamelLockType;
    gint                camel_lock_dot                      (const gchar *path,
                                                             CamelException *ex);
    gint                camel_lock_fcntl                    (gint fd,
                                                             CamelLockType type,
                                                             CamelException *ex);
    gint                camel_lock_flock                    (gint fd,
                                                             CamelLockType type,
                                                             CamelException *ex);
    void                camel_unlock_dot                    (const gchar *path);
    void                camel_unlock_fcntl                  (gint fd);
    void                camel_unlock_flock                  (gint fd);
    gint                camel_lock_folder                   (const gchar *path,
                                                             gint fd,
                                                             CamelLockType type,
                                                             CamelException *ex);
    void                camel_unlock_folder                 (const gchar *path,
                                                             gint fd);

## Description

## Details

### CAMEL_LOCK_DOT_RETRY

    #define CAMEL_LOCK_DOT_RETRY (5) /* number of times to retry lock */

### CAMEL_LOCK_DOT_DELAY

    #define CAMEL_LOCK_DOT_DELAY (2) /* delay between locking retries */

### CAMEL_LOCK_DOT_STALE

    #define CAMEL_LOCK_DOT_STALE (60) /* seconds before a lock becomes stale */

### CAMEL_LOCK_RETRY

    #define CAMEL_LOCK_RETRY (5) /* number of times to retry lock */

### CAMEL_LOCK_DELAY

    #define CAMEL_LOCK_DELAY (2) /* delay between locking retries */

### enum CamelLockType

    typedef enum {
    	CAMEL_LOCK_READ,
    	CAMEL_LOCK_WRITE
    } CamelLockType;

### camel_lock_dot ()

    gint                camel_lock_dot                      (const gchar *path,
                                                             CamelException *ex);

Create an exclusive lock using .lock semantics. All locks are equivalent to write locks (exclusive).

Returns : | -1 on error, sets `ex` appropriately.

### camel_lock_fcntl ()

    gint                camel_lock_fcntl                    (gint fd,
                                                             CamelLockType type,
                                                             CamelException *ex);

Create a lock using fcntl(2).

`type` is CAMEL_LOCK_WRITE or CAMEL_LOCK_READ, to create exclusive or shared read locks

Returns : | -1 on error.

### camel_lock_flock ()

    gint                camel_lock_flock                    (gint fd,
                                                             CamelLockType type,
                                                             CamelException *ex);

Create a lock using flock(2).

`type` is CAMEL_LOCK_WRITE or CAMEL_LOCK_READ, to create exclusive or shared read locks

Returns : | -1 on error.

### camel_unlock_dot ()

    void                camel_unlock_dot                    (const gchar *path);

Attempt to unlock a .lock lock.

### camel_unlock_fcntl ()

    void                camel_unlock_fcntl                  (gint fd);

Unlock an fcntl lock.

### camel_unlock_flock ()

    void                camel_unlock_flock                  (gint fd);

Unlock an flock lock.

### camel_lock_folder ()

    gint                camel_lock_folder                   (const gchar *path,
                                                             gint fd,
                                                             CamelLockType type,
                                                             CamelException *ex);

Attempt to lock a folder, multiple attempts will be made using all locking strategies available.

`path` : | Path to the file to lock (used for .locking only).
`fd` : | Open file descriptor of the right type to lock.
`type` : | Type of lock, CAMEL_LOCK_READ or CAMEL_LOCK_WRITE.
Returns : | -1 on error, `ex` will describe the locking system that failed.

### camel_unlock_folder ()

    void                camel_unlock_folder                 (const gchar *path,
                                                             gint fd);

Free a lock on a folder.

`path` : | Filename of folder.
`fd` : | Open descrptor on which locks were placed.