# Filesystem locks
[Filesystem interaction subsystem]

## Typedefs
typedef svn_error_t *(* | svn_fs_get_locks_callback_t )(void *baton, svn_lock_t *lock, apr_pool_t *pool)
| The type of a lock discovery callback function.
## Functions
svn_error_t * | svn_fs_lock (svn_lock_t **lock, svn_fs_t *fs, const char *path, const char *token, const char *comment, svn_boolean_t is_dav_comment, apr_time_t expiration_date, svn_revnum_t current_rev, svn_boolean_t steal_lock, apr_pool_t *pool)
| A lock represents one user's exclusive right to modify a path in a filesystem.
svn_error_t * | svn_fs_generate_lock_token (const char **token, svn_fs_t *fs, apr_pool_t *pool)
| Generate a unique lock-token using fs.
svn_error_t * | svn_fs_unlock (svn_fs_t *fs, const char *path, const char *token, svn_boolean_t break_lock, apr_pool_t *pool)
| Remove the lock on path represented by token in fs.
svn_error_t * | svn_fs_get_lock (svn_lock_t **lock, svn_fs_t *fs, const char *path, apr_pool_t *pool)
| If path is locked in fs, set *lock to an svn_lock_t which represents the lock, allocated in pool.
svn_error_t * | svn_fs_get_locks2 (svn_fs_t *fs, const char *path, svn_depth_t depth, svn_fs_get_locks_callback_t get_locks_func, void *get_locks_baton, apr_pool_t *pool)
| Report locks on or below path in fs using the get_locks_func / get_locks_baton.
SVN_DEPRECATED svn_error_t * | svn_fs_get_locks (svn_fs_t *fs, const char *path, svn_fs_get_locks_callback_t get_locks_func, void *get_locks_baton, apr_pool_t *pool)
| Similar to svn_fs_get_locks2(), but with depth always passed as svn_depth_infinity, and with the following known problem (which is not present in svn_fs_get_locks2()):

## Detailed Description

Since:
  New in 1.2.

## Typedef Documentation

typedef svn_error_t*(* svn_fs_get_locks_callback_t)(void *baton, svn_lock_t *lock, apr_pool_t *pool)

The type of a lock discovery callback function.

baton is the value specified in the call to svn_fs_get_locks(); the filesystem passes it through to the callback. lock is a lock structure. pool is a temporary subpool for use by the callback implementation -- it is cleared after invocation of the callback.

Definition at line 2128 of file svn_fs.h.

## Function Documentation

svn_error_t* svn_fs_generate_lock_token | ( | const char ** | token,
|  | svn_fs_t * | fs,
|  | apr_pool_t * | pool |
| ) |  |  |

Generate a unique lock-token using fs.

Return in *token, allocated in pool.

This can be used in to populate lock->token before calling svn_fs_attach_lock().

svn_error_t* svn_fs_get_lock | ( | svn_lock_t ** | lock,
|  | svn_fs_t * | fs,
|  | const char * | path,
|  | apr_pool_t * | pool |
| ) |  |  |

If path is locked in fs, set *lock to an svn_lock_t which represents the lock, allocated in pool.

If path is not locked, set *lock to NULL.

SVN_DEPRECATED svn_error_t* svn_fs_get_locks | ( | svn_fs_t * | fs,
|  | const char * | path,
|  | svn_fs_get_locks_callback_t | get_locks_func,
|  | void * | get_locks_baton,
|  | apr_pool_t * | pool |
| ) |  |  |

Similar to svn_fs_get_locks2(), but with depth always passed as svn_depth_infinity, and with the following known problem (which is not present in svn_fs_get_locks2()):

Note:
  On Berkeley-DB-backed filesystems in Subversion 1.6 and prior, the get_locks_func callback will be invoked from within a Berkeley-DB transaction trail. Implementors of the callback are, as a result, forbidden from calling any svn_fs API functions which might themselves attempt to start a new Berkeley DB transaction (which is most of this svn_fs API). Yes, this is a nasty implementation detail to have to be aware of.

Deprecated:
  Provided for backward compatibility with the 1.6 API.

svn_error_t* svn_fs_get_locks2 | ( | svn_fs_t * | fs,
|  | const char * | path,
|  | svn_depth_t | depth,
|  | svn_fs_get_locks_callback_t | get_locks_func,
|  | void * | get_locks_baton,
|  | apr_pool_t * | pool |
| ) |  |  |

Report locks on or below path in fs using the get_locks_func / get_locks_baton.

Use pool for necessary allocations.

depth limits the reported locks to those associated with paths within the specified depth of path, and must be one of the following values: svn_depth_empty, svn_depth_files, svn_depth_immediates, or svn_depth_infinity.

If the get_locks_func callback implementation returns an error, lock iteration will terminate and that error will be returned by this function.

Note:
  Over the course of this function's invocation, locks might be added, removed, or modified by concurrent processes. Callers need to anticipate and gracefully handle the transience of this information.

Since:
  New in 1.7.

svn_error_t* svn_fs_lock | ( | svn_lock_t ** | lock,
|  | svn_fs_t * | fs,
|  | const char * | path,
|  | const char * | token,
|  | const char * | comment,
|  | svn_boolean_t | is_dav_comment,
|  | apr_time_t | expiration_date,
|  | svn_revnum_t | current_rev,
|  | svn_boolean_t | steal_lock,
|  | apr_pool_t * | pool |
| ) |  |  |

A lock represents one user's exclusive right to modify a path in a filesystem.

In order to create or destroy a lock, a username must be associated with the filesystem's access context (see svn_fs_access_t).

When a lock is created, a 'lock-token' is returned. The lock-token is a unique URI that represents the lock (treated as an opaque string by the client), and is required to make further use of the lock (including removal of the lock.) A lock-token can also be queried to return a svn_lock_t structure that describes the details of the lock. lock-tokens must not contain any newline character, mainly due to the serialization for tokens for pre-commit hook.

Locks are not secret; anyone can view existing locks in a filesystem. Locks are not omnipotent: they can broken and stolen by people who don't "own" the lock. (Though admins can tailor a custom break/steal policy via libsvn_repos pre-lock hook script.)

Locks can be created with an optional expiration date. If a lock has an expiration date, then the act of fetching/reading it might cause it to automatically expire, returning either nothing or an expiration error (depending on the API). Lock path in fs, and set *lock to a lock representing the new lock, allocated in pool.

Warning:
  You may prefer to use svn_repos_fs_lock() instead, which see.

fs must have a username associated with it (see svn_fs_access_t), else return SVN_ERR_FS_NO_USER. Set the 'owner' field in the new lock to the fs username.

comment is optional: it's either an xml-escapable UTF8 string which describes the lock, or it is `NULL`.

is_dav_comment describes whether the comment was created by a generic DAV client; only mod_dav_svn's autoversioning feature needs to use it. If in doubt, pass 0.

If path is already locked, then return SVN_ERR_FS_PATH_ALREADY_LOCKED, unless steal_lock is TRUE, in which case "steal" the existing lock, even if the FS access-context's username does not match the current lock's owner: delete the existing lock on path, and create a new one.

token is a lock token such as can be generated using svn_fs_generate_lock_token() (indicating that the caller wants to dictate the lock token used), or it is `NULL` (indicating that the caller wishes to have a new token generated by this function). If token is not `NULL`, and represents an existing lock, then path must match the path associated with that existing lock.

If expiration_date is zero, then create a non-expiring lock. Else, the lock will expire at expiration_date.

If current_rev is a valid revnum, then do an out-of-dateness check. If the revnum is less than the last-changed-revision of path (or if path doesn't exist in HEAD), return SVN_ERR_FS_OUT_OF_DATE.

Note:
  At this time, only files can be locked.

svn_error_t* svn_fs_unlock | ( | svn_fs_t * | fs,
|  | const char * | path,
|  | const char * | token,
|  | svn_boolean_t | break_lock,
|  | apr_pool_t * | pool |
| ) |  |  |

Remove the lock on path represented by token in fs.

If token doesn't point to a lock, return SVN_ERR_FS_BAD_LOCK_TOKEN. If token points to an expired lock, return SVN_ERR_FS_LOCK_EXPIRED. If fs has no username associated with it, return SVN_ERR_FS_NO_USER unless break_lock is specified.

If token points to a lock, but the username of fs's access context doesn't match the lock's owner, return SVN_ERR_FS_LOCK_OWNER_MISMATCH. If break_lock is TRUE, however, don't return error; allow the lock to be "broken" in any case. In the latter case, token shall be `NULL`.

Use pool for temporary allocations.

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines