Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_config.h
Go to the documentation of this file.
1 /**
2  * @copyright
3  * ====================================================================
4  * Copyright (c) 2000-2008 CollabNet. All rights reserved.
5  *
6  * This software is licensed as described in the file COPYING, which
7  * you should have received as part of this distribution. The terms
8  * are also available at http://subversion.tigris.org/license-1.html.
9  * If newer versions of this license are posted there, you may use a
10  * newer version instead, at your option.
11  *
12  * This software consists of voluntary contributions made by many
13  * individuals. For exact contribution history, see the revision
14  * history and logs, available at http://subversion.tigris.org/.
15  * ====================================================================
16  * @endcopyright
17  *
18  * @file svn_config.h
19  * @brief Accessing SVN configuration files.
20  */
21 
22 
23 
24 #ifndef SVN_CONFIG_H
25 #define SVN_CONFIG_H
26 
27 #include <apr.h> /* for apr_int64_t */
28 #include <apr_pools.h> /* for apr_pool_t */
29 #include <apr_hash.h> /* for apr_hash_t */
30 
31 #include "svn_types.h"
32 
33 #ifdef __cplusplus
34 extern "C" {
35 #endif /* __cplusplus */
36 
37 
38 /**************************************************************************
39  *** ***
40  *** For a description of the SVN configuration file syntax, see ***
41  *** your ~/.subversion/README, which is written out automatically by ***
42  *** svn_config_ensure(). ***
43  *** ***
44  **************************************************************************/
45 
46 
47 /** Opaque structure describing a set of configuration options. */
48 typedef struct svn_config_t svn_config_t;
49 
50 
51 /*** Configuration Defines ***/
52 
53 /**
54  * @name Client configuration files strings
55  * Strings for the names of files, sections, and options in the
56  * client configuration files.
57  * @{
58  */
59 #define SVN_CONFIG_CATEGORY_SERVERS "servers"
60 #define SVN_CONFIG_SECTION_GROUPS "groups"
61 #define SVN_CONFIG_SECTION_GLOBAL "global"
62 #define SVN_CONFIG_OPTION_HTTP_PROXY_HOST "http-proxy-host"
63 #define SVN_CONFIG_OPTION_HTTP_PROXY_PORT "http-proxy-port"
64 #define SVN_CONFIG_OPTION_HTTP_PROXY_USERNAME "http-proxy-username"
65 #define SVN_CONFIG_OPTION_HTTP_PROXY_PASSWORD "http-proxy-password"
66 #define SVN_CONFIG_OPTION_HTTP_PROXY_EXCEPTIONS "http-proxy-exceptions"
67 #define SVN_CONFIG_OPTION_HTTP_TIMEOUT "http-timeout"
68 #define SVN_CONFIG_OPTION_HTTP_COMPRESSION "http-compression"
69 #define SVN_CONFIG_OPTION_NEON_DEBUG_MASK "neon-debug-mask"
70 #define SVN_CONFIG_OPTION_HTTP_AUTH_TYPES "http-auth-types"
71 #define SVN_CONFIG_OPTION_SSL_AUTHORITY_FILES "ssl-authority-files"
72 #define SVN_CONFIG_OPTION_SSL_TRUST_DEFAULT_CA "ssl-trust-default-ca"
73 #define SVN_CONFIG_OPTION_SSL_CLIENT_CERT_FILE "ssl-client-cert-file"
74 #define SVN_CONFIG_OPTION_SSL_CLIENT_CERT_PASSWORD "ssl-client-cert-password"
75 #define SVN_CONFIG_OPTION_SSL_PKCS11_PROVIDER "ssl-pkcs11-provider"
76 #define SVN_CONFIG_OPTION_HTTP_LIBRARY "http-library"
77 #define SVN_CONFIG_OPTION_STORE_PASSWORDS "store-passwords"
78 #define SVN_CONFIG_OPTION_STORE_PLAINTEXT_PASSWORDS "store-plaintext-passwords"
79 #define SVN_CONFIG_OPTION_STORE_AUTH_CREDS "store-auth-creds"
80 #define SVN_CONFIG_OPTION_STORE_SSL_CLIENT_CERT_PP "store-ssl-client-cert-pp"
81 #define SVN_CONFIG_OPTION_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT \
82  "store-ssl-client-cert-pp-plaintext"
83 #define SVN_CONFIG_OPTION_USERNAME "username"
84 
85 #define SVN_CONFIG_CATEGORY_CONFIG "config"
86 #define SVN_CONFIG_SECTION_AUTH "auth"
87 #define SVN_CONFIG_OPTION_PASSWORD_STORES "password-stores"
88 #define SVN_CONFIG_OPTION_KWALLET_WALLET "kwallet-wallet"
89 #define SVN_CONFIG_OPTION_KWALLET_SVN_APPLICATION_NAME_WITH_PID "kwallet-svn-application-name-with-pid"
90 /* The majority of options of the "auth" section
91  * has been moved to SVN_CONFIG_CATEGORY_SERVERS. */
92 #define SVN_CONFIG_SECTION_HELPERS "helpers"
93 #define SVN_CONFIG_OPTION_EDITOR_CMD "editor-cmd"
94 #define SVN_CONFIG_OPTION_DIFF_CMD "diff-cmd"
95 #define SVN_CONFIG_OPTION_DIFF3_CMD "diff3-cmd"
96 #define SVN_CONFIG_OPTION_DIFF3_HAS_PROGRAM_ARG "diff3-has-program-arg"
97 #define SVN_CONFIG_OPTION_MERGE_TOOL_CMD "merge-tool-cmd"
98 #define SVN_CONFIG_SECTION_MISCELLANY "miscellany"
99 #define SVN_CONFIG_OPTION_GLOBAL_IGNORES "global-ignores"
100 #define SVN_CONFIG_OPTION_LOG_ENCODING "log-encoding"
101 #define SVN_CONFIG_OPTION_USE_COMMIT_TIMES "use-commit-times"
102 #define SVN_CONFIG_OPTION_TEMPLATE_ROOT "template-root"
103 #define SVN_CONFIG_OPTION_ENABLE_AUTO_PROPS "enable-auto-props"
104 #define SVN_CONFIG_OPTION_NO_UNLOCK "no-unlock"
105 #define SVN_CONFIG_OPTION_MIMETYPES_FILE "mime-types-file"
106 #define SVN_CONFIG_OPTION_PRESERVED_CF_EXTS "preserved-conflict-file-exts"
107 #define SVN_CONFIG_OPTION_INTERACTIVE_CONFLICTS "interactive-conflicts"
108 #define SVN_CONFIG_SECTION_TUNNELS "tunnels"
109 #define SVN_CONFIG_SECTION_AUTO_PROPS "auto-props"
110 /** @} */
111 
112 /** @name Repository conf directory configuration files strings
113  * Strings for the names of sections and options in the
114  * repository conf directory configuration files.
115  * @{
116  */
117 /* For repository svnserve.conf files */
118 #define SVN_CONFIG_SECTION_GENERAL "general"
119 #define SVN_CONFIG_OPTION_ANON_ACCESS "anon-access"
120 #define SVN_CONFIG_OPTION_AUTH_ACCESS "auth-access"
121 #define SVN_CONFIG_OPTION_PASSWORD_DB "password-db"
122 #define SVN_CONFIG_OPTION_REALM "realm"
123 #define SVN_CONFIG_OPTION_AUTHZ_DB "authz-db"
124 #define SVN_CONFIG_SECTION_SASL "sasl"
125 #define SVN_CONFIG_OPTION_USE_SASL "use-sasl"
126 #define SVN_CONFIG_OPTION_MIN_SSF "min-encryption"
127 #define SVN_CONFIG_OPTION_MAX_SSF "max-encryption"
128 
129 /* For repository password database */
130 #define SVN_CONFIG_SECTION_USERS "users"
131 /** @} */
132 
133 /*** Configuration Default Values ***/
134 
135 /* '*' matches leading dots, e.g. '*.rej' matches '.foo.rej'. */
136 /* We want this to be printed on two lines in the generated config file,
137  * but we don't want the # character to end up in the variable.
138  */
139 #define SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_1 \
140  "*.o *.lo *.la *.al .libs *.so *.so.[0-9]* *.a *.pyc *.pyo"
141 #define SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_2 \
142  "*.rej *~ #*# .#* .*.swp .DS_Store"
143 
144 #define SVN_CONFIG_DEFAULT_GLOBAL_IGNORES \
145  SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_1 " " \
146  SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_2
147 
148 #define SVN_CONFIG_TRUE "TRUE"
149 #define SVN_CONFIG_FALSE "FALSE"
150 #define SVN_CONFIG_ASK "ASK"
151 
152 /* Default values for some options. Should be passed as default values
153  * to svn_config_get and friends, instead of hard-coding the defaults in
154  * multiple places. */
155 #define SVN_CONFIG_DEFAULT_OPTION_STORE_PASSWORDS TRUE
156 #define SVN_CONFIG_DEFAULT_OPTION_STORE_PLAINTEXT_PASSWORDS SVN_CONFIG_ASK
157 #define SVN_CONFIG_DEFAULT_OPTION_STORE_AUTH_CREDS TRUE
158 #define SVN_CONFIG_DEFAULT_OPTION_STORE_SSL_CLIENT_CERT_PP TRUE
159 #define SVN_CONFIG_DEFAULT_OPTION_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT \
160  SVN_CONFIG_ASK
161 
162 /** Read configuration information from the standard sources and merge it
163  * into the hash @a *cfg_hash. If @a config_dir is not NULL it specifies a
164  * directory from which to read the configuration files, overriding all
165  * other sources. Otherwise, first read any system-wide configurations
166  * (from a file or from the registry), then merge in personal
167  * configurations (again from file or registry). The hash and all its data
168  * are allocated in @a pool.
169  *
170  * @a *cfg_hash is a hash whose keys are @c const char * configuration
171  * categories (@c SVN_CONFIG_CATEGORY_SERVERS,
172  * @c SVN_CONFIG_CATEGORY_CONFIG, etc.) and whose values are the @c
173  * svn_config_t * items representing the configuration values for that
174  * category.
175  */
176 svn_error_t *
177 svn_config_get_config(apr_hash_t **cfg_hash,
178  const char *config_dir,
179  apr_pool_t *pool);
180 
181 
182 /** Read configuration data from @a file (a file or registry path) into
183  * @a *cfgp, allocated in @a pool.
184  *
185  * If @a file does not exist, then if @a must_exist, return an error,
186  * otherwise return an empty @c svn_config_t.
187  */
188 svn_error_t *
190  const char *file,
191  svn_boolean_t must_exist,
192  apr_pool_t *pool);
193 
194 /** Like svn_config_read(), but merges the configuration data from @a file
195  * (a file or registry path) into @a *cfg, which was previously returned
196  * from svn_config_read(). This function invalidates all value
197  * expansions in @a cfg, so that the next svn_config_get() takes the
198  * modifications into account.
199  */
200 svn_error_t *
202  const char *file,
203  svn_boolean_t must_exist);
204 
205 
206 /** Find the value of a (@a section, @a option) pair in @a cfg, set @a
207  * *valuep to the value.
208  *
209  * If @a cfg is @c NULL, just sets @a *valuep to @a default_value. If
210  * the value does not exist, expand and return @a default_value. @a
211  * default_value can be NULL.
212  *
213  * The returned value will be valid at least until the next call to
214  * svn_config_get(), or for the lifetime of @a default_value. It is
215  * safest to consume the returned value immediately.
216  *
217  * This function may change @a cfg by expanding option values.
218  */
219 void
221  const char **valuep,
222  const char *section,
223  const char *option,
224  const char *default_value);
225 
226 /** Add or replace the value of a (@a section, @a option) pair in @a cfg with
227  * @a value.
228  *
229  * This function invalidates all value expansions in @a cfg.
230  *
231  * To remove an option, pass NULL for the @c value.
232  */
233 void
235  const char *section,
236  const char *option,
237  const char *value);
238 
239 /** Like svn_config_get(), but for boolean values.
240  *
241  * Parses the option as a boolean value. The recognized representations
242  * are 'TRUE'/'FALSE', 'yes'/'no', 'on'/'off', '1'/'0'; case does not
243  * matter. Returns an error if the option doesn't contain a known string.
244  */
245 svn_error_t *
247  svn_boolean_t *valuep,
248  const char *section,
249  const char *option,
250  svn_boolean_t default_value);
251 
252 /** Like svn_config_set(), but for boolean values.
253  *
254  * Sets the option to 'TRUE'/'FALSE', depending on @a value.
255  */
256 void
258  const char *section,
259  const char *option,
260  svn_boolean_t value);
261 
262 /** Like svn_config_get(), but only for yes/no/ask values.
263  *
264  * Parse @a option in @a section and set @a *valuep to one of
265  * SVN_CONFIG_TRUE, SVN_CONFIG_FALSE, or SVN_CONFIG_ASK. If there is
266  * no setting for @a option, then parse @a default_value and set
267  * @a *valuep accordingly. If @a default_value is NULL, the result is
268  * undefined, and may be an error; we recommend that you pass one of
269  * SVN_CONFIG_TRUE, SVN_CONFIG_FALSE, or SVN_CONFIG_ASK for @a default value.
270  *
271  * Valid representations are (at least) "true"/"false", "yes"/"no",
272  * "on"/"off", "1"/"0", and "ask"; they are case-insensitive. Return
273  * an SVN_ERR_BAD_CONFIG_VALUE error if either @a default_value or
274  * @a option's value is not a valid representation.
275  *
276  * @since New in 1.6.
277  */
278 svn_error_t *
280  const char **valuep,
281  const char *section,
282  const char *option,
283  const char* default_value);
284 
285 /** Similar to @c svn_config_section_enumerator2_t, but is not
286  * provided with a memory pool argument.
287  *
288  * See svn_config_enumerate_sections() for the details of this type.
289  *
290  * @deprecated Provided for backwards compatibility with the 1.2 API.
291  */
292 typedef svn_boolean_t (*svn_config_section_enumerator_t)(const char *name,
293  void *baton);
294 
295 /** Similar to svn_config_enumerate_sections2(), but uses a memory pool of
296  * @a cfg instead of one that is explicitely provided.
297  *
298  * @deprecated Provided for backwards compatibility with the 1.2 API.
299  */
301 int
304  void *baton);
305 
306 /** A callback function used in enumerating config sections.
307  *
308  * See svn_config_enumerate_sections2() for the details of this type.
309  *
310  * @since New in 1.3.
311  */
313  void *baton,
314  apr_pool_t *pool);
315 
316 /** Enumerate the sections, passing @a baton and the current section's name
317  * to @a callback. Continue the enumeration if @a callback returns @c TRUE.
318  * Return the number of times @a callback was called.
319  *
320  * ### See kff's comment to svn_config_enumerate2(). It applies to this
321  * function, too. ###
322  *
323  * @a callback's @a name parameter is only valid for the duration of the call.
324  *
325  * @since New in 1.3.
326  */
327 int
330  void *baton, apr_pool_t *pool);
331 
332 /** Similar to @c svn_config_enumerator2_t, but is not
333  * provided with a memory pool argument.
334  * See svn_config_enumerate() for the details of this type.
335  *
336  * @deprecated Provided for backwards compatibility with the 1.2 API.
337  */
338 typedef svn_boolean_t (*svn_config_enumerator_t)(const char *name,
339  const char *value,
340  void *baton);
341 
342 /** Similar to svn_config_enumerate2(), but uses a memory pool of
343  * @a cfg instead of one that is explicitely provided.
344  *
345  * @deprecated Provided for backwards compatibility with the 1.2 API.
346  */
348 int
350  const char *section,
351  svn_config_enumerator_t callback,
352  void *baton);
353 
354 
355 /** A callback function used in enumerating config options.
356  *
357  * See svn_config_enumerate2() for the details of this type.
358  *
359  * @since New in 1.3.
360  */
361 typedef svn_boolean_t (*svn_config_enumerator2_t)(const char *name,
362  const char *value,
363  void *baton,
364  apr_pool_t *pool);
365 
366 /** Enumerate the options in @a section, passing @a baton and the current
367  * option's name and value to @a callback. Continue the enumeration if
368  * @a callback returns @c TRUE. Return the number of times @a callback
369  * was called.
370  *
371  * ### kff asks: A more usual interface is to continue enumerating
372  * while @a callback does not return error, and if @a callback does
373  * return error, to return the same error (or a wrapping of it)
374  * from svn_config_enumerate(). What's the use case for
375  * svn_config_enumerate()? Is it more likely to need to break out
376  * of an enumeration early, with no error, than an invocation of
377  * @a callback is likely to need to return an error? ###
378  *
379  * @a callback's @a name and @a value parameters are only valid for the
380  * duration of the call.
381  *
382  * @since New in 1.3.
383  */
384 int
386  const char *section,
387  svn_config_enumerator2_t callback,
388  void *baton,
389  apr_pool_t *pool);
390 
391 /**
392  * Return @c TRUE if @a section exists in @a cfg, @c FALSE otherwise.
393  *
394  * @since New in 1.4.
395  */
398  const char *section);
399 
400 /** Enumerate the group @a master_section in @a cfg. Each variable
401  * value is interpreted as a list of glob patterns (separated by comma
402  * and optional whitespace). Return the name of the first variable
403  * whose value matches @a key, or @c NULL if no variable matches.
404  */
405 const char *
407  const char *key,
408  const char *master_section,
409  apr_pool_t *pool);
410 
411 /** Retrieve value corresponding to @a option_name in @a cfg, or
412  * return @a default_value if none is found.
413  *
414  * The config will first be checked for a default.
415  * If @a server_group is not @c NULL, the config will also be checked
416  * for an override in a server group,
417  *
418  */
419 const char *
421  const char* server_group,
422  const char* option_name,
423  const char* default_value);
424 
425 /** Retrieve value into @a result_value corresponding to @a option_name for a
426  * given @a server_group in @a cfg, or return @a default_value if none is
427  * found.
428  *
429  * The config will first be checked for a default, then will be checked for
430  * an override in a server group. If the value found is not a valid integer,
431  * a @c svn_error_t* will be returned.
432  */
433 svn_error_t *
435  const char *server_group,
436  const char *option_name,
437  apr_int64_t default_value,
438  apr_int64_t *result_value,
439  apr_pool_t *pool);
440 
441 
442 /** Set @a *valuep according to @a option_name for a given
443  * @a server_group in @a cfg, or set to @a default_value if no value is
444  * specified.
445  *
446  * Check first a default, then for an override in a server group. If
447  * a value is found but is not a valid boolean, return an
448  * SVN_ERR_BAD_CONFIG_VALUE error.
449  *
450  * @since New in 1.6.
451  */
452 svn_error_t *
454  svn_boolean_t *valuep,
455  const char *server_group,
456  const char *option_name,
457  svn_boolean_t default_value);
458 
459 
460 
461 /** Try to ensure that the user's ~/.subversion/ area exists, and create
462  * no-op template files for any absent config files. Use @a pool for any
463  * temporary allocation. If @a config_dir is not @c NULL it specifies a
464  * directory from which to read the config overriding all other sources.
465  *
466  * Don't error if something exists but is the wrong kind (for example,
467  * ~/.subversion exists but is a file, or ~/.subversion/servers exists
468  * but is a directory).
469  *
470  * Also don't error if trying to create something and failing -- it's
471  * okay for the config area or its contents not to be created.
472  * However, if creating a config template file succeeds, return an
473  * error if unable to initialize its contents.
474  */
475 svn_error_t *
476 svn_config_ensure(const char *config_dir,
477  apr_pool_t *pool);
478 
479 
480 
481 
482 /** Accessing cached authentication data in the user config area.
483  *
484  * @defgroup cached_authentication_data Cached authentication data
485  * @{
486  */
487 
488 
489 /** A hash-key pointing to a realmstring. Every file containing
490  * authentication data should have this key.
491  */
492 #define SVN_CONFIG_REALMSTRING_KEY "svn:realmstring"
493 
494 /** Use @a cred_kind and @a realmstring to locate a file within the
495  * ~/.subversion/auth/ area. If the file exists, initialize @a *hash
496  * and load the file contents into the hash, using @a pool. If the
497  * file doesn't exist, set @a *hash to NULL.
498  *
499  * If @a config_dir is not NULL it specifies a directory from which to
500  * read the config overriding all other sources.
501  *
502  * Besides containing the original credential fields, the hash will
503  * also contain @c SVN_CONFIG_REALMSTRING_KEY. The caller can examine
504  * this value as a sanity-check that the correct file was loaded.
505  *
506  * The hashtable will contain <tt>const char *</tt> keys and
507  * <tt>svn_string_t *</tt> values.
508  */
509 svn_error_t *
510 svn_config_read_auth_data(apr_hash_t **hash,
511  const char *cred_kind,
512  const char *realmstring,
513  const char *config_dir,
514  apr_pool_t *pool);
515 
516 /** Use @a cred_kind and @a realmstring to create or overwrite a file
517  * within the ~/.subversion/auth/ area. Write the contents of @a hash into
518  * the file. If @a config_dir is not NULL it specifies a directory to read
519  * the config overriding all other sources.
520  *
521  * Also, add @a realmstring to the file, with key @c
522  * SVN_CONFIG_REALMSTRING_KEY. This allows programs (or users) to
523  * verify exactly which set credentials live within the file.
524  *
525  * The hashtable must contain <tt>const char *</tt> keys and
526  * <tt>svn_string_t *</tt> values.
527  */
528 svn_error_t *
529 svn_config_write_auth_data(apr_hash_t *hash,
530  const char *cred_kind,
531  const char *realmstring,
532  const char *config_dir,
533  apr_pool_t *pool);
534 
535 /** Put the absolute path to the user's configuration directory,
536  * or to a file within that directory, into @a *path.
537  *
538  * If @a config_dir is not NULL, it must point to an alternative
539  * config directory location. If it is NULL, the default location
540  * is used. If @a fname is not NULL, it must specify the last
541  * component of the path to be returned. This can be used to create
542  * a path to any file in the configuration directory.
543  *
544  * Do all allocations in @a pool.
545  *
546  * Hint:
547  * To get the user configuration file, pass @c SVN_CONFIG_CATEGORY_CONFIG
548  * for @a fname. To get the servers configuration file, pass
549  * @c SVN_CONFIG_CATEGORY_SERVERS for @a fname.
550  *
551  * @since New in 1.6.
552  */
553 svn_error_t *
554 svn_config_get_user_config_path(const char **path,
555  const char *config_dir,
556  const char *fname,
557  apr_pool_t *pool);
558 
559 /** @} */
560 
561 #ifdef __cplusplus
562 }
563 #endif /* __cplusplus */
564 
565 #endif /* SVN_CONFIG_H */