3 * ====================================================================
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
12 * http://www.apache.org/licenses/LICENSE-2.0
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
20 * ====================================================================
24 * @brief Support functions for command line programs
33 #include <apr_pools.h>
34 #include <apr_getopt.h>
36 #ifndef DOXYGEN_SHOULD_SKIP_THIS
37 #define APR_WANT_STDIO
41 #include "svn_types.h"
43 #include "svn_config.h"
47 #endif /* __cplusplus */
50 /** Set up the locale for character conversion, and initialize APR.
51 * If @a error_stream is non-NULL, print error messages to the stream,
52 * using @a progname as the program name. Attempt to set @c stdout to
53 * line-buffered mode, and @a error_stream to unbuffered mode. Return
54 * @c EXIT_SUCCESS if successful, otherwise @c EXIT_FAILURE.
56 * @note This function should be called exactly once at program startup,
57 * before calling any other APR or Subversion functions.
60 svn_cmdline_init(const char *progname,
64 /** Set @a *dest to an output-encoded C string from UTF-8 C string @a
65 * src; allocate @a *dest in @a pool.
68 svn_cmdline_cstring_from_utf8(const char **dest,
72 /** Like svn_utf_cstring_from_utf8_fuzzy(), but converts to an
73 * output-encoded C string. */
75 svn_cmdline_cstring_from_utf8_fuzzy(const char *src,
78 /** Set @a *dest to a UTF-8-encoded C string from input-encoded C
79 * string @a src; allocate @a *dest in @a pool.
82 svn_cmdline_cstring_to_utf8(const char **dest,
86 /** Set @a *dest to an output-encoded natively-formatted path string
87 * from canonical path @a src; allocate @a *dest in @a pool.
90 svn_cmdline_path_local_style_from_utf8(const char **dest,
94 /** Write to stdout, using a printf-like format string @a fmt, passed
95 * through apr_pvsprintf(). All string arguments are in UTF-8; the output
96 * is converted to the output encoding. Use @a pool for temporary
102 svn_cmdline_printf(apr_pool_t *pool,
105 __attribute__((format(printf, 2, 3)));
107 /** Write to the stdio @a stream, using a printf-like format string @a fmt,
108 * passed through apr_pvsprintf(). All string arguments are in UTF-8;
109 * the output is converted to the output encoding. Use @a pool for
110 * temporary allocation.
115 svn_cmdline_fprintf(FILE *stream,
119 __attribute__((format(printf, 3, 4)));
121 /** Output the @a string to the stdio @a stream, converting from UTF-8
122 * to the output encoding. Use @a pool for temporary allocation.
127 svn_cmdline_fputs(const char *string,
131 /** Flush output buffers of the stdio @a stream, returning an error if that
132 * fails. This is just a wrapper for the standard fflush() function for
133 * consistent error handling.
138 svn_cmdline_fflush(FILE *stream);
140 /** Return the name of the output encoding allocated in @a pool, or @c
141 * APR_LOCALE_CHARSET if the output encoding is the same as the locale
147 svn_cmdline_output_encoding(apr_pool_t *pool);
149 /** Handle @a error in preparation for immediate exit from a
150 * command-line client. Specifically:
152 * Call svn_handle_error2(@a error, stderr, FALSE, @a prefix), clear
153 * @a error, destroy @a pool iff it is non-NULL, and return EXIT_FAILURE.
158 svn_cmdline_handle_exit_error(svn_error_t *error,
162 /** A prompt function/baton pair, and the path to the configuration
163 * directory. To be passed as the baton argument to the
164 * @c svn_cmdline_*_prompt functions.
168 typedef struct svn_cmdline_prompt_baton2_t {
169 svn_cancel_func_t cancel_func;
171 const char *config_dir;
172 } svn_cmdline_prompt_baton2_t;
174 /** Like svn_cmdline_prompt_baton2_t, but without the path to the
175 * configuration directory.
178 * @deprecated Provided for backward compatibility with the 1.5 API.
180 typedef struct svn_cmdline_prompt_baton_t {
181 svn_cancel_func_t cancel_func;
183 } svn_cmdline_prompt_baton_t;
185 /** Prompt the user for input, using @a prompt_str for the prompt and
186 * @a baton (which may be @c NULL) for cancellation, and returning the
187 * user's response in @a result, allocated in @a pool.
192 svn_cmdline_prompt_user2(const char **result,
193 const char *prompt_str,
194 svn_cmdline_prompt_baton_t *baton,
197 /** Similar to svn_cmdline_prompt_user2, but without cancellation
200 * @deprecated Provided for backward compatibility with the 1.4 API.
204 svn_cmdline_prompt_user(const char **result,
205 const char *prompt_str,
208 /** An implementation of @c svn_auth_simple_prompt_func_t that prompts
209 * the user for keyboard input on the command line.
213 * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
216 svn_cmdline_auth_simple_prompt(svn_auth_cred_simple_t **cred_p,
219 const char *username,
220 svn_boolean_t may_save,
224 /** An implementation of @c svn_auth_username_prompt_func_t that prompts
225 * the user for their username via the command line.
229 * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
232 svn_cmdline_auth_username_prompt(svn_auth_cred_username_t **cred_p,
235 svn_boolean_t may_save,
239 /** An implementation of @c svn_auth_ssl_server_trust_prompt_func_t that
240 * asks the user if they trust a specific ssl server via the command line.
244 * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
247 svn_cmdline_auth_ssl_server_trust_prompt(
248 svn_auth_cred_ssl_server_trust_t **cred_p,
251 apr_uint32_t failures,
252 const svn_auth_ssl_server_cert_info_t *cert_info,
253 svn_boolean_t may_save,
257 /** An implementation of @c svn_auth_ssl_client_cert_prompt_func_t that
258 * prompts the user for the filename of their SSL client certificate via
261 * Records absolute path of the SSL client certificate file.
265 * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
268 svn_cmdline_auth_ssl_client_cert_prompt(
269 svn_auth_cred_ssl_client_cert_t **cred_p,
272 svn_boolean_t may_save,
276 /** An implementation of @c svn_auth_ssl_client_cert_pw_prompt_func_t that
277 * prompts the user for their SSL certificate password via the command line.
281 * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
284 svn_cmdline_auth_ssl_client_cert_pw_prompt(
285 svn_auth_cred_ssl_client_cert_pw_t **cred_p,
288 svn_boolean_t may_save,
291 /** An implementation of @c svn_auth_plaintext_prompt_func_t that
292 * prompts the user whether storing unencrypted passwords to disk is OK.
294 * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton.
299 svn_cmdline_auth_plaintext_prompt(svn_boolean_t *may_save_plaintext,
300 const char *realmstring,
304 /** An implementation of @c svn_auth_plaintext_passphrase_prompt_func_t that
305 * prompts the user whether storing unencrypted passphrase to disk is OK.
307 * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton.
312 svn_cmdline_auth_plaintext_passphrase_prompt(svn_boolean_t *may_save_plaintext,
313 const char *realmstring,
318 /** Set @a *ab to an authentication baton allocated from @a pool and
319 * initialized with the standard set of authentication providers used
320 * by the command line client.
322 * @a non_interactive, @a username, @a password, @a config_dir,
323 * @a no_auth_cache, and @a trust_server_cert are the values of the
324 * command line options of the corresponding names.
326 * @a cfg is the @c SVN_CONFIG_CATEGORY_CONFIG configuration, and
327 * @a cancel_func and @a cancel_baton control the cancellation of the
328 * prompting providers that are initialized.
330 * Use @a pool for all allocations.
335 svn_cmdline_create_auth_baton(svn_auth_baton_t **ab,
336 svn_boolean_t non_interactive,
337 const char *username,
338 const char *password,
339 const char *config_dir,
340 svn_boolean_t no_auth_cache,
341 svn_boolean_t trust_server_cert,
343 svn_cancel_func_t cancel_func,
347 /** Similar to svn_cmdline_create_auth_baton(), but with
348 * @a trust_server_cert always set to false.
351 * @deprecated Provided for backward compatibility with the 1.5 API.
352 * Use svn_cmdline_create_auth_baton() instead.
354 * @note This deprecation does not follow the usual pattern of putting
355 * a new number on end of the function's name. Instead, the new
356 * function name is distinguished from the old by a grammatical
357 * improvement: the verb "create" instead of the noun "setup".
361 svn_cmdline_setup_auth_baton(svn_auth_baton_t **ab,
362 svn_boolean_t non_interactive,
363 const char *username,
364 const char *password,
365 const char *config_dir,
366 svn_boolean_t no_auth_cache,
368 svn_cancel_func_t cancel_func,
374 #endif /* __cplusplus */
376 #endif /* SVN_CMDLINE_H */