OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

show_help.h
Go to the documentation of this file.
1 /*
2 * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
3 * University Research and Technology
4 * Corporation. All rights reserved.
5 * Copyright (c) 2004-2006 The University of Tennessee and The University
6 * of Tennessee Research Foundation. All rights
7 * reserved.
8 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
9 * University of Stuttgart. All rights reserved.
10 * Copyright (c) 2004-2005 The Regents of the University of California.
11 * All rights reserved.
12 * Copyright (c) 2008-2011 Cisco Systems, Inc. All rights reserved.
13 * $COPYRIGHT$
14 *
15 * Additional copyrights may follow
16 *
17 * $HEADER$
18 */
19 /**
20 * @file
21 *
22 * The "show help" subsystem (SHS) in Open MPI is intended to help the
23 * developer convey meaningful information to the user (read longer
24 * than is convenient in a single printf), particularly when errors
25 * occur. The SHS allows the storage of arbitrary-length help
26 * messages in text files which can be parameterized by text filename,
27 * message name, POSIX locale, and printf()-style parameters (e.g.,
28 * "%s", "%d", etc.). Note that the primary purpose of the SHS is to
29 * display help messages, but it can actually be used to display any
30 * arbitrary text messages.
31 *
32 * The function opal_show_help() is used to find a help message and
33 * display it. Its important parameters are a filename, message name,
34 * and printf()-style varargs parameters used to substitute into the
35 * message.
36 *
37 * It was originally intended that this system would support a very
38 * simple version of i18n-like support, but we got (strong) feedback
39 * that i18n support was not desired. So it never happened.
40 *
41 * As such, the file lookup is quite straightforward -- the caller
42 * passes in the filename to find the help message, and the SHS looks
43 * for that file in $pkgdatadir (typically $prefix/share/openmpi).
44 *
45 * Once the file is successfully opened, the SHS looks for the
46 * appropriate help message to display. It looks for the message name
47 * in the file, reads in the message, and displays it. printf()-like
48 * substitutions are performed (e.g., %d, %s, etc.) --
49 * opal_show_help() takes a variable legnth argument list that are
50 * used for these substitutions.
51 *
52 * The format of the help file is simplistic:
53 *
54 * - Comments begin with #. Any characters after a # on a line are
55 * ignored. It is not possible to escape a #.
56 * - Message names are on a line by themselves and marked with [].
57 * Names can be any ASCII string within the [] (excluding the
58 * characters newline, linefeed, [, ], and #).
59 * - Messages are any characters between message names and/or the end
60 * of the file.
61 *
62 * Here's a sample helpfile:
63 *
64 * \verbatimbegin
65 * # This is a comment.
66 * [topic 1]
67 * Here's the first message. Let's substitute in an integer: %d.
68 * The quick brown fox jumped over the lazy %s.
69 * # This is another comment -- it's not displayed in the first message.
70 * [another:topic:foo:foo:foo]
71 * This is the second message. Let's just keep rolling along to get
72 * to the second line in the message for this example.
73 * \verbatimend
74 *
75 * It is expected that help messages will be grouped by filename;
76 * similar messages should be in a single file. For example, an MCA
77 * component may install its own helpfile in Open MPI's $pkgdatadir,
78 * and therefore the component can invoke opal_show_help() to display
79 * its own help messages.
80 *
81 * Message files in $pkgdatadir have a naming convention: they
82 * generally start with the prefix "help-" and are followed by a name
83 * descriptive of what kind of messages they contain. MCA components
84 * should generally abide by the MCA prefix rule, with the exception
85 * that they should start the filename with "help-", as mentioned
86 * previously.
87 */
88
89 #ifndef OPAL_SHOW_HELP_H
90 #define OPAL_SHOW_HELP_H
91
92 #include "opal_config.h"
93
94 #include <stdarg.h>
95
96 BEGIN_C_DECLS
97
98 /**
99 * \internal
100 *
101 * Initialization of show_help subsystem
102 */
103 OPAL_DECLSPEC int opal_show_help_init(void);
104
105
106 /**
107 * \internal
108 *
109 * Finalization of show_help subsystem
110 */
111 OPAL_DECLSPEC int opal_show_help_finalize(void);
112
113
114 /**
115 * Look up a text message in a text file and display it to the
116 * stderr using printf()-like substitutions (%d, %s, etc.).
117 *
118 * @param filename File where the text messages are contained.
119 * @param topic String index of which message to display from the
120 * text file.
121 * @param want_error_header Display error-bar line header and
122 * footer with the message.
123 * @param varargs Any additional parameters are substituted,
124 * printf()-style into the help message that is displayed.
125 *
126 * This function looks for the filename in the $pkgdatadir
127 * (typically $prefix/share/openmpi), and looks up the message
128 * based on the topic, and displays it. If want_error_header is
129 * true, a header and footer of asterisks are also displayed.
130 */
131 typedef int (*opal_show_help_fn_t)(const char *filename, const char *topic,
132 bool want_error_header, ...);
133 OPAL_DECLSPEC extern opal_show_help_fn_t opal_show_help;
134
135 /**
136 * This function does the same thing as opal_show_help(), but accepts
137 * a va_list form of varargs.
138 */
139 typedef int (*opal_show_vhelp_fn_t)(const char *filename, const char *topic,
140 bool want_error_header, va_list ap);
141 OPAL_DECLSPEC extern opal_show_vhelp_fn_t opal_show_vhelp;
142
143 /**
144 * This function does the same thing as opal_show_help(), but returns
145 * its output in a string (that must be freed by the caller).
146 */
147 OPAL_DECLSPEC char* opal_show_help_string(const char *filename,
148 const char *topic,
149 bool want_error_header, ...);
150
151 /**
152 * This function does the same thing as opal_show_help_string(), but
153 * accepts a va_list form of varargs.
154 */
155 OPAL_DECLSPEC char* opal_show_help_vstring(const char *filename,
156 const char *topic,
157 bool want_error_header, va_list ap);
158
159 /**
160 * This function adds another search location for the files that
161 * back show_help messages. Locations will be searched starting
162 * with the prefix installation directory, then cycled through
163 * any additional directories in the order they were added
164 *
165 * This interface allows libraries that use OMPI to take advantage
166 * of the show_help functionality. OMPI defines the show_help directory
167 * based on where OMPI was installed. However, if the library wants to
168 * use show_help to provide error output specific to itself, then it
169 * nees to tell show_help how to find its own show_help files - without
170 * interfering with the linked ORTE libs when they need to do show_help.
171 */
172 OPAL_DECLSPEC int opal_show_help_add_dir(const char *directory);
173
174 /**
175 * \internal
176 *
177 * Internal function to help clean up the flex parser.
178 *
179 * This function is called internally by the SHS to shut down the
180 * flex parser since we may not hit the <<EOF>> rule and call this
181 * function automatically.
182 */
183 OPAL_DECLSPEC int opal_show_help_finish_parsing(void);
184
185 END_C_DECLS
186
187 #endif
opal_show_vhelp_fn_t
int(* opal_show_vhelp_fn_t)(const char *filename, const char *topic, bool want_error_header, va_list ap)
This function does the same thing as opal_show_help(), but accepts a va_list form of varargs...
Definition: show_help.h:139
opal_show_help_string
OPAL_DECLSPEC char * opal_show_help_string(const char *filename, const char *topic, bool want_error_header,...)
This function does the same thing as opal_show_help(), but returns its output in a string (that must ...
Definition: show_help.c:317
opal_show_help_vstring
OPAL_DECLSPEC char * opal_show_help_vstring(const char *filename, const char *topic, bool want_error_header, va_list ap)
This function does the same thing as opal_show_help_string(), but accepts a va_list form of varargs...
Definition: show_help.c:293
opal_show_help_add_dir
OPAL_DECLSPEC int opal_show_help_add_dir(const char *directory)
This function adds another search location for the files that back show_help messages.
Definition: show_help.c:363
opal_show_help_fn_t
int(* opal_show_help_fn_t)(const char *filename, const char *topic, bool want_error_header,...)
Look up a text message in a text file and display it to the stderr using printf()-like substitutions ...
Definition: show_help.h:131