1
1
openmpi/opal/util/cmd_line.h

592 строки
23 KiB
C
Исходник Обычный вид История

/* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
/*
* Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
* University Research and Technology
* Corporation. All rights reserved.
* Copyright (c) 2004-2005 The University of Tennessee and The University
* of Tennessee Research Foundation. All rights
* reserved.
2015-06-24 06:59:57 +03:00
* Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
* University of Stuttgart. All rights reserved.
* Copyright (c) 2004-2005 The Regents of the University of California.
* All rights reserved.
* Copyright (c) 2012 Cisco Systems, Inc. All rights reserved.
Refactor the ORTE DVM code so that external codes can submit multiple jobs using only a single connection to the HNP. * Clean up the DVM so it continues to run even when applications error out and we would ordinarily abort the daemons. * Create a new errmgr component for the DVM to handle the differences. * Cleanup the DVM state component. * Add ORTE bindings directory and brief README * Pass a local tool index around to match jobs. * Pass the jobid on job completion. * Fix initialization logic. * Add framework for python wrapper. * Fix terminate-with-non-zero-exit behavior so it properly terminates only the indicated procs, notifies orte-submit, and orte-dvm continues executing. * Add some missing options to orte-dvm * Fix a bug in -host processing that caused us to ignore the #slots designator. Add a new attribute to indicate "do not expand the DVM" when submitting job spawn requests. * It actually makes no sense that we treat the termination of all children differently than terminating the children of a specific job - it only creates confusion over the difference in behavior. So terminate children the same way regardless. Extend the cmd_line utility to easily allow layering of command line definitions Catch up with ORTE interface change and make build more generic. Disable "fixed dvm" logic for now. Add another cmd_line function to merge a table of cmd line options with another one, reporting as errors any duplicate entries. Use this to allow orterun to reuse the orted_submit code Fix the "fixed_dvm" logic by ensuring we reset num_new_daemons to zero. Also ensure that the nidmap is sent with the first job so the downstream daemons get the node info. Remove a duplicate cmd line entry in orterun. Revise the DVM startup procedure to pass the nidmap only once, at the startup of the DVM. This reduces the overhead on each job launch and ensures that the nidmap doesn't get overwritten. Add new commands to get_orted_comm_cmd_str(). Move ORTE command line options to orte_globals.[ch]. Catch up with extra orte_submit_init parameter. Add example code. Add documentation. Bump version. The nidmap and routing data must be updated prior to propagating the xcast or else the xcast will fail. Fix the return code so it is something more expected when an error occurs. Ensure we get an error returned to us when we fail to launch for some reason. In this case, we will always get a launch_cb as we did indeed attempt to spawn it. The error code will be returned in the complete_cb. Fix the return code from orte_submit_job - it was returning the tracker index instead of "success". Take advantage of ORTE's pretty-print capabilities to provide a nice error output explaining why we failed to launch. Ensure we always get a launch_cb when we fail to launch, but no complete_cb as the job never launched. Extend the error reporting capability to job completion as well. Add index parameter to orte_submit_job(). Add orte_job_cancel and implement ORTE_DAEMON_TERMINATE_JOB_CMD. Factor out dvm termination. Parse the terminate option at tool level. Add error string for ORTE_ERR_JOB_CANCELLED. Add some safeguards. Cleanup and/of comments. Enable the return. Properly ORTE_DECLSPEC orte_submit_halt. Add orte_submit_halt and orte_submit_cancel to interface. Use the plm interface to terminate the job
2015-12-17 02:30:40 +03:00
* Copyright (c) 2015-2016 Intel, Inc. All rights reserved.
* Copyright (c) 2016 Los Alamos National Security, LLC. All rights
* reserved.
* $COPYRIGHT$
2015-06-24 06:59:57 +03:00
*
* Additional copyrights may follow
2015-06-24 06:59:57 +03:00
*
* $HEADER$
*/
/**
2015-06-24 06:59:57 +03:00
* @file
*
* General command line parsing facility for use throughout Open MPI.
*
* This scheme is inspired by the GNU getopt package. Command line
* options are registered. Each option can have up to three different
* matching tokens: a "short" name, a "single dash" name, and a "long"
* name. Each option can also take 0 or more arguments. Finally,
* each option can be repeated on the command line an arbitrary number
* of times.
*
* The "short" name can only be a single letter, and will be found
* after a single dash (e.g., "-a"). Multiple "short" names can be
* combined into a single command line argument (e.g., "-abc" can be
* equivalent to "-a -b -c").
*
* The "single dash" name is a multi-character name that only
* requires a single dash. This only exists to provide backwards
* compatibility for some well-known command line options in prior
* MPI implementations (e.g., "mpirun -np 3"). It should be used
* sparingly.
*
* The "long" name is a multi-character name that is found after a
2015-06-24 06:59:57 +03:00
* pair of dashes. For example, "--some-option-name".
*
* A command line option is a combination of 1 or more of a short
* name, single dash name, and a long name. Any of the names may be
* used on the command line; they are treated as synonyms. For
* example, say the following was used in for an executable named
* "foo":
*
* \code
* opal_cmd_line_make_opt3(cmd, 'a', NULL, 'add', 1, "Add a user");
* \endcode
*
* In this case, the following command lines are exactly equivalent:
*
* \verbatim
* shell$ foo -a jsmith
* shell$ foo --add jsmith
* \endverbatim
*
* Note that this interface can also track multiple invocations of the
* same option. For example, the following is both legal and able to
* be retrieved through this interface:
*
* \verbatim
* shell$ foo -a jsmith -add bjones
* \endverbatim
*
* The caller to this interface creates a command line handle
* (opal_cmd_line_t) with OBJ_NEW() and then uses it to register the
* desired parameters via opal_cmd_line_make_opt3(). Once all the
* parameters have been registered, the user invokes
* opal_cmd_line_parse() with the command line handle and the argv/argc
* pair to be parsed (typically the arguments from main()). The parser
* will examine the argv and find registered options and parameters.
* It will stop parsing when it runs into an recognized string token or
* the special "--" token.
*
* After the parse has occurred, various accessor functions can be
* used to determine which options were selected, what parameters were
* passed to them, etc.:
*
* - opal_cmd_line_get_usage_msg() returns a string suitable for "help"
* kinds of messages.
* - opal_cmd_line_is_taken() returns a true or false indicating
* whether a given command line option was found on the command
* line.
* - opal_cmd_line_get_argc() returns the number of tokens parsed on
* the handle.
* - opal_cmd_line_get_argv() returns any particular string from the
* original argv.
* - opal_cmd_line_get_ninsts() returns the number of times a
* particular option was found on a command line.
* - opal_cmd_line_get_param() returns the Nth parameter in the Mth
* instance of a given parameter.
* - opal_cmd_line_get_tail() returns an array of tokens not parsed
* (i.e., if the parser ran into "--" or an unrecognized token).
*
* Note that a shortcut to creating a large number of options exists
* -- one can make a table of opal_cmd_line_init_t instances and the
* table to opal_cmd_line_create(). This creates an opal_cmd_line_t
* handle that is pre-seeded with all the options from the table
* without the need to repeatedly invoke opal_cmd_line_make_opt3() (or
* equivalent). This opal_cmd_line_t instance is just like any other;
* it is still possible to add more options via
* opal_cmd_line_make_opt3(), etc.
*/
#ifndef OPAL_CMD_LINE_H
#define OPAL_CMD_LINE_H
#include "opal_config.h"
#include "opal/class/opal_object.h"
#include "opal/class/opal_list.h"
#include "opal/threads/mutex.h"
2004-01-10 21:19:55 +03:00
- Replace combinations of #if defined (c_plusplus) defined (__cplusplus) followed by extern "C" { and the closing counterpart by BEGIN_C_DECLS and END_C_DECLS. Notable exceptions are: - opal/include/opal_config_bottom.h: This is our generated code, that itself defines BEGIN_C_DECL and END_C_DECL - ompi/mpi/cxx/mpicxx.h: Here we do not include opal_config_bottom.h: - Belongs to external code: opal/mca/backtrace/darwin/MoreBacktrace/MoreDebugging/MoreBacktrace.c opal/mca/backtrace/darwin/MoreBacktrace/MoreDebugging/MoreBacktrace.h - opal/include/opal/prefetch.h: Has C++ specific macros that are protected: - Had #if ... } #endif _and_ END_C_DECLS (aka end up with 2x END_C_DECLS) ompi/mca/btl/openib/btl_openib.h - opal/event/event.h has #ifdef __cplusplus as BEGIN_C_DECLS... - opal/win32/ompi_process.h: had extern "C"\n {... opal/win32/ompi_process.h: dito - ompi/mca/btl/pcie/btl_pcie_lex.l: needed to add *_C_DECLS ompi/mpi/f90/test/align_c.c: dito - ompi/debuggers/msgq_interface.h: used #ifdef __cplusplus - ompi/mpi/f90/xml/common-C.xsl: Amend Tested on linux using --with-openib and --with-mx The following do not contain either opal_config.h, orte_config.h or ompi_config.h (but possibly other header files, that include one of the above): ompi/mca/bml/r2/bml_r2_ft.h ompi/mca/btl/gm/btl_gm_endpoint.h ompi/mca/btl/gm/btl_gm_proc.h ompi/mca/btl/mx/btl_mx_endpoint.h ompi/mca/btl/ofud/btl_ofud_endpoint.h ompi/mca/btl/ofud/btl_ofud_frag.h ompi/mca/btl/ofud/btl_ofud_proc.h ompi/mca/btl/openib/btl_openib_mca.h ompi/mca/btl/portals/btl_portals_endpoint.h ompi/mca/btl/portals/btl_portals_frag.h ompi/mca/btl/sctp/btl_sctp_endpoint.h ompi/mca/btl/sctp/btl_sctp_proc.h ompi/mca/btl/tcp/btl_tcp_endpoint.h ompi/mca/btl/tcp/btl_tcp_ft.h ompi/mca/btl/tcp/btl_tcp_proc.h ompi/mca/btl/template/btl_template_endpoint.h ompi/mca/btl/template/btl_template_proc.h ompi/mca/btl/udapl/btl_udapl_eager_rdma.h ompi/mca/btl/udapl/btl_udapl_endpoint.h ompi/mca/btl/udapl/btl_udapl_mca.h ompi/mca/btl/udapl/btl_udapl_proc.h ompi/mca/mtl/mx/mtl_mx_endpoint.h ompi/mca/mtl/mx/mtl_mx.h ompi/mca/mtl/psm/mtl_psm_endpoint.h ompi/mca/mtl/psm/mtl_psm.h ompi/mca/pml/cm/pml_cm_component.h ompi/mca/pml/csum/pml_csum_comm.h ompi/mca/pml/dr/pml_dr_comm.h ompi/mca/pml/dr/pml_dr_component.h ompi/mca/pml/dr/pml_dr_endpoint.h ompi/mca/pml/dr/pml_dr_recvfrag.h ompi/mca/pml/example/pml_example.h ompi/mca/pml/ob1/pml_ob1_comm.h ompi/mca/pml/ob1/pml_ob1_component.h ompi/mca/pml/ob1/pml_ob1_endpoint.h ompi/mca/pml/ob1/pml_ob1_rdmafrag.h ompi/mca/pml/ob1/pml_ob1_recvfrag.h ompi/mca/pml/v/pml_v_output.h opal/include/opal/prefetch.h opal/mca/timer/aix/timer_aix.h opal/util/qsort.h test/support/components.h This commit was SVN r21855. The following SVN revision numbers were found above: r2 --> open-mpi/ompi@58fdc188553052bc2e893ba28fb28fddbe78435a
2009-08-20 15:42:18 +04:00
BEGIN_C_DECLS
/**
* \internal
*
* Main top-level handle. This interface should not be used by users!
*/
struct opal_cmd_line_t {
/** Make this an OBJ handle */
opal_object_t super;
2015-06-24 06:59:57 +03:00
/** Thread safety */
opal_mutex_t lcl_mutex;
2015-06-24 06:59:57 +03:00
/** List of cmd_line_option_t's (defined internally) */
opal_list_t lcl_options;
2015-06-24 06:59:57 +03:00
/** Duplicate of argc from opal_cmd_line_parse() */
int lcl_argc;
/** Duplicate of argv from opal_cmd_line_parse() */
char **lcl_argv;
2015-06-24 06:59:57 +03:00
/** Parsed output; list of cmd_line_param_t's (defined internally) */
opal_list_t lcl_params;
2015-06-24 06:59:57 +03:00
/** List of tail (unprocessed) arguments */
int lcl_tail_argc;
/** List of tail (unprocessed) arguments */
char **lcl_tail_argv;
};
/**
* \internal
*
* Convenience typedef
*/
typedef struct opal_cmd_line_t opal_cmd_line_t;
/**
* Data types supported by the parser
*/
enum opal_cmd_line_type_t {
OPAL_CMD_LINE_TYPE_NULL,
OPAL_CMD_LINE_TYPE_STRING,
OPAL_CMD_LINE_TYPE_INT,
OPAL_CMD_LINE_TYPE_SIZE_T,
OPAL_CMD_LINE_TYPE_BOOL,
OPAL_CMD_LINE_TYPE_MAX
};
/**
* \internal
*
* Convenience typedef
*/
typedef enum opal_cmd_line_type_t opal_cmd_line_type_t;
/**
* Datatype used to construct a command line handle; see
* opal_cmd_line_create().
*/
struct opal_cmd_line_init_t {
/** If want to set an MCA parameter, set its parameter name
here. */
const char *ocl_mca_param_name;
/** "Short" name (i.e., "-X", where "X" is a single letter) */
char ocl_cmd_short_name;
/** "Single dash" name (i.e., "-foo"). The use of these are
discouraged. */
const char *ocl_cmd_single_dash_name;
/** Long name (i.e., "--foo"). */
const char *ocl_cmd_long_name;
/** Number of parameters that this option takes */
int ocl_num_params;
/** If this parameter is encountered, its *first* parameter it
saved here. If the parameter is encountered again, the
value is overwritten. */
void *ocl_variable_dest;
/** If an ocl_variable_dest is given, its datatype must be
supplied as well. */
opal_cmd_line_type_t ocl_variable_type;
/** Description of the command line option, to be used with
opal_cmd_line_get_usage_msg(). */
const char *ocl_description;
};
/**
* \internal
*
* Convenience typedef
*/
typedef struct opal_cmd_line_init_t opal_cmd_line_init_t;
2015-06-24 06:59:57 +03:00
/**
* Top-level command line handle.
*
* This handle is used for accessing all command line functionality
* (i.e., all opal_cmd_line*() functions). Multiple handles can be
* created and simultaneously processed; each handle is independant
* from others.
*
* The opal_cmd_line_t handles are [simplisticly] thread safe;
* processing is guaranteed to be mutually exclusive if multiple
* threads invoke functions on the same handle at the same time --
* access will be serialized in an unspecified order.
*
* Once finished, handles should be released with OBJ_RELEASE(). The
* destructor for opal_cmd_line_t handles will free all memory
* associated with the handle.
*/
OPAL_DECLSPEC OBJ_CLASS_DECLARATION(opal_cmd_line_t);
/**
* Make a command line handle from a table of initializers.
*
* @param cmd OPAL command line handle.
* @param table Table of opal_cmd_line_init_t instances for all
* the options to be included in the resulting command line
* handler.
*
* @retval OPAL_SUCCESS Upon success.
*
* This function takes a table of opal_cmd_line_init_t instances
* to pre-seed an OPAL command line handle. The last instance in
* the table must have '\0' for the short name and NULL for the
* single-dash and long names. The handle is expected to have
* been OBJ_NEW'ed or OBJ_CONSTRUCT'ed already.
*
* Upon return, the command line handle is just like any other. A
* sample using this syntax:
*
* \code
* opal_cmd_line_init_t cmd_line_init[] = {
2015-06-24 06:59:57 +03:00
* { NULL, NULL, NULL, 'h', NULL, "help", 0,
* &orterun_globals.help, OPAL_CMD_LINE_TYPE_BOOL,
* "This help message" },
*
* { NULL, NULL, NULL, '\0', NULL, "wd", 1,
* &orterun_globals.wd, OPAL_CMD_LINE_TYPE_STRING,
* "Set the working directory of the started processes" },
*
* { NULL, NULL, NULL, '\0', NULL, NULL, 0,
* NULL, OPAL_CMD_LINE_TYPE_NULL, NULL }
* };
* \endcode
*/
OPAL_DECLSPEC int opal_cmd_line_create(opal_cmd_line_t *cmd,
opal_cmd_line_init_t *table);
Refactor the ORTE DVM code so that external codes can submit multiple jobs using only a single connection to the HNP. * Clean up the DVM so it continues to run even when applications error out and we would ordinarily abort the daemons. * Create a new errmgr component for the DVM to handle the differences. * Cleanup the DVM state component. * Add ORTE bindings directory and brief README * Pass a local tool index around to match jobs. * Pass the jobid on job completion. * Fix initialization logic. * Add framework for python wrapper. * Fix terminate-with-non-zero-exit behavior so it properly terminates only the indicated procs, notifies orte-submit, and orte-dvm continues executing. * Add some missing options to orte-dvm * Fix a bug in -host processing that caused us to ignore the #slots designator. Add a new attribute to indicate "do not expand the DVM" when submitting job spawn requests. * It actually makes no sense that we treat the termination of all children differently than terminating the children of a specific job - it only creates confusion over the difference in behavior. So terminate children the same way regardless. Extend the cmd_line utility to easily allow layering of command line definitions Catch up with ORTE interface change and make build more generic. Disable "fixed dvm" logic for now. Add another cmd_line function to merge a table of cmd line options with another one, reporting as errors any duplicate entries. Use this to allow orterun to reuse the orted_submit code Fix the "fixed_dvm" logic by ensuring we reset num_new_daemons to zero. Also ensure that the nidmap is sent with the first job so the downstream daemons get the node info. Remove a duplicate cmd line entry in orterun. Revise the DVM startup procedure to pass the nidmap only once, at the startup of the DVM. This reduces the overhead on each job launch and ensures that the nidmap doesn't get overwritten. Add new commands to get_orted_comm_cmd_str(). Move ORTE command line options to orte_globals.[ch]. Catch up with extra orte_submit_init parameter. Add example code. Add documentation. Bump version. The nidmap and routing data must be updated prior to propagating the xcast or else the xcast will fail. Fix the return code so it is something more expected when an error occurs. Ensure we get an error returned to us when we fail to launch for some reason. In this case, we will always get a launch_cb as we did indeed attempt to spawn it. The error code will be returned in the complete_cb. Fix the return code from orte_submit_job - it was returning the tracker index instead of "success". Take advantage of ORTE's pretty-print capabilities to provide a nice error output explaining why we failed to launch. Ensure we always get a launch_cb when we fail to launch, but no complete_cb as the job never launched. Extend the error reporting capability to job completion as well. Add index parameter to orte_submit_job(). Add orte_job_cancel and implement ORTE_DAEMON_TERMINATE_JOB_CMD. Factor out dvm termination. Parse the terminate option at tool level. Add error string for ORTE_ERR_JOB_CANCELLED. Add some safeguards. Cleanup and/of comments. Enable the return. Properly ORTE_DECLSPEC orte_submit_halt. Add orte_submit_halt and orte_submit_cancel to interface. Use the plm interface to terminate the job
2015-12-17 02:30:40 +03:00
/* Add a table of opal_cmd_line_init_t instances
* to an existing OPAL command line handle.
*
* Multiple calls to opal_cmd_line_add are permitted - each
* subsequent call will simply append new options to the existing
* handle. Note that any duplicates will return an error.
*/
OPAL_DECLSPEC int opal_cmd_line_add(opal_cmd_line_t *cmd,
opal_cmd_line_init_t *table);
/**
* Create a command line option.
*
* @param cmd OPAL command line handle.
* @param entry Command line entry to add to the command line.
*
* @retval OPAL_SUCCESS Upon success.
*
*/
OPAL_DECLSPEC int opal_cmd_line_make_opt_mca(opal_cmd_line_t *cmd,
opal_cmd_line_init_t entry);
/**
* Create a command line option.
*
* @param cmd OPAL command line handle.
* @param short_name "Short" name of the command line option.
* @param sd_name "Single dash" name of the command line option.
* @param long_name "Long" name of the command line option.
* @param num_params How many parameters this option takes.
* @param dest Short string description of this option.
*
* @retval OPAL_ERR_OUT_OF_RESOURCE If out of memory.
* @retval OPAL_ERR_BAD_PARAM If bad parameters passed.
* @retval OPAL_SUCCESS Upon success.
*
* Adds a command line option to the list of options that an OPAL
* command line handle will accept. The short_name may take the
* special value '\0' to not have a short name. Likewise, the
* sd_name and long_name may take the special value NULL to not have
* a single dash or long name, respectively. However, one of the
* three must have a name.
*
* num_params indicates how many parameters this option takes. It
* must be greater than or equal to 0.
*
* Finally, desc is a short string description of this option. It is
* used to generate the output from opal_cmd_line_get_usage_msg().
*
*/
2015-06-24 06:59:57 +03:00
OPAL_DECLSPEC int opal_cmd_line_make_opt3(opal_cmd_line_t *cmd,
char short_name,
const char *sd_name,
2015-06-24 06:59:57 +03:00
const char *long_name,
int num_params,
const char *desc);
/**
* Parse a command line according to a pre-built OPAL command line
* handle.
*
* @param cmd OPAL command line handle.
* @param ignore_unknown Whether to print an error message upon
* finding an unknown token or not
* @param ignore_unknown_option Whether to print an error message upon
* finding an unknown option or not
* @param argc Length of the argv array.
* @param argv Array of strings from the command line.
*
* @retval OPAL_SUCCESS Upon success.
* @retval OPAL_ERR_SILENT If an error message was printed. This
* value will only be returned if the command line was not
* successfully parsed.
*
* Parse a series of command line tokens according to the option
* descriptions from a OPAL command line handle. The OPAL command line
* handle can then be queried to see what options were used, what
* their parameters were, etc.
*
* If an unknown token is found in the command line (i.e., a token
* that is not a parameter or a registered option), the parsing will
* stop (see below). If ignore_unknown is false, an error message
* is displayed. If ignore_unknown is true, the error message is
* not displayed.
*
* Error messages are always displayed regardless of the value
* of ignore_unknown (to stderr, and OPAL_ERR_SILENT is
* returned) if:
*
* 1. A token was encountered that required N parameters, but <N
* parameters were found (e.g., "cmd --param foo", but --param was
* registered to require 2 option tokens).
*
* 2. An unknown token beginning with "-" is encountered. For
* example, if "--fo" is specified, and no "fo" option is
* registered (e.g., perhaps the user meant to type "--foo"), an
* error message is always printed, UNLESS this unknown token
2015-06-24 06:59:57 +03:00
* happens after a "--" token (see below).
*
* The contents of argc and argv are not changed during parsing.
* argv[0] is assumed to be the executable name, and is ignored during
* parsing, except when printing error messages.
*
* Parsing will stop in the following conditions:
*
* - all argv tokens are processed
* - the token "--" is found
* - an unrecognized token is found
* - a parameter registered with an integer type option finds a
* non-integer option token
* - a parameted registered N option tokens, but finds less then
* <N tokens available
*
* Upon any of these conditions, any remaining tokens will be placed
* in the "tail" (and therefore not examined by the parser),
* regardless of the value of ignore_unknown. The set of tail
* tokens is available from the opal_cmd_line_get_tail() function.
*
* Note that "--" is ignored if it is found in the middle an expected
* number of arguments. For example, if "--foo" is expected to have 3
* arguments, and the command line is:
*
* executable --foo a b -- other arguments
*
* This will result in an error, because "--" will be parsed as the
* third parameter to the first instance of "foo", and "other" will be
* an unrecognized option.
*
* Note that -- can be used to allow unknown tokens that begin
* with "-". For example, if a user wants to mpirun an executable
* named "-my-mpi-program", the "usual" way:
*
* mpirun -my-mpi-program
*
* will cause an error, because mpirun won't find single-letter
* options registered for some/all of those letters. But two
* workarounds are possible:
*
* mpirun -- -my-mpi-program
* or
* mpirun ./-my-mpi-program
*
* Finally, note that invoking this function multiple times on
* different sets of argv tokens is safe, but will erase any
* previous parsing results.
*/
2015-06-24 06:59:57 +03:00
OPAL_DECLSPEC int opal_cmd_line_parse(opal_cmd_line_t *cmd,
bool ignore_unknown,
bool ignore_unknown_option,
int argc, char **argv);
/**
* Return a consolidated "usage" message for a OPAL command line handle.
*
* @param cmd OPAL command line handle.
*
* @retval str Usage message.
*
* Returns a formatted string suitable for printing that lists the
* expected usage message and a short description of each option on
* the OPAL command line handle. Options that passed a NULL
* description to opal_cmd_line_make_opt3() will not be included in the
* display (to allow for undocumented options).
*
* This function is typically only invoked internally by the
* opal_show_help() function.
*
* This function should probably be fixed up to produce prettier
* output.
*
* The returned string must be freed by the caller.
*/
OPAL_DECLSPEC char *opal_cmd_line_get_usage_msg(opal_cmd_line_t *cmd) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__;
/**
* Test if a given option was taken on the parsed command line.
*
* @param cmd OPAL command line handle.
* @param opt Short or long name of the option to check for.
*
* @retval true If the command line option was found during
* opal_cmd_line_parse().
*
* @retval false If the command line option was not found during
* opal_cmd_line_parse(), or opal_cmd_line_parse() was not invoked on
* this handle.
*
2015-06-24 06:59:57 +03:00
* This function should only be called after opal_cmd_line_parse().
*
* The function will return true if the option matching opt was found
* (either by its short or long name) during token parsing.
* Otherwise, it will return false.
*/
2015-06-24 06:59:57 +03:00
OPAL_DECLSPEC bool opal_cmd_line_is_taken(opal_cmd_line_t *cmd,
const char *opt) __opal_attribute_nonnull__(1) __opal_attribute_nonnull__(2);
/**
* Return the number of arguments parsed on a OPAL command line handle.
*
* @param cmd A pointer to the OPAL command line handle.
*
* @retval OPAL_ERROR If cmd is NULL.
* @retval argc Number of arguments previously added to the handle.
*
* Arguments are added to the handle via the opal_cmd_line_parse()
* function.
*/
OPAL_DECLSPEC int opal_cmd_line_get_argc(opal_cmd_line_t *cmd) __opal_attribute_unused__;
/**
* Return a string argument parsed on a OPAL command line handle.
*
* @param cmd A pointer to the OPAL command line handle.
* @param index The nth argument from the command line (0 is
* argv[0], etc.).
*
* @retval NULL If cmd is NULL or index is invalid
* @retval argument String of original argv[index]
*
* This function returns a single token from the arguments parsed
* on this handle. Arguments are added bia the
* opal_cmd_line_parse() function.
*
* What is returned is a pointer to the actual string that is on
* the handle; it should not be modified or freed.
*/
2015-06-24 06:59:57 +03:00
OPAL_DECLSPEC char *opal_cmd_line_get_argv(opal_cmd_line_t *cmd,
int index);
/**
* Return the number of instances of an option found during parsing.
*
* @param cmd OPAL command line handle.
* @param opt Short or long name of the option to check for.
*
* @retval num Number of instances (to include 0) of a given potion
* found during opal_cmd_line_parse().
*
* @retval OPAL_ERR If the command line option was not found during
* opal_cmd_line_parse(), or opal_cmd_line_parse() was not invoked on
* this handle.
*
* This function should only be called after opal_cmd_line_parse().
*
* The function will return the number of instances of a given option
* (either by its short or long name) -- to include 0 -- or OPAL_ERR if
* either the option was not specified as part of the OPAL command line
* handle, or opal_cmd_line_parse() was not invoked on this handle.
*/
2015-06-24 06:59:57 +03:00
OPAL_DECLSPEC int opal_cmd_line_get_ninsts(opal_cmd_line_t *cmd,
const char *opt) __opal_attribute_nonnull__(1) __opal_attribute_nonnull__(2);
/**
* Return a specific parameter for a specific instance of a option
* from the parsed command line.
*
* @param cmd OPAL command line handle.
* @param opt Short or long name of the option to check for.
* @param instance_num Instance number of the option to query.
* @param param_num Which parameter to return.
*
* @retval param String of the parameter.
* @retval NULL If any of the input values are invalid.
*
2015-06-24 06:59:57 +03:00
* This function should only be called after opal_cmd_line_parse().
*
* This function returns the Nth parameter for the Ith instance of a
* given option on the parsed command line (both N and I are
* zero-indexed). For example, on the command line:
*
* executable --foo bar1 bar2 --foo bar3 bar4
*
* The call to opal_cmd_line_get_param(cmd, "foo", 1, 1) would return
* "bar4". opal_cmd_line_get_param(cmd, "bar", 0, 0) would return
* NULL, as would opal_cmd_line_get_param(cmd, "foo", 2, 2);
*
* The returned string should \em not be modified or freed by the
* caller.
*/
2015-06-24 06:59:57 +03:00
OPAL_DECLSPEC char *opal_cmd_line_get_param(opal_cmd_line_t *cmd,
const char *opt,
int instance_num,
int param_num);
/**
* Return the entire "tail" of unprocessed argv from a OPAL
* command line handle.
*
* @param cmd A pointer to the OPAL command line handle.
* @param tailc Pointer to the output length of the null-terminated
* tail argv array.
* @param tailv Pointer to the output null-terminated argv of all
* unprocessed arguments from the command line.
*
* @retval OPAL_ERROR If cmd is NULL or otherwise invalid.
* @retval OPAL_SUCCESS Upon success.
*
* The "tail" is all the arguments on the command line that were
* not processed for some reason. Reasons for not processing
* arguments include:
*
* \sa The argument was not recognized
* \sa The argument "--" was seen, and therefore all arguments
* following it were not processed
*
* The output tailc parameter will be filled in with the integer
* length of the null-terminated tailv array (length including the
* final NULL entry). The output tailv parameter will be a copy
* of the tail parameters, and must be freed (likely with a call
* to opal_argv_free()) by the caller.
*/
2015-06-24 06:59:57 +03:00
OPAL_DECLSPEC int opal_cmd_line_get_tail(opal_cmd_line_t *cmd, int *tailc,
char ***tailv);
- Replace combinations of #if defined (c_plusplus) defined (__cplusplus) followed by extern "C" { and the closing counterpart by BEGIN_C_DECLS and END_C_DECLS. Notable exceptions are: - opal/include/opal_config_bottom.h: This is our generated code, that itself defines BEGIN_C_DECL and END_C_DECL - ompi/mpi/cxx/mpicxx.h: Here we do not include opal_config_bottom.h: - Belongs to external code: opal/mca/backtrace/darwin/MoreBacktrace/MoreDebugging/MoreBacktrace.c opal/mca/backtrace/darwin/MoreBacktrace/MoreDebugging/MoreBacktrace.h - opal/include/opal/prefetch.h: Has C++ specific macros that are protected: - Had #if ... } #endif _and_ END_C_DECLS (aka end up with 2x END_C_DECLS) ompi/mca/btl/openib/btl_openib.h - opal/event/event.h has #ifdef __cplusplus as BEGIN_C_DECLS... - opal/win32/ompi_process.h: had extern "C"\n {... opal/win32/ompi_process.h: dito - ompi/mca/btl/pcie/btl_pcie_lex.l: needed to add *_C_DECLS ompi/mpi/f90/test/align_c.c: dito - ompi/debuggers/msgq_interface.h: used #ifdef __cplusplus - ompi/mpi/f90/xml/common-C.xsl: Amend Tested on linux using --with-openib and --with-mx The following do not contain either opal_config.h, orte_config.h or ompi_config.h (but possibly other header files, that include one of the above): ompi/mca/bml/r2/bml_r2_ft.h ompi/mca/btl/gm/btl_gm_endpoint.h ompi/mca/btl/gm/btl_gm_proc.h ompi/mca/btl/mx/btl_mx_endpoint.h ompi/mca/btl/ofud/btl_ofud_endpoint.h ompi/mca/btl/ofud/btl_ofud_frag.h ompi/mca/btl/ofud/btl_ofud_proc.h ompi/mca/btl/openib/btl_openib_mca.h ompi/mca/btl/portals/btl_portals_endpoint.h ompi/mca/btl/portals/btl_portals_frag.h ompi/mca/btl/sctp/btl_sctp_endpoint.h ompi/mca/btl/sctp/btl_sctp_proc.h ompi/mca/btl/tcp/btl_tcp_endpoint.h ompi/mca/btl/tcp/btl_tcp_ft.h ompi/mca/btl/tcp/btl_tcp_proc.h ompi/mca/btl/template/btl_template_endpoint.h ompi/mca/btl/template/btl_template_proc.h ompi/mca/btl/udapl/btl_udapl_eager_rdma.h ompi/mca/btl/udapl/btl_udapl_endpoint.h ompi/mca/btl/udapl/btl_udapl_mca.h ompi/mca/btl/udapl/btl_udapl_proc.h ompi/mca/mtl/mx/mtl_mx_endpoint.h ompi/mca/mtl/mx/mtl_mx.h ompi/mca/mtl/psm/mtl_psm_endpoint.h ompi/mca/mtl/psm/mtl_psm.h ompi/mca/pml/cm/pml_cm_component.h ompi/mca/pml/csum/pml_csum_comm.h ompi/mca/pml/dr/pml_dr_comm.h ompi/mca/pml/dr/pml_dr_component.h ompi/mca/pml/dr/pml_dr_endpoint.h ompi/mca/pml/dr/pml_dr_recvfrag.h ompi/mca/pml/example/pml_example.h ompi/mca/pml/ob1/pml_ob1_comm.h ompi/mca/pml/ob1/pml_ob1_component.h ompi/mca/pml/ob1/pml_ob1_endpoint.h ompi/mca/pml/ob1/pml_ob1_rdmafrag.h ompi/mca/pml/ob1/pml_ob1_recvfrag.h ompi/mca/pml/v/pml_v_output.h opal/include/opal/prefetch.h opal/mca/timer/aix/timer_aix.h opal/util/qsort.h test/support/components.h This commit was SVN r21855. The following SVN revision numbers were found above: r2 --> open-mpi/ompi@58fdc188553052bc2e893ba28fb28fddbe78435a
2009-08-20 15:42:18 +04:00
END_C_DECLS
#endif /* OPAL_CMD_LINE_H */