OpenMPI  0.1.1
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
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_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_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_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
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