| /* svn_fs.h : interface to the Subversion filesystem |
| * |
| * ==================================================================== |
| * Copyright (c) 2000-2002 CollabNet. All rights reserved. |
| * |
| * This software is licensed as described in the file COPYING, which |
| * you should have received as part of this distribution. The terms |
| * are also available at http://subversion.tigris.org/license-1.html. |
| * If newer versions of this license are posted there, you may use a |
| * newer version instead, at your option. |
| * |
| * This software consists of voluntary contributions made by many |
| * individuals. For exact contribution history, see the revision |
| * history and logs, available at http://subversion.tigris.org/. |
| * ==================================================================== |
| */ |
| |
| /* ==================================================================== */ |
| |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif /* __cplusplus */ |
| |
| #ifndef SVN_FS_H |
| #define SVN_FS_H |
| |
| #include <apr_pools.h> |
| #include <apr_hash.h> |
| #include <apr_tables.h> |
| #include "svn_types.h" |
| #include "svn_error.h" |
| #include "svn_delta.h" |
| #include "svn_io.h" |
| |
| |
| |
| /* Opening and creating filesystems. */ |
| |
| |
| /* An object representing a Subversion filesystem. */ |
| typedef struct svn_fs_t svn_fs_t; |
| |
| |
| /* Create a new filesystem object in POOL. It doesn't refer to any |
| actual repository yet; you need to invoke svn_fs_open_* or |
| svn_fs_create_* on it for that to happen. |
| |
| NOTE: you probably don't want to use this directly, especially not |
| if it's followed immediately by a call to svn_fs_open_berkeley(). |
| Take a look at svn_repos_open() instead. */ |
| svn_fs_t *svn_fs_new (apr_pool_t *pool); |
| |
| |
| /* Free the filesystem object FS. This frees memory, closes files, |
| frees database library structures, etc. */ |
| svn_error_t *svn_fs_close_fs (svn_fs_t *fs); |
| |
| |
| /* The type of a warning callback function. BATON is the value specified |
| in the call to `svn_fs_set_warning_func'; the filesystem passes it through |
| to the callback. FMT is a printf-style format string, which tells us |
| how to interpret any successive arguments. */ |
| #ifndef SWIG |
| typedef void (*svn_fs_warning_callback_t) (void *baton, const char *fmt, ...); |
| #endif |
| |
| |
| /* Provide a callback function, WARNING, that FS should use to report |
| warning messages. To print a warning message, the filesystem will |
| call WARNING, passing it BATON, a printf-style format string, and |
| any further arguments as appropriate for the format string. |
| |
| If it's acceptable to print messages on stderr, then the function |
| `svn_handle_warning', declared in "svn_error.h", would be a |
| suitable warning function. |
| |
| By default, this is set to a function that will crash the process. |
| Dumping to stderr or /dev/tty is not acceptable default behavior |
| for server processes, since those may both be equivalent to |
| /dev/null. */ |
| void svn_fs_set_warning_func (svn_fs_t *fs, |
| svn_fs_warning_callback_t warning, |
| void *warning_baton); |
| |
| |
| |
| /* Subversion filesystems based on Berkeley DB. */ |
| |
| /* There are many possible ways to implement the Subversion filesystem |
| interface. You could implement it directly using ordinary POSIX |
| filesystem operations; you could build it using an SQL server as a |
| back end; you could build it on RCS; and so on. |
| |
| The functions on this page create filesystem objects that use |
| Berkeley DB (http://www.sleepycat.com) to store their data. |
| Berkeley DB supports transactions and recoverability, making it |
| well-suited for Subversion. |
| |
| A Berkeley DB ``environment'' is a Unix directory containing |
| database files, log files, backing files for shared memory buffers, |
| and so on --- everything necessary for a complex database |
| application. Each Subversion filesystem lives in a single Berkeley |
| DB environment. */ |
| |
| |
| /* Create a new, empty Subversion filesystem, stored in a Berkeley DB |
| environment under PATH. Make FS refer to this new filesystem. |
| FS provides the memory pool, warning function, etc. If PATH |
| exists, it must be an empty directory. */ |
| svn_error_t *svn_fs_create_berkeley (svn_fs_t *fs, const char *path); |
| |
| |
| /* Make FS refer to the Berkeley DB-based Subversion filesystem at |
| PATH. PATH must refer to a file or directory created by |
| `svn_fs_create_berkeley'. |
| |
| Only one thread may operate on any given filesystem object at once. |
| Two threads may access the same filesystem simultaneously only if |
| they open separate filesystem objects. |
| |
| NOTE: you probably don't want to use this directly, especially not |
| if it's immediately preceded by a call to svn_fs_new(). Take a |
| look at svn_repos_open() instead. */ |
| svn_error_t *svn_fs_open_berkeley (svn_fs_t *fs, const char *path); |
| |
| |
| /* Return the path to FS's repository, allocated in POOL. |
| Note: this is just what was passed to svn_fs_create_berkeley() or |
| svn_fs_open_berkeley() -- might be absolute, might not. */ |
| const char *svn_fs_berkeley_path (svn_fs_t *fs, apr_pool_t *pool); |
| |
| |
| /* Register an error handling function for Berkeley DB error messages. |
| If a Berkeley DB error occurs, the filesystem will call HANDLER |
| with two strings: an error message prefix, which will be zero, and |
| an error message. HANDLER should print it out, log it somewhere, |
| etc. |
| |
| Since Berkeley DB's error messages are sometimes much more |
| informative than the error codes the functions return, it's worth |
| calling this function and providing some kind of error message |
| handler. |
| |
| This function calls `DBENV->set_errcall', with HANDLER as the |
| `db_errcall_fcn' argument. */ |
| svn_error_t *svn_fs_set_berkeley_errcall (svn_fs_t *fs, |
| void (*handler) (const char *errpfx, |
| char *msg)); |
| |
| |
| /* Delete the Berkeley DB-based filesystem PATH. This deletes the |
| database files, log files, shared memory segments, etc. PATH should |
| refer to a file or directory created by `svn_fs_create_berkeley'. */ |
| svn_error_t *svn_fs_delete_berkeley (const char *PATH, apr_pool_t *pool); |
| |
| |
| /* Perform any necessary non-catastrophic recovery on a Berkeley |
| DB-based Subversion filesystem, stored in the environment PATH. Do |
| any necessary allocation within POOL. |
| |
| After an unexpected server exit, due to a server crash or a system |
| crash, a Subversion filesystem based on Berkeley DB needs to run |
| recovery procedures to bring the database back into a consistent |
| state and release any locks that were held by the deceased process. |
| The recovery procedures require exclusive access to the database |
| --- while they execute, no other process or thread may access the |
| database. |
| |
| In a server with multiple worker processes, like Apache, if a |
| worker process accessing the filesystem dies, you must stop the |
| other worker processes, and run recovery. Then, the other worker |
| processes can re-open the database and resume work. |
| |
| If the server exited cleanly, there is no need to run recovery, but |
| there is no harm in it, either, and it take very little time. So |
| it's a fine idea to run recovery when the server process starts, |
| before it begins handling any requests. */ |
| |
| svn_error_t *svn_fs_berkeley_recover (const char *path, |
| apr_pool_t *pool); |
| |
| |
| |
| /* Node and Node Revision ID's. */ |
| |
| /* In a Subversion filesystem, a `node' corresponds roughly to an |
| `inode' in a Unix filesystem: |
| - A node is either a file or a directory. |
| - A node's contents change over time. |
| - When you change a node's contents, it's still the same node; it's |
| just been changed. So a node's identity isn't bound to a specific |
| set of contents. |
| - If you rename a node, it's still the same node, just under a |
| different name. So a node's identity isn't bound to a particular |
| filename. |
| |
| A `node revision' refers to a node's contents at a specific point in |
| time. Changing a node's contents always creates a new revision of that |
| node. Once created, a node revision's contents never change. |
| |
| When we create a node, its initial contents are the initial revision of |
| the node. As users make changes to the node over time, we create new |
| revisions of that same node. When a user commits a change that deletes |
| a file from the filesystem, we don't delete the node, or any revision |
| of it --- those stick around to allow us to recreate prior revisions of |
| the filesystem. Instead, we just remove the reference to the node |
| from the directory. |
| |
| Within the database, we refer to nodes and node revisions using strings |
| of numbers separated by periods that look a lot like RCS revision |
| numbers. |
| |
| node_id ::= number | node_revision_id "." number |
| node_revision_id ::= node_id "." number |
| |
| So: |
| - "100" is a node id. |
| - "100.10" is a node revision id, referring to revision 10 of node 100. |
| - "100.10.3" is a node id, referring to the third branch based on |
| revision 10 of node 100. |
| - "100.10.3.4" is a node revision id, referring to revision 4 of |
| of the third branch from revision 10 of node 100. |
| And so on. |
| |
| Node revision numbers start with 1. Thus, N.1 is the first revision |
| of node N. |
| |
| Node / branch numbers start with 1. Thus, N.M.1 is the first |
| branch off of N.M. |
| |
| A directory entry identifies the file or subdirectory it refers to |
| using a node revision number --- not a node number. This means that |
| a change to a file far down in a directory hierarchy requires the |
| parent directory of the changed node to be updated, to hold the new |
| node revision ID. Now, since that parent directory has changed, its |
| parent needs to be updated. |
| |
| If a particular subtree was unaffected by a given commit, the node |
| revision ID that appears in its parent will be unchanged. When |
| doing an update, we can notice this, and ignore that entire |
| subtree. This makes it efficient to find localized changes in |
| large trees. |
| |
| Note that the number specifying a particular revision of a node is |
| unrelated to the global filesystem revision when that node revision |
| was created. So 100.10 may have been created in filesystem revision |
| 1218; 100.10.3.2 may have been created any time after 100.10; it |
| doesn't matter. |
| |
| Since revision numbers increase by one each time a delta is added, |
| we can compute how many deltas separate two related node revisions |
| simply by comparing their ID's. For example, the distance between |
| 100.10.3.2 and 100.12 is the distance from 100.10.3.2 to their |
| common ancestor, 100.10 (two deltas), plus the distance from 100.10 |
| to 100.12 (two deltas). |
| |
| However, this is kind of a kludge, since the number of deltas is |
| not necessarily an accurate indicator of how different two files |
| are --- a single delta could be a minor change, or a complete |
| replacement. Furthermore, the filesystem may decide arbitrary to |
| store a given node revision as a delta or as full text --- perhaps |
| depending on how recently the node was used --- so revision id |
| distance isn't necessarily an accurate predictor of retrieval time. |
| |
| If you have insights about how this stuff could work better, let me |
| know. I've read some of Josh MacDonald's stuff on this; his |
| discussion seems to be mostly about how to retrieve things quickly, |
| which is important, but only part of the issue. I'd like to find |
| better ways to recognize renames, and find appropriate ancestors in |
| a source tree for changed files. */ |
| |
| |
| /* Within the code, we represent node and node revision ID's as arrays |
| of integers, terminated by a -1 element. This is the type of an |
| element of a node ID. */ |
| typedef svn_revnum_t svn_fs_id_t; |
| |
| |
| |
| /* Return the distance between node revisions A and B. Return -1 if |
| they are completely unrelated. */ |
| int svn_fs_id_distance (const svn_fs_id_t *a, const svn_fs_id_t *b); |
| |
| |
| |
| /* Perform an exhaustive traversal through node-id and copy-from |
| history to determine if the nodes associated with ID1 and ID2, and |
| found in filesystem FS, are related. If so, set *RELATED to 1, |
| else to 0. Use POOL for allocations. */ |
| svn_error_t *svn_fs_check_related (int *related, |
| svn_fs_t *fs, |
| const svn_fs_id_t *id1, |
| const svn_fs_id_t *id2, |
| apr_pool_t *pool); |
| |
| |
| /* Parse the LEN bytes at DATA as a node or node revision ID. Return |
| zero if the bytes are not a properly-formed ID. A properly formed |
| ID matches the regexp: |
| |
| [0-9]+(\.[0-9]+)* |
| |
| Allocate the parsed ID in POOL. If POOL is zero, malloc the ID; we |
| need this in certain cases where we can't pass in a pool, but it's |
| generally best to use a pool whenever possible. */ |
| svn_fs_id_t *svn_fs_parse_id (const char *data, apr_size_t len, |
| apr_pool_t *pool); |
| |
| |
| /* Return a Subversion string containing the unparsed form of the node |
| or node revision id ID. Allocate the string containing the |
| unparsed form in POOL. */ |
| svn_stringbuf_t *svn_fs_unparse_id (const svn_fs_id_t *id, apr_pool_t *pool); |
| |
| |
| |
| /* Transactions. */ |
| |
| |
| /* To make a change to a Subversion filesystem: |
| - Create a transaction object, using `svn_fs_begin_txn'. |
| - Call `svn_fs_txn_root', to get the transaction's root directory. |
| - Make whatever changes you like in that tree. |
| - Commit the transaction, using `svn_fs_commit_txn'. |
| |
| The filesystem implementation guarantees that your commit will |
| either: |
| - succeed completely, so that all of the changes are committed to |
| create a new revision of the filesystem, or |
| - fail completely, leaving the filesystem unchanged. |
| |
| Until you commit the transaction, any changes you make are |
| invisible. Only when your commit succeeds do they become visible |
| to the outside world, as a new revision of the filesystem. |
| |
| If you begin a transaction, and then decide you don't want to make |
| the change after all (say, because your net connection with the |
| client disappeared before the change was complete), you can call |
| `svn_fs_abort_txn', to cancel the entire transaction; this |
| leaves the filesystem unchanged. |
| |
| The only way to change the contents of files or directories, or |
| their properties, is by making a transaction and creating a new |
| revision, as described above. Once a revision has been committed, it |
| never changes again; the filesystem interface provides no means to |
| go back and edit the contents of an old revision. Once history has |
| been recorded, it is set in stone. Clients depend on this property |
| to do updates and commits reliably; proxies depend on this property |
| to cache changes accurately; and so on. |
| |
| |
| There are two kinds of nodes in the filesystem: mutable, and |
| immutable. Revisions in the filesystem consist entirely of |
| immutable nodes, whose contents never change. A transaction in |
| progress, which the user is still constructing, uses mutable nodes |
| for those nodes which have been changed so far, and refers to |
| immutable nodes from existing revisions for portions of the tree |
| which haven't been changed yet in that transaction. |
| |
| Immutable nodes, as part of revisions, never refer to mutable |
| nodes, which are part of uncommitted transactions. Mutable nodes |
| may refer to immutable nodes, or other mutable nodes. |
| |
| Note that the terms "immutable" and "mutable" describe whether or |
| not the nodes have been changed as part of a transaction --- not |
| the permissions on the nodes they refer to. Even if you aren't |
| authorized to modify the filesystem's root directory, you might be |
| authorized to change some descendant of the root; doing so would |
| create a new mutable copy of the root directory. Mutability refers |
| to the role of the node: part of an existing revision, or part of a |
| new one. This is independent of your authorization to make changes |
| to a given node. |
| |
| |
| Transactions are actually persistent objects, stored in the |
| database. You can open a filesystem, begin a transaction, and |
| close the filesystem, and then a separate process could open the |
| filesystem, pick up the same transaction, and continue work on it. |
| When a transaction is successfully committed, it is removed from |
| the database. |
| |
| Every transaction is assigned a name. You can open a transaction |
| by name, and resume work on it, or find out the name of a |
| transaction you already have open. You can also list all the |
| transactions currently present in the database. |
| |
| Transaction names are guaranteed to contain only letters (upper- |
| and lower-case), digits, `-', and `.', from the ASCII character |
| set. */ |
| |
| |
| |
| /* The type of a Subversion transaction object. */ |
| typedef struct svn_fs_txn_t svn_fs_txn_t; |
| |
| |
| /* Begin a new transaction on the filesystem FS, based on existing |
| revision REV. Set *TXN_P to a pointer to the new transaction. |
| When committed, this transaction will create a new revision. |
| |
| Allocate the new transaction in POOL; when POOL is freed, the new |
| transaction will be closed (neither committed nor aborted). You |
| can also close the transaction explicitly, using |
| `svn_fs_close_txn'. |
| |
| >> Note: if you're building a txn for committing, you probably << |
| >> don't want to call this directly. Instead, call << |
| >> svn_repos_fs_begin_txn_for_commit(), which honors the << |
| >> repository's hook configurations. << |
| */ |
| svn_error_t *svn_fs_begin_txn (svn_fs_txn_t **txn_p, |
| svn_fs_t *fs, |
| svn_revnum_t rev, |
| apr_pool_t *pool); |
| |
| |
| /* Commit TXN. |
| |
| >> Note: you usually don't want to call this directly. << |
| >> Instead, call svn_repos_fs_commit_txn(), which honors the << |
| >> repository's hook configurations. << |
| |
| If the transaction conflicts with other changes committed to the |
| repository, return an SVN_ERR_FS_CONFLICT error. Otherwise, create |
| a new filesystem revision containing the changes made in TXN, |
| storing that new revision number in *NEW_REV, and return zero. |
| |
| If CONFLICT_P is non-zero, use it to provide details on any |
| conflicts encountered merging TXN with the most recent committed |
| revisions. If a conflict occurs, set *CONFLICT_P to the path of |
| the conflict in TXN. Otherwise, set *CONFLICT_P to null. |
| |
| If the commit succeeds, it frees TXN, and any temporary resources |
| it holds. Any root objects (see below) referring to the root |
| directory of TXN become invalid; performing any operation on them |
| other than closing them will produce an SVN_ERR_FS_DEAD_TRANSACTION |
| error. |
| |
| If the commit fails, TXN is still valid; you can make more |
| operations to resolve the conflict, or call `svn_fs_abort_txn' to |
| abort the transaction. */ |
| svn_error_t *svn_fs_commit_txn (const char **conflict_p, |
| svn_revnum_t *new_rev, |
| svn_fs_txn_t *txn); |
| |
| |
| /* Abort the transaction TXN. Any changes made in TXN are discarded, |
| and the filesystem is left unchanged. |
| |
| If the abort succeeds, it frees TXN, and any temporary resources |
| it holds. Any root objects referring to TXN's root directory |
| become invalid; performing any operation on them other than closing |
| them will produce an SVN_ERR_FS_DEAD_TRANSACTION error. */ |
| svn_error_t *svn_fs_abort_txn (svn_fs_txn_t *txn); |
| |
| |
| /* Set *NAME_P to the name of the transaction TXN, as a |
| null-terminated string. Allocate the name in POOL. */ |
| svn_error_t *svn_fs_txn_name (const char **name_p, |
| svn_fs_txn_t *txn, |
| apr_pool_t *pool); |
| |
| |
| /* Return the filesystem to which TXN belongs. */ |
| svn_fs_t *svn_fs_txn_fs (svn_fs_txn_t *txn); |
| |
| |
| /* Return TXN's pool. */ |
| apr_pool_t *svn_fs_txn_pool (svn_fs_txn_t *txn); |
| |
| |
| /* Return TXN's base revision. If TXN's base root id is an mutable |
| node, return 0. */ |
| svn_revnum_t svn_fs_txn_base_revision (svn_fs_txn_t *txn); |
| |
| |
| |
| /* Open the transaction named NAME in the filesystem FS. Set *TXN to |
| the transaction. |
| |
| If there is no such transaction, SVN_ERR_FS_NO_SUCH_TRANSACTION is |
| the error returned. |
| |
| Allocate the new transaction in POOL; when POOL is freed, the new |
| transaction will be closed (neither committed nor aborted). You |
| can also close the transaction explicitly, using |
| `svn_fs_close_txn'. */ |
| svn_error_t *svn_fs_open_txn (svn_fs_txn_t **txn, |
| svn_fs_t *fs, |
| const char *name, |
| apr_pool_t *pool); |
| |
| |
| /* Close the transaction TXN. This is neither an abort nor a commit; |
| the state of the transaction so far is stored in the filesystem, to |
| be opened again later. */ |
| svn_error_t *svn_fs_close_txn (svn_fs_txn_t *txn); |
| |
| |
| /* Set *NAMES_P to a null-terminated array of pointers to strings, |
| containing the names of all the currently active transactions in |
| the filesystem FS. Allocate the array in POOL. */ |
| svn_error_t *svn_fs_list_transactions (char ***names_p, |
| svn_fs_t *fs, |
| apr_pool_t *pool); |
| |
| /* Transaction properties */ |
| |
| /* Set *VALUE_P to the value of the property named PROPNAME on |
| transaction TXN. If TXN has no property by that name, set *VALUE_P |
| to zero. Allocate the result in POOL. */ |
| svn_error_t *svn_fs_txn_prop (svn_string_t **value_p, |
| svn_fs_txn_t *txn, |
| const char *propname, |
| apr_pool_t *pool); |
| |
| |
| /* Set *TABLE_P to the entire property list of transaction TXN in |
| filesystem FS, as an APR hash table allocated in POOL. The |
| resulting table maps property names to pointers to svn_string_t |
| objects containing the property value. */ |
| svn_error_t *svn_fs_txn_proplist (apr_hash_t **table_p, |
| svn_fs_txn_t *txn, |
| apr_pool_t *pool); |
| |
| |
| /* Change a tranactions TXN's property's value, or add/delete a |
| property. NAME is the name of the property to change, and VALUE is |
| the new value of the property, or zero if the property should be |
| removed altogether. Do any necessary temporary allocation in |
| POOL. */ |
| svn_error_t *svn_fs_change_txn_prop (svn_fs_txn_t *txn, |
| const char *name, |
| const svn_string_t *value, |
| apr_pool_t *pool); |
| |
| |
| |
| /* Roots. */ |
| |
| /* An svn_fs_root_t object represents the root directory of some |
| revision or transaction in a filesystem. To refer to particular |
| node, you provide a root, and a directory path relative that root. */ |
| |
| typedef struct svn_fs_root_t svn_fs_root_t; |
| |
| |
| /* Set *ROOT_P to the root directory of revision REV in filesystem FS. |
| Allocate *ROOT_P in POOL. */ |
| svn_error_t *svn_fs_revision_root (svn_fs_root_t **root_p, |
| svn_fs_t *fs, |
| svn_revnum_t rev, |
| apr_pool_t *pool); |
| |
| |
| /* Set *ROOT_P to the root directory of TXN. Allocate *ROOT_P in POOL. */ |
| svn_error_t *svn_fs_txn_root (svn_fs_root_t **root_p, |
| svn_fs_txn_t *txn, |
| apr_pool_t *pool); |
| |
| |
| /* Set *ROOT_P to a root object that can be used to access nodes by |
| node revision ID in FS. Whenever you pass *ROOT_P to a filesystem |
| access function, any filename "relative" to *ROOT_P must actually |
| be the printed form of a node revision ID: a sequence of decimal |
| numbers without leading zeros, separated by '.' characters, |
| containing an even number of numbers; otherwise, return |
| SVN_ERR_FS_NOT_ID. Allocate ROOT_P in POOL. */ |
| svn_error_t *svn_fs_id_root (svn_fs_root_t **root_p, |
| svn_fs_t *fs, |
| apr_pool_t *pool); |
| |
| |
| /* Free the root directory ROOT. Simply clearing or destroying the |
| pool ROOT was allocated in will have the same effect as calling |
| this function. */ |
| void svn_fs_close_root (svn_fs_root_t *root); |
| |
| |
| /* Return the filesystem to which ROOT belongs. */ |
| svn_fs_t *svn_fs_root_fs (svn_fs_root_t *root); |
| |
| |
| /* Return true iff ROOT is a transaction/revision/id root. */ |
| int svn_fs_is_txn_root (svn_fs_root_t *root); |
| int svn_fs_is_revision_root (svn_fs_root_t *root); |
| int svn_fs_is_id_root (svn_fs_root_t *root); |
| |
| |
| /* If ROOT is the root of a transaction, return a pointer to the name |
| of the transaction; otherwise, return zero. The name is owned by |
| ROOT, and will be freed when ROOT is closed. */ |
| const char *svn_fs_txn_root_name (svn_fs_root_t *root, |
| apr_pool_t *pool); |
| |
| |
| /* If ROOT is the root of a revision, return the revision number. |
| Otherwise, return -1. */ |
| svn_revnum_t svn_fs_revision_root_revision (svn_fs_root_t *root); |
| |
| |
| /* If PATH in TXN_ROOT matches the specified ID, then set MATCHES to |
| true (1). Otherwise, set MATCHES to zero. |
| |
| In essence, this function answers the question, "I want to change |
| node ID. Is that the node which is present in TXN_ROOT?" If the |
| TXN_ROOT is based on the youngest (head) revision, then this test |
| is essentially a test for out-of-dateness. |
| |
| Note that a small compensation is made for asking to change a |
| directory identified by ID, but where the directory's id in the |
| TXN_ROOT is different because it was modified by the bubble-up |
| algorithm of a change below the directory. Since there were no |
| semantic changes, this function deems the bubbled-up directory |
| to match the specified ID, and returns MATCHES := 1. |
| |
| All temporary allocation is performed in POOL. */ |
| svn_error_t *svn_fs_txn_path_is_id (int *matches, |
| svn_fs_root_t *txn_root, |
| const char *path, |
| const svn_fs_id_t *id, |
| apr_pool_t *pool); |
| |
| |
| /* Directory entry names and directory paths. */ |
| |
| /* Here are the rules for directory entry names, and directory paths: |
| |
| A directory entry name is a Unicode string encoded in UTF-8, and |
| may not contain the null character (U+0000). The name should be in |
| Unicode canonical decomposition and ordering. No directory entry |
| may be named '.', '..', or the empty string. Given a directory |
| entry name which fails to meet these requirements, a filesystem |
| function returns an SVN_ERR_FS_PATH_SYNTAX error. |
| |
| A directory path is a sequence of zero or more directory entry |
| names, separated by slash characters (U+002f), and possibly ending |
| with slash characters. Sequences of two or more consecutive slash |
| characters are treated as if they were a single slash. If a path |
| ends with a slash, it refers to the same node it would without the |
| slash, but that node must be a directory, or else the function |
| returns an SVN_ERR_FS_NOT_DIRECTORY error. |
| |
| A path consisting of the empty string, or a string containing only |
| slashes, refers to the root directory. */ |
| |
| |
| |
| /* Operations appropriate to all kinds of nodes. */ |
| |
| /* Return the type of node present at PATH under ROOT. If PATH |
| does not exist under ROOT, set *KIND to svn_node_none. */ |
| svn_node_kind_t svn_fs_check_path (svn_fs_root_t *root, |
| const char *path, |
| apr_pool_t *pool); |
| |
| |
| /* Allocate and return an array *REVS of svn_revnum_t revisions in |
| which PATHS under ROOT were modified. Use POOL for all allocations. |
| The array of *REVS are sorted in descending order. All duplicates |
| will also be removed. PATHS is an array of `const char *' entries. |
| |
| NOTE: This function uses node-id ancestry alone to determine |
| modifiedness, and therefore does NOT claim that in any of the |
| returned revisions file contents changed, properties changed, |
| directory entries lists changed, etc. */ |
| svn_error_t *svn_fs_revisions_changed (apr_array_header_t **revs, |
| svn_fs_root_t *root, |
| const apr_array_header_t *paths, |
| apr_pool_t *pool); |
| |
| |
| /* Set *IS_DIR to non-zero iff PATH in ROOT is a directory. |
| Do any necessary temporary allocation in POOL. */ |
| svn_error_t *svn_fs_is_dir (int *is_dir, |
| svn_fs_root_t *root, |
| const char *path, |
| apr_pool_t *pool); |
| |
| /* Set *IS_FILE to non-zero iff PATH in ROOT is a file. |
| Do any necessary temporary allocation in POOL. */ |
| svn_error_t *svn_fs_is_file (int *is_file, |
| svn_fs_root_t *root, |
| const char *path, |
| apr_pool_t *pool); |
| |
| |
| /* Set *ID_P to the node revision ID of PATH in ROOT, allocated in POOL. |
| |
| If ROOT is the root of a transaction, keep in mind that other |
| changes to the transaction can change which node PATH refers to, |
| and even whether the path exists at all. */ |
| svn_error_t *svn_fs_node_id (svn_fs_id_t **id_p, |
| svn_fs_root_t *root, |
| const char *path, |
| apr_pool_t *pool); |
| |
| /* Set *REVISION to the revision in which PATH under ROOT was created. |
| Use POOL for any temporary allocations. *REVISION will be set to |
| SVN_INVALID_REVNUM for uncommitted nodes (i.e. modified nodes under |
| a transaction root). */ |
| svn_error_t *svn_fs_node_created_rev (svn_revnum_t *revision, |
| svn_fs_root_t *root, |
| const char *path, |
| apr_pool_t *pool); |
| |
| /* Set *VALUE_P to the value of the property named PROPNAME of PATH in |
| ROOT. If the node has no property by that name, set *VALUE_P to |
| zero. Allocate the result in POOL. */ |
| svn_error_t *svn_fs_node_prop (svn_string_t **value_p, |
| svn_fs_root_t *root, |
| const char *path, |
| const char *propname, |
| apr_pool_t *pool); |
| |
| |
| /* Set *TABLE_P to the entire property list of PATH in ROOT, as an APR |
| hash table allocated in POOL. The resulting table maps property |
| names to pointers to svn_string_t objects containing the property |
| value. */ |
| svn_error_t *svn_fs_node_proplist (apr_hash_t **table_p, |
| svn_fs_root_t *root, |
| const char *path, |
| apr_pool_t *pool); |
| |
| |
| /* Change a node's property's value, or add/delete a property. |
| - ROOT and PATH indicate the node whose property should change. |
| ROOT must be the root of a transaction, not the root of a revision. |
| - NAME is the name of the property to change. |
| - VALUE is the new value of the property, or zero if the property should |
| be removed altogether. |
| Do any necessary temporary allocation in POOL. */ |
| svn_error_t *svn_fs_change_node_prop (svn_fs_root_t *root, |
| const char *path, |
| const char *name, |
| const svn_string_t *value, |
| apr_pool_t *pool); |
| |
| |
| /* Set *CHANGED_P to 1 if the properties at PATH1 under ROOT1 differ |
| from those at PATH2 under ROOT2, or set it to 0 if they are the |
| same. Both paths must exist under their respective roots, and both |
| roots must be in the same filesystem. */ |
| svn_error_t *svn_fs_props_changed (int *changed_p, |
| svn_fs_root_t *root1, |
| const char *path1, |
| svn_fs_root_t *root2, |
| const char *path2, |
| apr_pool_t *pool); |
| |
| |
| /* Discover a node's copy ancestry, if any. |
| |
| If the node at PATH in ROOT was copied from some other node, set |
| *REV_P and *PATH_P to the revision and path of the other node, |
| allocating *PATH_P in POOL. |
| |
| Else if there is no copy ancestry for the node, set *REV_P to |
| SVN_INVALID_REVNUM and and *PATH_P to null. |
| |
| If an error is returned, the values of *REV_P and *PATH_P are |
| undefined, but otherwise, if one of them is set as described above, |
| you may assume the other is set correspondingly. |
| |
| ROOT may be a revision root or a transaction root. |
| |
| Notes: |
| - Copy ancestry does not descend. After copying directory D to |
| E, E will have copy ancestry referring to D, but E's children |
| may not. See also svn_fs_copy(). |
| |
| - Copy ancestry *under* a copy is preserved. That is, if you |
| copy /A/D/G/pi to /A/D/G/pi2, and then copy /A/D/G to /G, then |
| /G/pi2 will still have copy ancestry pointing to /A/D/G/pi. |
| We don't know if this is a feature or a bug yet; if it turns |
| out to be a bug, then the fix is to make svn_fs_copied_from() |
| observe the following logic, which currently callers may |
| choose to follow themselves: if node X has copy history, but |
| its ancestor A also has copy history, then you may ignore X's |
| history if X's revision-of-origin is earlier than A's -- |
| because that would mean that X's copy history was preserved in |
| a copy-under-a-copy scenario. If X's revision-of-origin is |
| the same as A's, then it was copied under A during the same |
| transaction that created A. (X's revision-of-origin cannot be |
| greater than A's, if X has copy history.) ### todo: See how |
| people like this, it can always be hidden behind the curtain |
| if necessary. |
| |
| - Copy ancestry is not stored as a regular subversion property |
| because it is not inherited. Copying foo to bar results in a |
| revision of bar with copy ancestry; but committing a text |
| change to bar right after that results in a new revision of |
| bar without copy ancestry. */ |
| svn_error_t *svn_fs_copied_from (svn_revnum_t *rev_p, |
| const char **path_p, |
| svn_fs_root_t *root, |
| const char *path, |
| apr_pool_t *pool); |
| |
| |
| /* Given nodes SOURCE and TARGET, and a common ancestor ANCESTOR, |
| modify TARGET to contain all the changes made between ANCESTOR and |
| SOURCE, as well as the changes made between ANCESTOR and TARGET. |
| TARGET_ROOT must be the root of a transaction, not a revision. |
| |
| SOURCE, TARGET, and ANCESTOR are generally directories; this |
| function recursively merges the directories' contents. If they are |
| files, this function simply returns an error whenever SOURCE, |
| TARGET, and ANCESTOR are all distinct node revisions. |
| |
| If there are differences between ANCESTOR and SOURCE that conflict |
| with changes between ANCESTOR and TARGET, this function returns an |
| SVN_ERR_FS_CONFLICT error. |
| |
| If the merge is successful, TARGET is left in the merged state, and |
| the base root of TARGET's txn is set to the root node of SOURCE. |
| If an error is returned (whether for conflict or otherwise), TARGET |
| is left unaffected. |
| |
| If CONFLICT_P is non-null, then: a conflict error sets *CONFLICT_P |
| to the name of the node in TARGET which couldn't be merged, |
| otherwise, success sets *CONFLICT_P to null. |
| |
| Do any necessary temporary allocation in POOL. */ |
| svn_error_t *svn_fs_merge (const char **conflict_p, |
| svn_fs_root_t *source_root, |
| const char *source_path, |
| svn_fs_root_t *target_root, |
| const char *target_path, |
| svn_fs_root_t *ancestor_root, |
| const char *ancestor_path, |
| apr_pool_t *pool); |
| |
| |
| |
| /* Compare the nodes ROOT1:PATH1 and ROOT2:PATH2, and determine if |
| they are "different". Return the answer in IS_DIFFERENT. |
| |
| We define two nodes to be "different" if: |
| |
| - they are different node types, or |
| |
| - if both files, they have different node-revision-ids, or |
| |
| - if both dirs, they have different entry lists. |
| |
| (Note that there is a small chance of getting a false positive: two |
| different node-rev-ids don't *necessarily* have different contents. |
| But right now it's not worth doing byte-for-byte comparisons. This |
| problem will go away when we have deltified storage.) */ |
| svn_error_t *svn_fs_is_different (int *is_different, |
| svn_fs_root_t *root1, |
| const char *path1, |
| svn_fs_root_t *root2, |
| const char *path2, |
| apr_pool_t *pool); |
| |
| |
| |
| /* Deltification of Storage. */ |
| |
| |
| /* Examine the data associated with PATH under ROOT, and offer the |
| filesystem a chance store that data in a deltified fashion. ROOT |
| is a revision root. |
| |
| If PATH represents a directory, deltify PATH's properties and list |
| of entries, and if RECURSIVE is non-zero, perform this operation |
| recursively on PATH's children. |
| |
| If PATH represents a file, deltify PATH's properties and text |
| contents (and ignore the RECURSIVE argument). |
| |
| Use POOL for all necessary allocations. */ |
| svn_error_t *svn_fs_deltify (svn_fs_root_t *root, |
| const char *path, |
| int recursive, |
| apr_pool_t *pool); |
| |
| |
| /* Ensure that the data associated with PATH under ROOT is stored as |
| fulltext (that is, in an undeltified fashion). If this is already |
| the case, do nothing. ROOT is a revision root. |
| |
| If PATH represents a directory, un-deltify PATH's properties and list |
| of entries, and if RECURSIVE is non-zero, perform this operation |
| recursively on PATH's children. |
| |
| If PATH represents a file, un-deltify PATH's properties and text |
| contents (and ignore the RECURSIVE argument). |
| |
| Use POOL for all necessary allocations. */ |
| svn_error_t *svn_fs_undeltify (svn_fs_root_t *root, |
| const char *path, |
| int recursive, |
| apr_pool_t *pool); |
| |
| |
| |
| /* Directories. */ |
| |
| |
| /* The type of a Subversion directory entry. */ |
| typedef struct svn_fs_dirent_t { |
| |
| /* The name of this directory entry. */ |
| char *name; |
| |
| /* The node revision ID it names. */ |
| svn_fs_id_t *id; |
| |
| } svn_fs_dirent_t; |
| |
| |
| /* Set *TABLE_P to a newly allocated APR hash table containing the |
| entries of the directory at PATH in ROOT. The keys of the table |
| are entry names, as byte strings, excluding the final null |
| character; the table's values are pointers to svn_fs_dirent_t |
| structures. Allocate the table and its contents in POOL. */ |
| svn_error_t *svn_fs_dir_entries (apr_hash_t **entries_p, |
| svn_fs_root_t *root, |
| const char *path, |
| apr_pool_t *pool); |
| |
| |
| /* Create a new directory named PATH in ROOT. The new directory has |
| no entries, and no properties. ROOT must be the root of a |
| transaction, not a revision. |
| |
| Do any necessary temporary allocation in POOL. */ |
| svn_error_t *svn_fs_make_dir (svn_fs_root_t *root, |
| const char *path, |
| apr_pool_t *pool); |
| |
| |
| /* Delete the node named PATH in ROOT. ROOT must be the root of a |
| transaction, not a revision. Do any necessary temporary allocation |
| in POOL. |
| |
| If the node being deleted is a directory, it must be empty, else |
| the error SVN_ERR_FS_DIR_NOT_EMPTY is returned. |
| |
| Attempting to remove the root dir also results in an error, |
| SVN_ERR_FS_ROOT_DIR, even if the dir is empty. */ |
| svn_error_t *svn_fs_delete (svn_fs_root_t *root, |
| const char *path, |
| apr_pool_t *pool); |
| |
| |
| /* Delete the node named PATH in ROOT. If the node being deleted is a |
| directory, its contents will be deleted recursively. ROOT must be |
| the root of a transaction, not of a revision. Use POOL for |
| temporary allocation. |
| |
| This function may be more efficient than making the equivalent |
| series of calls to svn_fs_delete, because it takes advantage of the |
| fact that, to delete an immutable subtree, shared with some |
| committed revision, you need only remove the directory entry. The |
| dumb algorithm would recurse into the subtree and end up cloning |
| each non-empty directory it contains, only to delete it later. |
| |
| If return SVN_ERR_FS_NO_SUCH_ENTRY, then the basename of PATH is |
| missing from its parent, that is, the final target of the deletion |
| is missing. */ |
| svn_error_t *svn_fs_delete_tree (svn_fs_root_t *root, |
| const char *path, |
| apr_pool_t *pool); |
| |
| |
| /* Move the node named FROM to TO, both in ROOT. ROOT must be the |
| root of a transaction, not a revision. |
| |
| Do any necessary temporary allocation in POOL. */ |
| svn_error_t *svn_fs_rename (svn_fs_root_t *root, |
| const char *from, |
| const char *to, |
| apr_pool_t *pool); |
| |
| |
| /* Create a copy of FROM_PATH in FROM_ROOT named TO_PATH in TO_ROOT. |
| If FROM_PATH in FROM_ROOT is a directory, copy the tree it refers |
| to recursively. |
| |
| The copy will remember its source; use svn_fs_copied_from() to |
| access this information. |
| |
| TO_ROOT must be the root of a transaction; FROM_PATH must be the |
| root of a revision. (Requiring FROM_PATH to be the root of a |
| revision makes the implementation trivial: there is no detectable |
| difference (modulo node revision ID's) between copying FROM and |
| simply adding a reference to it. So the operation takes place in |
| constant time. However, there's no reason not to extend this to |
| mutable nodes --- it's just more code.) |
| |
| Note: to do a copy without preserving copy history, use |
| svn_fs_link(). |
| |
| Do any necessary temporary allocation in POOL. */ |
| svn_error_t *svn_fs_copy (svn_fs_root_t *from_root, |
| const char *from_path, |
| svn_fs_root_t *to_root, |
| const char *to_path, |
| apr_pool_t *pool); |
| |
| |
| /* Like svn_fs_copy(), but doesn't record copy history. I.e., you |
| cannot use svn_fs_copied_from() later to find out where this copy |
| came from. |
| |
| Use svn_fs_link() in situations where you don't care about the copy |
| history, because it is slightly cheaper than svn_fs_copy(). */ |
| svn_error_t *svn_fs_link (svn_fs_root_t *from_root, |
| const char *from_path, |
| svn_fs_root_t *to_root, |
| const char *to_path, |
| apr_pool_t *pool); |
| |
| /* Files. */ |
| |
| /* Set *LENGTH_P to the length of the file PATH in ROOT, in bytes. Do |
| any necessary temporary allocation in POOL. */ |
| svn_error_t *svn_fs_file_length (apr_off_t *length_p, |
| svn_fs_root_t *root, |
| const char *path, |
| apr_pool_t *pool); |
| |
| |
| /* Set *CONTENTS to a readable generic stream will yield the contents |
| of the file PATH in ROOT. Allocate the stream in POOL. You can |
| only use *CONTENTS for as long as the underlying filesystem is |
| open. If PATH is not a file, return SVN_ERR_FS_NOT_FILE. |
| |
| If ROOT is the root of a transaction, it is possible that the |
| contents of the file PATH will change between calls to |
| svn_fs_file_contents(). In that case, the result of reading from |
| *CONTENTS is undefined. |
| |
| ### kff todo: I am worried about lifetime issues with this pool vs |
| the trail created farther down the call stack. Trace this function |
| to investigate... */ |
| svn_error_t *svn_fs_file_contents (svn_stream_t **contents, |
| svn_fs_root_t *root, |
| const char *path, |
| apr_pool_t *pool); |
| |
| |
| /* Create a new file named PATH in ROOT. The file's initial contents |
| are the empty string, and it has no properties. ROOT must be the |
| root of a transaction, not a revision. |
| |
| Do any necessary temporary allocation in POOL. */ |
| svn_error_t *svn_fs_make_file (svn_fs_root_t *root, |
| const char *path, |
| apr_pool_t *pool); |
| |
| |
| /* Apply a text delta to the file PATH in ROOT. ROOT must be the root |
| of a transaction, not a revision. |
| |
| Set *CONTENTS_P to a function ready to receive text delta windows |
| describing how to change the file's contents, relative to its |
| current contents. Set *CONTENTS_BATON_P to a baton to pass to |
| *CONTENTS_P. |
| |
| If PATH does not exist in ROOT, return an error. (You cannot use |
| this routine to create new files; use svn_fs_make_file to create |
| an empty file first.) |
| |
| Do any necessary temporary allocation in POOL. */ |
| svn_error_t *svn_fs_apply_textdelta (svn_txdelta_window_handler_t *contents_p, |
| void **contents_baton_p, |
| svn_fs_root_t *root, |
| const char *path, |
| apr_pool_t *pool); |
| |
| |
| /* Set *CHANGED_P to 1 if the contents at PATH1 under ROOT1 differ |
| from those at PATH2 under ROOT2, or set it to 0 if they are the |
| same. Both paths must exist under their respective roots, and both |
| roots must be in the same filesystem. */ |
| svn_error_t *svn_fs_contents_changed (int *changed_p, |
| svn_fs_root_t *root1, |
| const char *path1, |
| svn_fs_root_t *root2, |
| const char *path2, |
| apr_pool_t *pool); |
| |
| |
| |
| /* Filesystem revisions. */ |
| |
| |
| /* Set *YOUNGEST_P to the number of the youngest revision in filesystem FS. |
| Use POOL for all temporary allocation. |
| |
| The oldest revision in any filesystem is numbered zero. */ |
| svn_error_t *svn_fs_youngest_rev (svn_revnum_t *youngest_p, |
| svn_fs_t *fs, |
| apr_pool_t *pool); |
| |
| |
| /* Set *VALUE_P to the value of the property named PROPNAME on |
| revision REV in the filesystem FS. If REV has no property by that |
| name, set *VALUE_P to zero. Allocate the result in POOL. */ |
| svn_error_t *svn_fs_revision_prop (svn_string_t **value_p, |
| svn_fs_t *fs, |
| svn_revnum_t rev, |
| const char *propname, |
| apr_pool_t *pool); |
| |
| |
| /* Set *TABLE_P to the entire property list of revision REV in |
| filesystem FS, as an APR hash table allocated in POOL. The table |
| maps char * property names to svn_string_t * values; the names |
| and values are allocated in POOL. */ |
| svn_error_t *svn_fs_revision_proplist (apr_hash_t **table_p, |
| svn_fs_t *fs, |
| svn_revnum_t rev, |
| apr_pool_t *pool); |
| |
| |
| /* Change a revision's property's value, or add/delete a property. |
| |
| - FS is a filesystem, and REV is the revision in that filesystem |
| whose property should change. |
| - NAME is the name of the property to change. |
| - VALUE is the new value of the property, or zero if the property should |
| be removed altogether. |
| |
| Note that revision properties are non-historied --- you can change |
| them after the revision has been committed. They are not protected |
| via transactions. |
| |
| Do any necessary temporary allocation in POOL. */ |
| svn_error_t *svn_fs_change_rev_prop (svn_fs_t *fs, |
| svn_revnum_t rev, |
| const char *name, |
| const svn_string_t *value, |
| apr_pool_t *pool); |
| |
| |
| |
| /* Computing deltas. */ |
| |
| |
| /* Set *STREAM_P to a pointer to a delta stream that will turn the |
| contents of the file SOURCE into the contents of the file TARGET. |
| If SOURCE_ROOT is zero, use a file with zero length as the source. |
| |
| This function does not compare the two files' properties. |
| |
| Allocate *STREAM_P, and do any necessary temporary allocation, in |
| POOL. */ |
| svn_error_t * |
| svn_fs_get_file_delta_stream (svn_txdelta_stream_t **stream_p, |
| svn_fs_root_t *source_root, |
| const char *source_path, |
| svn_fs_root_t *target_root, |
| const char *target_path, |
| apr_pool_t *pool); |
| |
| |
| |
| |
| |
| /* Non-historical properties. */ |
| |
| /* [[Yes, do tell.]] */ |
| |
| #endif /* SVN_FS_H */ |
| |
| #ifdef __cplusplus |
| } |
| #endif /* __cplusplus */ |
| |
| |
| /* ---------------------------------------------------------------- |
| * local variables: |
| * eval: (load-file "../../tools/dev/svn-dev.el") |
| * end: |
| */ |
