Filesystem locks

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. More...

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. More...
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. More...
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. More...
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. More...
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. More...
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()): More...

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 2330 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_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.