Filesystem locks

Typedefs
typedef struct svn_fs_lock_target_t	svn_fs_lock_target_t
	A lock represents one user's exclusive right to modify a path in a filesystem. More...
typedef svn_error_t *(*	svn_fs_lock_callback_t )(void *baton, const char *path, const svn_lock_t *lock, svn_error_t *fs_err, apr_pool_t *scratch_pool)
	The callback invoked by svn_fs_lock_many() and svn_fs_unlock_many(). More...
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_fs_lock_target_t *	svn_fs_lock_target_create (const char *token, svn_revnum_t current_rev, apr_pool_t *result_pool)
	Create an svn_fs_lock_target_t allocated in result_pool. More...
void	svn_fs_lock_target_set_token (svn_fs_lock_target_t *target, const char *token)
	Update target changing the token to token, token can be NULL. More...
svn_error_t *	svn_fs_lock_many (svn_fs_t *fs, apr_hash_t *lock_targets, const char *comment, svn_boolean_t is_dav_comment, apr_time_t expiration_date, svn_boolean_t steal_lock, svn_fs_lock_callback_t lock_callback, void *lock_baton, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
	Lock the paths in lock_targets in fs. More...
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)
	Similar to svn_fs_lock_many() but locks only a single path and returns the lock in *lock, allocated in pool, or an error. 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_many (svn_fs_t *fs, apr_hash_t *unlock_targets, svn_boolean_t break_lock, svn_fs_lock_callback_t lock_callback, void *lock_baton, apr_pool_t *result_pool, apr_pool_t *scratch_pool)
	Remove the locks on the paths in unlock_targets in 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)
	Similar to svn_fs_unlock_many() but only unlocks a single path. 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 2881 of file svn_fs.h.

typedef svn_error_t*(* svn_fs_lock_callback_t)(void *baton, const char *path, const svn_lock_t *lock, svn_error_t *fs_err, apr_pool_t *scratch_pool)

The callback invoked by svn_fs_lock_many() and svn_fs_unlock_many().

path and lock are allocated in the result_pool passed to svn_fs_lock_many/svn_fs_unlock_many and so will persist beyond the callback invocation. fs_err will be cleared after the callback returns, use svn_error_dup() to preserve the error.

If the callback returns an error no further callbacks will be made and svn_fs_lock_many/svn_fs_unlock_many will return an error. The caller cannot rely on any particular order for these callbacks and cannot rely on interrupting the underlying operation by returning an error. Returning an error stops the callbacks but any locks that would have been reported in further callbacks may, or may not, still be created/released.

Since

New in 1.9.

Definition at line 2706 of file svn_fs.h.

typedef struct svn_fs_lock_target_t svn_fs_lock_target_t

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 be 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 information for use with svn_fs_lock_many() [and svn_repos_fs_...].

See Also

svn_fs_lock_target_create

Since

New in 1.9.

Definition at line 2665 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 or does not exist in HEAD, 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
	)

Similar to svn_fs_lock_many() but locks only a single path and returns the lock in *lock, allocated in pool, or an error.

Since

New in 1.2.

svn_error_t* svn_fs_lock_many	(	svn_fs_t *	fs,
		apr_hash_t *	lock_targets,
		const char *	comment,
		svn_boolean_t	is_dav_comment,
		apr_time_t	expiration_date,
		svn_boolean_t	steal_lock,
		svn_fs_lock_callback_t	lock_callback,
		void *	lock_baton,
		apr_pool_t *	result_pool,
		apr_pool_t *	scratch_pool
	)

Lock the paths in lock_targets in fs.

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

The paths to be locked are passed as the const char * keys of the lock_targets hash. The hash values are svn_fs_lock_target_t * and provide the token and current_rev for each path. The 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 the token is not NULL, and represents an existing lock, then the path must match the path associated with that existing lock. 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 the path (or if the path doesn't exist in HEAD), yield an SVN_ERR_FS_OUT_OF_DATE error for this path.

If a path is already locked, then yield 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 the path, and create a new one.

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

For each path in lock_targets lock_callback will be invoked passing lock_baton and the lock and error that apply to path. lock_callback can be NULL in which case it is not called and any errors that would have been passed to the callback are not reported.

The lock and path passed to lock_callback will be allocated in result_pool. Use scratch_pool for temporary allocations.

Note

At this time, only files can be locked.

This function is not atomic. If it returns an error, some targets may remain unlocked while others may have been locked.

You probably don't want to use this directly. Take a look at svn_repos_fs_lock_many() instead.

Since

New in 1.9.

svn_fs_lock_target_t* svn_fs_lock_target_create	(	const char *	token,
		svn_revnum_t	current_rev,
		apr_pool_t *	result_pool
	)

Create an svn_fs_lock_target_t allocated in result_pool.

token can be NULL and current_rev can be SVN_INVALID_REVNUM.

The token is not duplicated and so must have a lifetime at least as long as the returned target object.

Since

New in 1.9.

void svn_fs_lock_target_set_token	(	svn_fs_lock_target_t *	target,
		const char *	token
	)

Update target changing the token to token, token can be NULL.

The token is not duplicated and so must have a lifetime at least as long as target.

Since

New in 1.9.

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
	)

Similar to svn_fs_unlock_many() but only unlocks a single path.

Since

New in 1.2.

svn_error_t* svn_fs_unlock_many	(	svn_fs_t *	fs,
		apr_hash_t *	unlock_targets,
		svn_boolean_t	break_lock,
		svn_fs_lock_callback_t	lock_callback,
		void *	lock_baton,
		apr_pool_t *	result_pool,
		apr_pool_t *	scratch_pool
	)

Remove the locks on the paths in unlock_targets in fs.

The paths to be unlocked are passed as const char * keys of the unlock_targets hash with the corresponding lock tokens as const char * values. If the token doesn't point to a lock, yield an SVN_ERR_FS_BAD_LOCK_TOKEN error for this path. If the token points to an expired lock, yield an SVN_ERR_FS_LOCK_EXPIRED error for this path. If fs has no username associated with it, yield an SVN_ERR_FS_NO_USER unless break_lock is specified.

If the token points to a lock, but the username of fs's access context doesn't match the lock's owner, yield an 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, the token shall be NULL.

For each path in unlock_targets lock_callback will be invoked passing lock_baton and error that apply to path. The lock passed to the callback will be NULL. lock_callback can be NULL in which case it is not called and any errors that would have been passed to the callback are not reported.

The path passed to lock_callback will be allocated in result_pool. Use scratch_pool for temporary allocations.

Note

This function is not atomic. If it returns an error, some targets may remain locked while others may have been unlocked.

You probably don't want to use this directly. Take a look at svn_repos_fs_unlock_many() instead.

Since

New in 1.9.