OpenMPI  0.1.1
output.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) 2007-2011 Cisco Systems, Inc. All rights reserved.
13  * Copyright (c) 2010 Oracle and/or its affiliates. All rights reserved.
14  * $COPYRIGHT$
15  *
16  * Additional copyrights may follow
17  *
18  * $HEADER$
19  */
20 
21 /** @file
22  * OPAL output stream facility.
23  *
24  * The OPAL output stream facility is used to send output from the OPAL
25  * libraries to output devices. It is meant to fully replace all
26  * forms of printf() (and friends). Output streams are opened via the
27  * opal_output_open() function call, and then sent output via
28  * opal_output_verbose(), OPAL_OUTPUT(), and opal_output(). Streams are
29  * closed with opal_output_close().
30  *
31  * Streams can multiplex output to several kinds of outputs (one of
32  * each):
33  *
34  * - the syslog (if available)
35  * - standard output
36  * - standard error
37  * - file
38  *
39  * Which outputs to use are specified during opal_output_open().
40  *
41  * WARNING: When using "file" as an output destination, be aware that
42  * the file may not exist until the session directory for the process
43  * exists. This is at least part of the way through MPI_INIT (for
44  * example). Most MCA components and internals of Open MPI won't be
45  * affected by this, but some RTE / startup aspects of Open MPI will
46  * not be able to write to a file for output. See opal_output() for
47  * details on what happens in these cases.
48  *
49  * opal_output_open() returns an integer handle that is used in
50  * successive calls to OPAL_OUTPUT() and opal_output() to send output to
51  * the stream.
52  *
53  * The default "verbose" stream is opened after invoking
54  * opal_output_init() (and closed after invoking
55  * opal_output_finalize()). This stream outputs to stderr only, and
56  * has a stream handle ID of 0.
57  *
58  * It is erroneous to have one thread close a stream and have another
59  * try to write to it. Multiple threads writing to a single stream
60  * will be serialized in an unspecified order.
61  */
62 
63 #ifndef OPAL_OUTPUT_H_
64 #define OPAL_OUTPUT_H_
65 
66 #include "opal_config.h"
67 
68 #ifdef HAVE_STDARG_H
69 #include <stdarg.h>
70 #endif
71 
72 #include "opal/class/opal_object.h"
73 
74 BEGIN_C_DECLS
75 
76 /* There are systems where all output needs to be redirected to syslog
77  * and away from stdout/stderr or files - e.g., embedded systems whose
78  * sole file system is in flash. To support such systems, we provide
79  * the following environmental variables that support redirecting -all-
80  * output (both from opal_output and stdout/stderr of processes) to
81  * syslog:
82  *
83  * OPAL_OUTPUT_REDIRECT - set to "syslog" to redirect to syslog. Other
84  * options may someday be supported
85  * OPAL_OUTPUT_SYSLOG_PRI - set to "info", "error", or "warn" to have
86  * output sent to syslog at that priority
87  * OPAL_OUTPUT_SYSLOG_IDENT - a string identifier for the log
88  *
89  * We also define two global variables that notify all other
90  * layers that output is being redirected to syslog at the given
91  * priority. These are used, for example, by the IO forwarding
92  * subsystem to tell it to dump any collected output directly to
93  * syslog instead of forwarding it to another location.
94  */
95 OPAL_DECLSPEC extern bool opal_output_redirected_to_syslog;
96 OPAL_DECLSPEC extern int opal_output_redirected_syslog_pri;
97 
98 /**
99  * \class opal_output_stream_t
100  *
101  * Structure used to request the opening of a OPAL output stream. A
102  * pointer to this structure is passed to opal_output_open() to tell
103  * the opal_output subsystem where to send output for a given stream.
104  * It is valid to specify multiple destinations of output for a stream
105  * -- output streams can be multiplexed to multiple different
106  * destinations through the opal_output facility.
107  *
108  * Note that all strings in this struct are cached on the stream by
109  * value; there is no need to keep them allocated after the return
110  * from opal_output_open().
111  */
113  /** Class parent */
115 
116  /**
117  * Indicate the starting verbosity level of the stream.
118  *
119  * Verbose levels are a convenience mechanisms, and are only
120  * consulted when output is sent to a stream through the
121  * opal_output_verbose() function. Verbose levels are ignored in
122  * OPAL_OUTPUT() and opal_output().
123  *
124  * Valid verbose levels typically start at 0 (meaning "minimal
125  * information"). Higher verbosity levels generally indicate that
126  * more output and diagnostics should be displayed.
127  */
129 
130  /**
131  * When opal_output_stream_t::lds_want_syslog is true, this field is
132  * examined to see what priority output from the stream should be
133  * sent to the syslog.
134  *
135  * This value should be set as per the syslog(3) man page. It is
136  * typically the OR value of "facilty" and "level" values described
137  * in the man page.
138  */
140  /**
141  * When opal_output_stream_t::lds_want_syslog is true, this field is
142  * examined to see what ident value should be passed to openlog(3).
143  *
144  * If a NULL value is given, the string "opal" is used.
145  */
146 #if !defined(__WINDOWS__)
148 #elif !defined(_MSC_VER)
149  char *lds_syslog_ident;
150 #else
151  HANDLE lds_syslog_ident;
152 #endif /* !defined(__WINDOWS__) */
153 
154  /**
155  * String prefix added to all output on the stream.
156  *
157  * When this field is non-NULL, it is prefixed to all lines of
158  * output on the stream. When this field is NULL, no prefix is
159  * added to each line of output in the stream. The prefix is copied
160  * to an internal structure in the call to opal_output_open()!
161  */
162  char *lds_prefix;
163 
164  /**
165  * String suffix added to all output on the stream.
166  *
167  * When this field is non-NULL, it is appended to all lines of
168  * output on the stream. When this field is NULL, no suffix is
169  * added to each line of output in the stream. The suffix is copied
170  * to an internal structure in the call to opal_output_open()!
171  */
172  char *lds_suffix;
173 
174  /**
175  * Indicates whether the output of the stream is
176  * debugging/developer-only output or not.
177  *
178  * This field should be "true" if the output is for debugging
179  * purposes only. In that case, the output will never be sent to
180  * the stream unless OPAL was configured with --enable-debug.
181  */
183 
184  /**
185  * Indicates whether output of the stream should be sent to the
186  * syslog or not.
187  *
188  * If this field is true, output from this stream is sent to the
189  * syslog, and the following fields are also examined:
190  *
191  * - lds_syslog_priority
192  * - lds_syslog_ident
193  * - lds_prefix
194  *
195  * If this field is false, the above three fields are ignored.
196  */
198 
199  /**
200  * Whether to send stream output to stdout or not.
201  *
202  * If this field is true, stream output is sent to stdout.
203  */
205  /**
206  * Whether to send stream output to stderr or not.
207  *
208  * If this field is true, stream output is sent to stderr.
209  */
211 
212  /**
213  * Whether to send stream output to a file or not.
214  *
215  * When this field is true, stream output is sent to a file, and the
216  * following fields are also examined:
217  *
218  * - lds_want_file_append
219  * - lda_file_suffix
220  */
222  /**
223  * When opal_output_stream_t::lds_want_file is true, this field
224  * indicates whether to append the file (if it exists) or overwrite
225  * it.
226  *
227  * If false, the file is opened with the O_TRUNC flag.
228  */
230  /**
231  * When opal_output_stream_t::lds_want_file is true, this field
232  * indicates the string suffix to add to the filename.
233  *
234  * The output file will be in the directory and begin with the
235  * prefix set by opal_output_set_output_file_info() (e.g.,
236  * "$dir/$prefix$suffix"). If this field is NULL and
237  * lds_want_file is true, then the suffix "output.txt" is used.
238  *
239  * Note that it is possible that the output directory may not
240  * exist when opal_output_open() is invoked. See opal_output()
241  * for details on what happens in this situation.
242  */
244 
245 };
246 
247  /**
248  * Convenience typedef
249  */
251 
252  /**
253  * Initializes the output stream system and opens a default
254  * "verbose" stream.
255  *
256  * @retval true Upon success.
257  * @retval false Upon failure.
258  *
259  * This should be the first function invoked in the output
260  * subsystem. After this call, the default "verbose" stream is open
261  * and can be written to via calls to opal_output_verbose() and
262  * opal_output_error().
263  *
264  * By definition, the default verbose stream has a handle ID of 0,
265  * and has a verbose level of 0.
266  */
267  OPAL_DECLSPEC bool opal_output_init(void);
268 
269  /**
270  * Shut down the output stream system.
271  *
272  * Shut down the output stream system, including the default verbose
273  * stream.
274  */
275  OPAL_DECLSPEC void opal_output_finalize(void);
276 
277  /**
278  * Opens an output stream.
279  *
280  * @param lds A pointer to opal_output_stream_t describing what the
281  * characteristics of the output stream should be.
282  *
283  * This function opens an output stream and returns an integer
284  * handle. The caller is responsible for maintaining the handle and
285  * using it in successive calls to OPAL_OUTPUT(), opal_output(),
286  * opal_output_switch(), and opal_output_close().
287  *
288  * If lds is NULL, the default descriptions will be used, meaning
289  * that output will only be sent to stderr.
290  *
291  * It is safe to have multiple threads invoke this function
292  * simultaneously; their execution will be serialized in an
293  * unspecified manner.
294  *
295  * Be sure to see opal_output() for a description of what happens
296  * when open_open() / opal_output() is directed to send output to a
297  * file but the process session directory does not yet exist.
298  */
299  OPAL_DECLSPEC int opal_output_open(opal_output_stream_t *lds);
300 
301  /**
302  * Re-opens / redirects an output stream.
303  *
304  * @param output_id Stream handle to reopen
305  * @param lds A pointer to opal_output_stream_t describing what the
306  * characteristics of the reopened output stream should be.
307  *
308  * This function redirects an existing stream into a new [set of]
309  * location[s], as specified by the lds parameter. If the output_id
310  * passed is invalid, this call is effectively the same as opening a
311  * new stream with a specific stream handle.
312  */
313  OPAL_DECLSPEC int opal_output_reopen(int output_id, opal_output_stream_t *lds);
314 
315  /**
316  * Enables and disables output streams.
317  *
318  * @param output_id Stream handle to switch
319  * @param enable Boolean indicating whether to enable the stream
320  * output or not.
321  *
322  * @returns The previous enable state of the stream (true == enabled,
323  * false == disabled).
324  *
325  * The output of a stream can be temporarily disabled by passing an
326  * enable value to false, and later resumed by passing an enable
327  * value of true. This does not close the stream -- it simply tells
328  * the opal_output subsystem to intercept and discard any output sent
329  * to the stream via OPAL_OUTPUT() or opal_output() until the output
330  * is re-enabled.
331  */
332  OPAL_DECLSPEC bool opal_output_switch(int output_id, bool enable);
333 
334  /**
335  * \internal
336  *
337  * Reopens all existing output streams.
338  *
339  * This function should never be called by user applications; it is
340  * typically only invoked after a restart (i.e., in a new process)
341  * where output streams need to be re-initialized.
342  */
343  OPAL_DECLSPEC void opal_output_reopen_all(void);
344 
345  /**
346  * Close an output stream.
347  *
348  * @param output_id Handle of the stream to close.
349  *
350  * Close an output stream. No output will be sent to the stream
351  * after it is closed. Be aware that output handles tend to be
352  * re-used; it is possible that after a stream is closed, if another
353  * stream is opened, it will get the same handle value.
354  */
355  OPAL_DECLSPEC void opal_output_close(int output_id);
356 
357  /**
358  * Main function to send output to a stream.
359  *
360  * @param output_id Stream id returned from opal_output_open().
361  * @param format printf-style format string.
362  * @param varargs printf-style varargs list to fill the string
363  * specified by the format parameter.
364  *
365  * This is the main function to send output to custom streams (note
366  * that output to the default "verbose" stream is handled through
367  * opal_output_verbose() and opal_output_error()).
368  *
369  * It is never necessary to send a trailing "\n" in the strings to
370  * this function; some streams requires newlines, others do not --
371  * this function will append newlines as necessary.
372  *
373  * Verbosity levels are ignored in this function.
374  *
375  * Note that for output streams that are directed to files, the
376  * files are stored under the process' session directory. If the
377  * session directory does not exist when opal_output() is invoked,
378  * the output will be discarded! Once the session directory is
379  * created, opal_output() will automatically create the file and
380  * writing to it.
381  */
382  OPAL_DECLSPEC void opal_output(int output_id, const char *format, ...) __opal_attribute_format__(__printf__, 2, 3);
383 
384  /**
385  * Send output to a stream only if the passed verbosity level is
386  * high enough.
387  *
388  * @param output_id Stream id returned from opal_output_open().
389  * @param level Target verbosity level.
390  * @param format printf-style format string.
391  * @param varargs printf-style varargs list to fill the string
392  * specified by the format parameter.
393  *
394  * Output is only sent to the stream if the current verbosity level
395  * is greater than or equal to the level parameter. This mechanism
396  * can be used to send "information" kinds of output to user
397  * applications, but only when the user has asked for a high enough
398  * verbosity level.
399  *
400  * It is never necessary to send a trailing "\n" in the strings to
401  * this function; some streams requires newlines, others do not --
402  * this function will append newlines as necessary.
403  *
404  * This function is really a convenience wrapper around checking the
405  * current verbosity level set on the stream, and if the passed
406  * level is less than or equal to the stream's verbosity level, this
407  * function will effectively invoke opal_output to send the output to
408  * the stream.
409  *
410  * @see opal_output_set_verbosity()
411  */
412  OPAL_DECLSPEC void opal_output_verbose(int verbose_level, int output_id,
413  const char *format, ...) __opal_attribute_format__(__printf__, 3, 4);
414 
415  /**
416  * Same as opal_output_verbose(), but takes a va_list form of varargs.
417  */
418  OPAL_DECLSPEC void opal_output_vverbose(int verbose_level, int output_id,
419  const char *format, va_list ap) __opal_attribute_format__(__printf__, 3, 0);
420 
421  /**
422  * Send output to a string if the verbosity level is high enough.
423  *
424  * @param output_id Stream id returned from opal_output_open().
425  * @param level Target verbosity level.
426  * @param format printf-style format string.
427  * @param varargs printf-style varargs list to fill the string
428  * specified by the format parameter.
429  *
430  * Exactly the same as opal_output_verbose(), except the output it
431  * sent to a string instead of to the stream. If the verbose
432  * level is not high enough, NULL is returned. The caller is
433  * responsible for free()'ing the returned string.
434  */
435  OPAL_DECLSPEC char *opal_output_string(int verbose_level, int output_id,
436  const char *format, ...) __opal_attribute_format__(__printf__, 3, 4);
437 
438  /**
439  * Same as opal_output_string, but accepts a va_list form of varargs.
440  */
441  OPAL_DECLSPEC char *opal_output_vstring(int verbose_level, int output_id,
442  const char *format, va_list ap) __opal_attribute_format__(__printf__, 3, 0);
443 
444  /**
445  * Set the verbosity level for a stream.
446  *
447  * @param output_id Stream id returned from opal_output_open().
448  * @param level New verbosity level
449  *
450  * This function sets the verbosity level on a given stream. It
451  * will be used for all future invocations of opal_output_verbose().
452  */
453  OPAL_DECLSPEC void opal_output_set_verbosity(int output_id, int level);
454 
455  /**
456  * Get the verbosity level for a stream
457  *
458  * @param output_id Stream id returned from opal_output_open()
459  * @returns Verbosity of stream
460  */
461  OPAL_DECLSPEC int opal_output_get_verbosity(int output_id);
462 
463  /**
464  * Set characteristics for output files.
465  *
466  * @param dir Directory where output files will go
467  * @param olddir If non-NULL, the directory where output files
468  * were previously opened
469  * @param prefix Prefix of files in the output directory
470  * @param oldprefix If non-NULL, the old prefix
471  *
472  * This function controls the final filename used for all new
473  * output streams that request output files. Specifically, when
474  * opal_output_stream_t::lds_want_file is true, the output
475  * filename will be of the form $dir/$prefix$suffix.
476  *
477  * The default value for the output directory is whatever is
478  * specified in the TMPDIR environment variable if it exists, or
479  * $HOME if it does not. The default value for the prefix is
480  * "output-pid<pid>-" (where "<pid>" is replaced by the PID of the
481  * current process).
482  *
483  * If dir or prefix are NULL, new values are not set. The strings
484  * represented by dir and prefix are copied into internal storage;
485  * it is safe to pass string constants or free() these values
486  * after opal_output_set_output_file_info() returns.
487  *
488  * If olddir or oldprefix are not NULL, copies of the old
489  * directory and prefix (respectively) are returned in these
490  * parameters. The caller is responsible for calling (free) on
491  * these values. This allows one to get the old values, output an
492  * output file in a specific directory and/or with a specific
493  * prefix, and then restore the old values.
494  *
495  * Note that this function only affects the creation of \em new
496  * streams -- streams that have already started writing to output
497  * files are not affected (i.e., their output files are not moved
498  * to the new directory). More specifically, the opal_output
499  * system only opens/creates output files lazily -- so calling
500  * this function affects both new streams \em and any stream that
501  * was previously opened but had not yet output anything.
502  */
503  OPAL_DECLSPEC void opal_output_set_output_file_info(const char *dir,
504  const char *prefix,
505  char **olddir,
506  char **oldprefix);
507 
508 #if OPAL_ENABLE_DEBUG
509  /**
510  * Main macro for use in sending debugging output to output streams;
511  * will be "compiled out" when OPAL is configured without
512  * --enable-debug.
513  *
514  * @see opal_output()
515  */
516 #define OPAL_OUTPUT(a) opal_output a
517 
518  /**
519  * Macro for use in sending debugging output to the output
520  * streams. Will be "compiled out" when OPAL is configured
521  * without --enable-debug.
522  *
523  * @see opal_output_verbose()
524  */
525 #define OPAL_OUTPUT_VERBOSE(a) opal_output_verbose a
526 #else
527  /**
528  * Main macro for use in sending debugging output to output streams;
529  * will be "compiled out" when OPAL is configured without
530  * --enable-debug.
531  *
532  * @see opal_output()
533  */
534 #define OPAL_OUTPUT(a)
535 
536  /**
537  * Macro for use in sending debugging output to the output
538  * streams. Will be "compiled out" when OPAL is configured
539  * without --enable-debug.
540  *
541  * @see opal_output_verbose()
542  */
543 #define OPAL_OUTPUT_VERBOSE(a)
544 #endif
545 
546 /**
547  * Declare the class of this type. Note that the constructor for
548  * this class is for convenience only -- it is \em not necessary
549  * to be invoked. If the constructor it used, it sets all values
550  * in the struct to be false / 0 (i.e., turning off all output).
551  * The intended usage is to invoke the constructor and then enable
552  * the output fields that you want.
553  */
555 
556 END_C_DECLS
557 
558 #endif /* OPAL_OUTPUT_H_ */
559 
OPAL_DECLSPEC void opal_output_set_output_file_info(const char *dir, const char *prefix, char **olddir, char **oldprefix)
Set characteristics for output files.
Definition: output.c:469
opal_object_t super
Class parent.
Definition: output.h:114
OPAL_DECLSPEC int opal_output_open(opal_output_stream_t *lds)
Opens an output stream.
Definition: output.c:216
OPAL_DECLSPEC void opal_output_close(int output_id)
Close an output stream.
Definition: output.c:321
OPAL_DECLSPEC void OPAL_DECLSPEC void opal_output_verbose(int verbose_level, int output_id, const char *format,...) __opal_attribute_format__(__printf__
Send output to a stream only if the passed verbosity level is high enough.
Structure used to request the opening of a OPAL output stream.
Definition: output.h:112
bool lds_want_syslog
Indicates whether output of the stream should be sent to the syslog or not.
Definition: output.h:197
OPAL_DECLSPEC void OPAL_DECLSPEC void OPAL_DECLSPEC void OPAL_DECLSPEC char * opal_output_string(int verbose_level, int output_id, const char *format,...) __opal_attribute_format__(__printf__
Send output to a string if the verbosity level is high enough.
char * lds_file_suffix
When opal_output_stream_t::lds_want_file is true, this field indicates the string suffix to add to th...
Definition: output.h:243
int lds_verbose_level
Indicate the starting verbosity level of the stream.
Definition: output.h:128
char * lds_syslog_ident
When opal_output_stream_t::lds_want_syslog is true, this field is examined to see what ident value sh...
Definition: output.h:147
char * lds_suffix
String suffix added to all output on the stream.
Definition: output.h:172
OPAL_DECLSPEC int opal_output_reopen(int output_id, opal_output_stream_t *lds)
Re-opens / redirects an output stream.
Definition: output.c:225
OPAL_DECLSPEC void opal_output_finalize(void)
Shut down the output stream system.
Definition: output.c:495
int lds_syslog_priority
When opal_output_stream_t::lds_want_syslog is true, this field is examined to see what priority outpu...
Definition: output.h:139
OPAL_DECLSPEC void opal_output(int output_id, const char *format,...) __opal_attribute_format__(__printf__
Main function to send output to a stream.
OPAL_DECLSPEC OBJ_CLASS_DECLARATION(opal_output_stream_t)
Declare the class of this type.
OPAL_DECLSPEC int opal_output_get_verbosity(int output_id)
Get the verbosity level for a stream.
Definition: output.c:948
bool lds_is_debugging
Indicates whether the output of the stream is debugging/developer-only output or not.
Definition: output.h:182
OPAL_DECLSPEC bool opal_output_init(void)
Initializes the output stream system and opens a default "verbose" stream.
Definition: output.c:124
OPAL_DECLSPEC void OPAL_DECLSPEC void OPAL_DECLSPEC void OPAL_DECLSPEC char OPAL_DECLSPEC char OPAL_DECLSPEC void opal_output_set_verbosity(int output_id, int level)
Set the verbosity level for a stream.
Definition: output.c:458
Base object.
Definition: opal_object.h:182
bool lds_want_stdout
Whether to send stream output to stdout or not.
Definition: output.h:204
char * lds_prefix
String prefix added to all output on the stream.
Definition: output.h:162
bool lds_want_stderr
Whether to send stream output to stderr or not.
Definition: output.h:210
OPAL_DECLSPEC void OPAL_DECLSPEC void OPAL_DECLSPEC void OPAL_DECLSPEC char OPAL_DECLSPEC char * opal_output_vstring(int verbose_level, int output_id, const char *format, va_list ap) __opal_attribute_format__(__printf__
Same as opal_output_string, but accepts a va_list form of varargs.
A simple C-language object-oriented system with single inheritance and ownership-based memory managem...
bool lds_want_file_append
When opal_output_stream_t::lds_want_file is true, this field indicates whether to append the file (if...
Definition: output.h:229
OPAL_DECLSPEC bool opal_output_switch(int output_id, bool enable)
Enables and disables output streams.
Definition: output.c:234
bool lds_want_file
Whether to send stream output to a file or not.
Definition: output.h:221
OPAL_DECLSPEC void OPAL_DECLSPEC void OPAL_DECLSPEC void opal_output_vverbose(int verbose_level, int output_id, const char *format, va_list ap) __opal_attribute_format__(__printf__
Same as opal_output_verbose(), but takes a va_list form of varargs.