SST user manual

Sometimes you might only be interested in building certain parts of SST, not all of it. For example, if you’re using SST in a C project, you might only be interested in building the C library. To provide control over this, both the ./configure script and the install/* scripts support the --with-build-groups option, whose syntax is as follows:

Each <group> in the comma-separated list specifies some part of the build system that should be enabled or disabled. The group will be enabled if the ‘```' prefix is given, or disabled if the '```-```' prefix is given. Omitting the prefix is the same as giving the '```’ prefix. All groups begin as disabled, and the entries of the list will be applied in order. If the --with-build-groups option is omitted, the behavior is as if it had been given as --with-build-groups=default, i.e., the default set of build groups will be enabled. Enabling or disabling certain build groups may implicitly enable or disable other build groups depending on how they are related.

The build groups are as follows:

When a global variable is made readonly, it cannot be shadowed by a local variable in a function.

This can generally be avoided by preferring to put code into functions and using local variables.

As an important special case of Section 2.5.1, do not make IFS readonly.

Bash <4.2 does not support declare -g in functions. Ignoring shadowing problems, global variable declarations can always be safely omitted except when a function needs to use a global associative array that may not have been declared yet. In this case, instead of writing declare -g -A foo in the function, write declare -A foo in the global scope just before the function.

For stylistic reasons, you may want to put commented-out # Bash >=4.2: declare -g declarations in a function for all global variables used by the function regardless of whether the declarations would technically be necessary. These declarations are helpful to the reader, and you can enable them later if you eventually migrate to Bash >=4.2.

Some versions of Bash sometimes have incorrect behavior for x=$* and x=$@, while x="$@" always works:

Note that x="$*" also always works, but x="$@" is still preferred when space separation is desired, as it is not affected by IFS.

The sst_nl function copies the content of standard input to standard output, appending a newline character to the end if not already present.

If no arguments are given, the sst_csf function copies the content of standard input to standard output, appending an “x” character and a newline character. Otherwise, the function removes the last character from each <&var> if it exists as an “x” character, and removes the next last character if it exists as a newline character.

The purpose of the sst_csf function is to allow command substitutions to be used that only remove a single trailing newline character instead of as many trailing newline characters as possible. To be more specific, instead of writing foo=$(bar), you can write foo=$(bar | sst_csf); sst_csf foo.

The “csf” abbreviation in the function name is short for “command substitution fix”.

When input is said to be read in sst_csf form, it means that the input is taken to be all characters up to but not including a possible single trailing newline character.

When output is said to be written in sst_csf form, it means that the output is followed by a single trailing newline character.

The sst_ihd function copies the content of standard input to standard output, removing <n> space characters from the beginning of each line. Lines that do not begin with <n> space characters are left unchanged.

If all lines are empty, all lines are left unchanged. Otherwise, if <n> is omitted, it is taken to be the length \(k\) of the longest possible sequence of space characters at the beginning of the first nonempty line, which may be zero. Otherwise, if <n> is negative, it is adjusted to \(\max\left(k + \mathtt{<n>}, 0\right)\).

If the input is empty, the output will be empty. Otherwise, a trailing newline character will be appended to the last line of output if not already present.

The “ihd” abbreviation in the function name is short for “indented here-document”.

The sst_ihs function is equivalent to the sst_ihd function except the first and last lines of input are ignored.

The “ihs” abbreviation in the function name is short for “indented here-string”.

The sst_join function writes the space-separated concatenation of the arguments to standard output in [bl_sst_csf] form. If no arguments are given, the concatenation is the empty string.

The sst_quote function converts the input into a portably quoted shell word.

The algorithm is as follows:

The input is the space-separated concatenation of the arguments. If no arguments are given, the input is read from standard input in CSF form instead. The output is always written to standard output in CSF form.

This function never requires the use of sst_csf, as the output never ends with a newline character (before it is written to standard output in CSF form). In other words, a plain command substitution always correctly collects the output.

The sst_quote_list function converts each <argument> to a portably quoted shell word and outputs the resulting list of words, separated by space characters. If no <argument>s are given, the output is empty.

Each conversion is performed using the same algorithm as the sst_quote function.

The output is written to standard output in CSF form.

This function never requires the use of sst_csf, as the output never ends with a newline character (before it is written to standard output in CSF form). In other words, a plain command substitution always correctly collects the output.

The sst_smart_quote function is equivalent to the sst_quote function except that if the result matches the regular expression ^'[+./0-9:=A-Z_a-z-]+'$, the quotes are removed.

This function never requires the use of sst_csf, as the output never ends with a newline character (before it is written to standard output in CSF form). In other words, a plain command substitution always correctly collects the output.

The sst_regex_escape function escapes the input for use in a Bash regular expression.

The input is the space-separated concatenation of the arguments. If no arguments are given, the input is read from standard input in CSF form instead. The output is always written to standard output in CSF form.

This function never requires the use of sst_csf, as the output never ends with a newline character (before it is written to standard output in CSF form). In other words, a plain command substitution always correctly collects the output.

The sst_regex_escape_list function outputs a Bash regular expression that matches any of the arguments. If no arguments are given, the regular expression will never match. The regular expression is always parenthesized.

The output is written to standard output in CSF form.

This function never requires the use of sst_csf, as the output never ends with a newline character (before it is written to standard output in CSF form). In other words, a plain command substitution always correctly collects the output.

The sst_barf function prints an error message and a stack trace to standard error and terminates the script.

The error message consists of the string "$0: Error: ", followed by the space-separated concatenation of the arguments, followed by a newline character.

If the SST_BARF_STATUS variable is set to an integer between 0 and 255 inclusive, the exit status will be $SST_BARF_STATUS. Otherwise, if sst_barf was called implicitly by a failed command, the exit status will be that of the failed command. Otherwise, the exit status will be 1.

The sst_warn function prints a warning message to standard error.

The warning message consists of the string "$0: warning: ", followed by the space-separated concatenation of the arguments, followed by a newline character.

The sst_info function prints an informative message to standard output.

The informative message consists of the string "$0: ", followed by the space-separated concatenation of the arguments, followed by a newline character.

The sst_expect_not_subshell function verifies that the current code is not running in a subshell^[1]. If the verification fails, sst_barf will be called with an appropriate error message.

The error message will state that <function> must not be called in a subshell. If <function> is omitted, it is inferred as the name of the calling function. If <function> is a single “-” character, the error message will instead generically state that the current code must not be run in a subshell.

The sst_push_var function saves the current value of <&var> onto a stack and sets <&var> to <value>. The most recent saved value of <&var> can be restored by calling sst_pop_var.

If <&var> is currently unset, its unset-ness will be saved onto the stack, and the corresponding call to sst_pop_var will unset <&var>.

If <value> is omitted, <&var> will be unset instead of being set to <value>.

The sst_set_exit function takes no action and returns with exit status <status>. If <status> is omitted, it is taken to be the exit status of the last command executed, in which case the call is effectively a noop.

The sst_expect_exit_status function verifies that each <argument> is an exit status.

A string is an exit status if all of the following are true:

The sst_array_cmp function compares two arrays. The arrays are compared in lexical order first on their keys, and then on their values. The result is -1, 0, or 1. The result is printed to standard output in [bl_sst_csf] form.

The sst_array_to_string function converts an array to a string. The output is written to standard output in [bl_sst_csf] form.

The sst_array_from_zterm function parses a sequence of zero-terminated elements into <array>.

If <command> [<arg>]…​ is given, it is run with standard input as its standard input and the elements are parsed from its standard output. Otherwise, the elements are parsed from standard input.

If the element sequence is empty, the resulting array will be empty. Otherwise, the zero terminator of the last element is optional if the last element is nonempty.

The sst_abs_dir function outputs an absolute path to <path> that includes a trailing / character. <path> is not validated against the file system and need not exist.

If <path> is empty, sst_barf will be called.

The output is guaranteed to begin and end with a / character.

If <path> is not given, the input is read from standard input in CSF form. The output is always written to standard output in CSF form.

This function never requires the use of sst_csf, as the output never ends with a newline character (before it is written to standard output in CSF form). In other words, a plain command substitution always correctly collects the output.

This function is unaffected by errexit suspension. Errors will always cause the current shell to exit with a nonzero exit status.

This function is equivalent to calling sst_add_slash followed by sst_abs_prefix followed by sst_squish_slashes, except it may have improved performance.

The sst_abs_file function outputs an absolute path to <path>. <path> is not validated against the file system and need not exist.

sst_barf will be called if any of the following is true:

The output is guaranteed to begin with a / character.

If <path> is not given, the input is read from standard input in CSF form. The output is always written to standard output in CSF form.

This function is unaffected by errexit suspension. Errors will always cause the current shell to exit with a nonzero exit status.

This function is equivalent to calling sst_abs_dir followed by sst_trim_slashes, except it may have improved performance and inputs that cannot possibly be file paths are rejected.

The sst_abs_prefix function constructs an absolute path to <path>, removes any characters after the last / character, and outputs the result. <path> is not validated against the file system and need not exist. If <path> ends with a / character, the behavior is as if it ended with /. instead.

If <path> is empty, sst_barf will be called.

The output is guaranteed to begin and end with a / character.

The output is guaranteed to be free of . and .. components if any of the following is true:

If <path> is not given, the input is read from standard input in CSF form. The output is always written to standard output in CSF form.

This function never requires the use of sst_csf, as the output never ends with a newline character (before it is written to standard output in CSF form). In other words, a plain command substitution always correctly collects the output.

This function is unaffected by errexit suspension. Errors will always cause the current shell to exit with a nonzero exit status.

The sst_add_slash function appends a / character to <path> if <path> ends with a non-/ character.

If <path> is empty, sst_barf will be called.

If <path> is not given, the input is read from standard input in CSF form. The output is always written to standard output in CSF form.

This function never requires the use of sst_csf, as the output never ends with a newline character (before it is written to standard output in CSF form). In other words, a plain command substitution always correctly collects the output.

This function is unaffected by errexit suspension. Errors will always cause the current shell to exit with a nonzero exit status.

The sst_add_slash_abs_prefix function is equivalent to calling sst_add_slash followed by sst_abs_prefix, except it may have improved performance.

If <path> is not given, the input is read from standard input in CSF form. The output is always written to standard output in CSF form.

This function never requires the use of sst_csf, as the output never ends with a newline character (before it is written to standard output in CSF form). In other words, a plain command substitution always correctly collects the output.

This function is unaffected by errexit suspension. Errors will always cause the current shell to exit with a nonzero exit status.

The sst_add_slash_dot_slash function is equivalent to calling sst_add_slash followed by sst_dot_slash, except it may have improved performance.

If <path> is not given, the input is read from standard input in CSF form. The output is always written to standard output in CSF form.

This function never requires the use of sst_csf, as the output never ends with a newline character (before it is written to standard output in CSF form). In other words, a plain command substitution always correctly collects the output.

This function is unaffected by errexit suspension. Errors will always cause the current shell to exit with a nonzero exit status.

The sst_dot_slash function prepends ./ to <path> if <path> does not begin with / or ./.

If <path> is empty, sst_barf will be called.

If <path> is not given, the input is read from standard input in CSF form. The output is always written to standard output in CSF form.

This function is primarily used to adjust an arbitrary path to be safe to use as a program argument. Without adjustment, an unusual path like --foo may be mistakenly interpreted as an option instead of an operand. For example, rm --foo will fail, but rm ./--foo will work.

This function is unaffected by errexit suspension. Errors will always cause the current shell to exit with a nonzero exit status.

The sst_expect_prefix function is equivalent to the sst_get_prefix function except it also verifies that the output is nonempty.

The sst_get_prefix function gets the longest initial substring of <path> that ends in a / character. If <path> does not contain a / character, the result is the empty string.

If <path> is not given, the input is read from standard input in CSF form. The output is always written to standard output in CSF form.

This function never requires the use of sst_csf, as the output never ends with a newline character (before it is written to standard output in CSF form). In other words, a plain command substitution always correctly collects the output.

The sst_safe_dir function outputs a path to <path> that includes a trailing / character. <path> is not validated against the file system and need not exist.

If <path> is empty, sst_barf will be called.

The output is guaranteed to begin with a / or . character and end with a / character.

If <path> is not given, the input is read from standard input in CSF form. The output is always written to standard output in CSF form.

This function never requires the use of sst_csf, as the output never ends with a newline character (before it is written to standard output in CSF form). In other words, a plain command substitution always correctly collects the output.

This function is unaffected by errexit suspension. Errors will always cause the current shell to exit with a nonzero exit status.

This function is equivalent to calling sst_add_slash followed by sst_dot_slash followed by sst_squish_slashes, except it may have improved performance.

The sst_safe_file function outputs an adjusted path to <path>. <path> is not validated against the file system and need not exist.

sst_barf will be called if any of the following is true:

The output is guaranteed to begin with a / or . character.

If <path> is not given, the input is read from standard input in CSF form. The output is always written to standard output in CSF form.

This function is unaffected by errexit suspension. Errors will always cause the current shell to exit with a nonzero exit status.

This function is equivalent to calling sst_safe_dir followed by sst_trim_slashes, except it may have improved performance and inputs that cannot possibly be file paths are rejected.

The sst_squish_slashes function replaces each maximal sequence of / characters in <path> with a single / character, subject to the following exceptions:

If <path> is not given, the input is read from standard input in CSF form. The output is always written to standard output in CSF form.

This function is unaffected by errexit suspension. Errors will always cause the current shell to exit with a nonzero exit status.

The sst_trim_slashes function removes all trailing / characters from <path>, subject to the following exceptions:

If <path> is not given, the input is read from standard input in CSF form. The output is always written to standard output in CSF form.

This function is unaffected by errexit suspension. Errors will always cause the current shell to exit with a nonzero exit status.

The sst_json_escape function escapes the input to be suitable to use in a JSON string.

The input is the space-separated concatenation of the arguments. If no arguments are given, the input is read from standard input in CSF form instead. The output is always written to standard output in CSF form.

The input must be encoded with UTF-8. If the input contains an invalid sequence of UTF-8 code units, sst_barf is called. The output is encoded with UTF-8 and always consists of code points between U+0020 and U+007E. Any code point outside this range is always represented as \b, \f, \n, \r, \t, \uXXXX, or a UTF-16 surrogate pair \uXXXX\uXXXX. It is unspecified which representation is used for any occurrence of any code point that can be represented more than one way, including even for code points between U+0020 and U+007E.

This function never requires the use of sst_csf, as the output never ends with a newline character (before it is written to standard output in CSF form). In other words, a plain command substitution always correctly collects the output.

The sst_json_quote function quotes the input as a JSON string.

The input is the space-separated concatenation of the arguments. If no arguments are given, the input is read from standard input in CSF form instead. The output is always written to standard output in CSF form.

The input must be encoded with UTF-8. If the input contains an invalid sequence of UTF-8 code units, sst_barf is called. The output is encoded with UTF-8 and always consists of code points between U+0020 and U+007E. Any code point outside this range is always represented as \b, \f, \n, \r, \t, \uXXXX, or a UTF-16 surrogate pair \uXXXX\uXXXX. It is unspecified which representation is used for any occurrence of any code point that can be represented more than one way, including even for code points between U+0020 and U+007E.

This function never requires the use of sst_csf, as the output never ends with a newline character (before it is written to standard output in CSF form). In other words, a plain command substitution always correctly collects the output.

The sst_jq_expect function checks a condition on JSON input using the jq utility and terminates the script if the condition is false.

The JSON input is read from standard input.

The <condition> argument specifies the condition to check. It should be a jq filter that outputs true or false.

If the condition is true, no action is taken. Otherwise, the script is terminated by calling [bl_sst_barf] [<format> [<arg>…​]].

The sst_jq_get_string function uses the jq utility to parse a JSON string into a variable.

<json> specifies the JSON value on which to run jq. If <json> is a single - character, the JSON value is read from standard input. Otherwise, if <json> begins with a /, A-Z, a-z, 0-9, ., _, or - character, it is taken to be a path to a file from which to read the JSON value. Otherwise, <json> is taken literally as the JSON value. If the input is actually a sequence of JSON values, all but the first JSON value is ignored.

<filter> specifies the jq filter to run on <json>. The filter should produce either a null value or a string value. A null value will be implicitly adjusted to an empty string value. If <filter> is omitted, it is taken to be .<&var>.

The resulting string value is assigned to <&var>.

The sst_jq_get_strings function parses an array of JSON strings into an indexed array.

<json> specifies the JSON value on which to run jq. If <json> is a single - character, the JSON value is read from standard input. Otherwise, if <json> begins with a /, A-Z, a-z, 0-9, ., _, or - character, it is taken to be a path to a file from which to read the JSON value. Otherwise, <json> is taken literally as the JSON value. If the input is actually a sequence of JSON values, all but the first JSON value is ignored.

<filter> specifies the jq filter to run on <json>. The filter should produce either a single null value, a single string value, or an array of null and string values. A single value is implicitly adjusted to an array containing that value, an empty array is implicitly adjusted to an array containing an empty string value, and each null value is implicitly adjusted to an empty string value.

The resulting JSON array is parsed into the variable named <var> as an indexed array.

The sst_parse_opt function attempts to parse an option from the beginning of a list of command-line arguments.

When sst_parse_opt returns, the following variables will have been updated in the calling context:

The build-dist-archive.bash script builds the distribution archive of an Autotools project.

The sst_ag_define_ordering_macros function generates every nonexistent macro \(y\) implied by the existence of a GATBPS_BEFORE([$0], [\(y\)]) call. Each \(y\) is called an ordering macro.

Consider the set of all pairs \((x, y)\) implied by the existence of any GATBPS_BEFORE([$0], [\(y\)]) call in any macro \(x\) defined in m4/\(x\).m4. For each unique \(y\) for which m4/\(y\).m4 does not exist, m4/\(y\).m4 will be generated, defining \(y\) to call GATBPS_REQUIRE([\(x\)]) for every corresponding \(x\).

The sst_am_distribute function adds each <path> to the distributed files list.

<path> must either exist as a file, exist as a directory, or not exist. A repeated <path> will be skipped, even across multiple calls.

This function must not be called from a subshell.

The sst_am_distribute_if_not_dir function adds each <path> to the distributed files list, but skips <path> if it exists as a directory.

<path> must either exist as a file, exist as a directory, or not exist. A repeated <path> will be skipped, even across multiple calls.

This function must not be called from a subshell.

The sst_am_if function starts an if block for the AM_CONDITIONAL variable <var>. If the ! character is given, the condition will be negated. The block must be ended by a matching call to sst_am_elif, sst_am_else, or sst_am_endif.

The sst_am_endif function ends the if block started by the matching call to sst_am_if, sst_am_elif, or sst_am_else. If <expected_comment> is given, it will be verified to match the condition of the block being ended.

The sst_libdir variable provides an absolute path to the directory that contains the SST Bash library. The path is guaranteed to begin with a / character and end with a non-/ character.

The sst_is0atty variable indicates whether standard input is connected to a terminal.

sst_is0atty=<boolean> means that sst_is0atty is set to either 1 or null to indicate true or false, respectively. Because arithmetic evaluation implicitly converts null variables to 0, this means that sst_is0atty can be compared to true with either [[ "$sst_is0atty" ]] or ((sst_is0atty)), and compared to false with either [[ ! "$sst_is0atty" ]] or ((!sst_is0atty)).

The sst_underscore_slug function replaces every non-alphanumeric character of the input with an underscore character.

The input is the space-separated concatenation of the arguments. If no arguments are given, the input is read from standard input in CSF form instead. The output is always written to standard output in CSF form.

The sst_extract_archive function extracts the archive <file> into the current directory. The supported file extensions are .tar, .tar.gz, .tar.xz, and .zip.

The sst_get_distro function identifies the system type and stores it in the sst_distro variable.

The following results are possible: alpine, arch, centos, cygwin, debian, fedora, homebrew, macports, msys2, rhel, ubuntu, or unknown.

The first time this function is called, it determines the result and stores it in the sst_distro variable, and subsequent calls simply output the cached result.

All possible results, including those added in the future, are guaranteed to be spelled such that $sst_distro is unaffected by word splitting and pathname expansion.

The sst_get_distro_version function identifies the system version and stores it in the sst_distro_version variable.

The following results are possible for the various sst_get_distro values:

The first time this function is called, it determines the result and stores it in the sst_distro_version variable, and subsequent calls simply output the cached result.

All possible results, including those added in the future, are guaranteed to be spelled such that $sst_distro_version is unaffected by word splitting and pathname expansion.

The prepare-dist-repo.bash script makes a commit to a private [bs_distribution_repository] for preview purposes before the [bl_publish_dist_repo_bash] script is used to publish the preview commit to a corresponding public distribution repository.

<json> specifies the JSON value on which to run jq. If <json> is a single - character, the JSON value is read from standard input. Otherwise, if <json> begins with a /, A-Z, a-z, 0-9, ., _, or - character, it is taken to be a path to a file from which to read the JSON value. Otherwise, <json> is taken literally as the JSON value. If the input is actually a sequence of JSON values, all but the first JSON value is ignored.

The following arguments may be specified in <json>:

The publish-dist-repo.bash script publishes a preview commit made by the [bl_prepare_dist_repo_bash] script to a corresponding public [bs_distribution_repository].

This function never requires the use of sst_csf, as the output never ends with a newline character (before it is written to standard output in CSF form). In other words, a plain command substitution always correctly collects the output.

The sst_type function calls type "$@" and adjusts an exit status of 1 to 0.

The sst_grep function calls grep "$@" and adjusts an exit status of 1 to 0.

The sst_expect_utf8 function validates that the input is valid UTF-8 and outputs the input unchanged.

The input is the space-separated concatenation of the arguments. If no arguments are given, the input is read from standard input in CSF form instead. The output is always written to standard output in CSF form.

The sst_get_variables function outputs all existing variable names that match any of the Bash regular expressions <regex>.

If more than one variable name matches, the names are separated by newline characters and the order of the names is unspecified. If no variable names match, the output is empty.

The output is written to standard output in CSF form.

The sst_get_environment_variables function outputs all existing environment variable names that match any of the Bash regular expressions <regex>.

If more than one environment variable name matches, the names are separated by newline characters and the order of the names is unspecified. If no environment variable names match, the output is empty.

The output is written to standard output in CSF form.

The sst_human_list function adjusts and outputs a list of items in human-readable form.

The output is designed to appear after a : character in normal prose.

The output is written to standard output in CSF form.

The sst_kill_all_jobs function runs kill [<arg>...] %j for every currently existing background job j.

If all of the kill commands succeed, the function will return with exit status 0. Otherwise, the function will return with the exit status of the first failed kill command. The rest of the kill commands will still be run, but their exit statuses will be ignored.

Other errors are possible but extremely rare, and will cause the function to immediately return with the offending exit status. This differs from the usual fail-fast convention of the library, as the main purpose of this function is for best-effort cleanup. Because subshells do not inherit background jobs, the usual error handling technique of using a subshell does not work, i.e., (sst_kill_all_jobs &>/dev/null) || : will never find any background jobs to kill.

Note that the kill builtin may exit with exit status 0 in certain cases you may not expect it to. For example, on Bash 5.0, (sleep 2 & kill foo %1 || echo bar) will kill the sleep command and print an error message about foo being unrecognized, but it will not print bar.

The sst_copyright_notice function formats a copyright notice for use in source code.

The prose of the copyright notice is specified by <prose> as follows:

The comment structure of the copyright notice is specified by <comment1>, <comment2>, and <comment3> as follows:

The sst_is_errexit_suspended function outputs 1 if errexit is suspended, 0 if errexit is not suspended, or nothing if an error occurs.

The output is written to standard output in CSF form. However, if an error occurs, the output may be completely empty instead of a single newline character.

The sst_expect_any_file function verifies that at least one <path> exists as a file.

The sst_expect_extension function verifies that the final component of <path> ends with <extension>, but is not solely <extension>.

Technically speaking, this function verifies that <extension> is a trailing substring of <path> that is preceded by at least one non-slash character.

The sst_expect_file function verifies that each <path> exists as a file.

The sst_expect_maybe_file function verifies that each <path> either exists as a file or does not exist.

The sst_expect_not_exist function verifies that each <path> does not exist. If any verification fails, sst_barf will be called with an appropriate error message.

The sst_mkdir_p_new function iterates through the <path> parameters, taking the following actions for each <path>:

If no <path> parameters are given, no action is taken.

The sst_mkdir_p_only function iterates through the <path> parameters, taking the following actions for each <path>:

If no <path> parameters are given, no action is taken.

This function behaves correctly under errexit suspension.

The sst_popd function is equivalent to the popd builtin except it does not write anything to standard output.

This function is unaffected by errexit suspension. Errors will always cause the current shell to exit with a nonzero exit status.

The sst_pushd function is equivalent to the pushd builtin except it does not write anything to standard output.

This function is unaffected by errexit suspension. Errors will always cause the current shell to exit with a nonzero exit status.

The sst_stmpdir variable provides an absolute path to a directory that can be used to store sensitive temporary files. The path is guaranteed to begin with a “/” character and end with a non-“/” character. When the script exits, all files below the directory will be overwritten with zeros and the directory will be deleted.

The sst_tmpdir variable provides an absolute path to a directory that can be used to store non-sensitive temporary files. The path is guaranteed to begin with a “/” character and end with a non-“/” character. When the script exits, the directory will be deleted.

The public header files of the SST C/C++ library are those that live below the src/c-cpp/include/sst directory in the SST Git repository, but excluding those that live below the src/c-cpp/include/sst/private directory.

All public SST header files use the .h file extension except for those that are intended to be used in C++ only, which use the .hpp file extension instead.

Sometimes you might find two copies of the same public SST header file alongside each other: one with the .h file extension, and one with the .hpp file extension. In this case, including the .hpp header file in C++ is equivalent to including the .h header file, but the .hpp header file is deprecated and will eventually be removed.

If a header file is intended to be used in C++ only, it should include the following code after its include guard:

If a header file is intended to be used in C only, it should include the following code after its include guard:

An algorithm with an iterator parameter p is called unique-pass with respect to p if the algorithm satisfies all of the following properties:

Depending on the language version being used, the SST_NORETURN macro expands to either nothing or an attribute that specifies that a function never returns.

Note that SST requires C++11, which supports the standard [[noreturn]] attribute, so SST_NORETURN is not necessary when using C++. However, for consistency, it is provided anyway.

If SST_DEBUG is nonzero, the SST_ASSERT (C) (1) macro expands to a parenthesized expression (x) of type void that evaluates the expression CONDITION exactly once. The following actions are then taken:

Any message written to standard error will also include the values of __FILE__ and __LINE__ from the location of the SST_ASSERT (C) (1) call.

If SST_DEBUG is zero, the SST_ASSERT (C) (1) macro expands to a parenthesized expression (x) of type void that takes no action. It does not evaluate CONDITION, except if the result of CONDITION is a variable length array.

If SST_DEBUG is nonzero, the SST_ASSERT (C) (2) macro expands to a parenthesized expression (x) of type void that evaluates the expression CONDITION exactly once. The following actions are then taken:

Any message written to standard error will also include the values of __FILE__ and __LINE__ from the location of the SST_ASSERT (C) (2) call.

If SST_DEBUG is zero, the SST_ASSERT (C) (2) macro expands to a parenthesized expression (x) of type void that takes no action. It does not evaluate CONDITION, except if the result of CONDITION is a variable length array, and it does not evaluate MESSAGE.

If SST_DEBUG is nonzero, the SST_ASSERT (C++) (1) macro expands to a parenthesized expression (x) of type void that evaluates the expression CONDITION exactly once. The following actions are then taken:

Any message written to standard error will also include the values of __FILE__ and __LINE__ from the location of the SST_ASSERT (C++) (1) call.

If SST_DEBUG is zero, the SST_ASSERT (C++) (1) macro expands to a parenthesized expression (x) of type void that takes no action. It does not evaluate CONDITION.

If SST_DEBUG is nonzero, the SST_ASSERT (C++) (2) macro expands to a parenthesized expression (x) of type void that evaluates the expression CONDITION exactly once. The following actions are then taken:

Any message written to standard error will also include the values of __FILE__ and __LINE__ from the location of the SST_ASSERT (C++) (2) call.

If SST_DEBUG is zero, the SST_ASSERT (C++) (2) macro expands to a parenthesized expression (x) of type void that takes no action. It does not evaluate CONDITION, and it does not evaluate MESSAGE.

The SST_DEBUG macro expands to a parenthesized integer constant expression (x) with type int. The expression is also suitable for use in the preprocessor.

The sst::overlap function attempts to determine whether two memory regions overlap.

Each memory region consists of the n\(i\) elements of type T\(i\) beginning at p\(i\). n\(i\) must be nonnegative and p\(i\) must be a valid pointer, even if n\(i\) is zero. If n\(i\) is omitted, it is taken to be 1. T\(i\) must be an object type or void. If T\(i\) is void, the behavior is as if it were unsigned char.

If this function returns true, the two memory regions overlap.

If this function returns false, the two memory regions may or may not overlap. False negatives are generally possible because some systems allow multiple memory regions to refer to the same underlying data. For example, a system may allow the same file to be mapped into two different memory regions at the same time, with any changes being reflected in both regions simultaneously. If no such functionality is being used, false negatives are not possible.

If n1 or n2 is zero, this function always returns false.

The sst::pointer_eq function returns true if p1 is equal to p2 with respect to the implementation-defined strict total order over pointers.

Each of T1 and T2 must be either void or an object type.

The sst::pointer_ge function returns true if p1 is greater than or equal to p2 with respect to the implementation-defined strict total order over pointers.

Each of T1 and T2 must be either void or an object type.

The sst::pointer_gt function returns true if p1 is greater than p2 with respect to the implementation-defined strict total order over pointers.

Each of T1 and T2 must be either void or an object type.

The sst::pointer_le function returns true if p1 is less than or equal to p2 with respect to the implementation-defined strict total order over pointers.

Each of T1 and T2 must be either void or an object type.

The sst::pointer_lt function returns true if p1 is less than p2 with respect to the implementation-defined strict total order over pointers.

Each of T1 and T2 must be either void or an object type.

The sst::pointer_ne function returns true if p1 is not equal to p2 with respect to the implementation-defined strict total order over pointers.

Each of T1 and T2 must be either void or an object type.

The SST_CPP14_CONSTEXPR macro expands to the constexpr keyword if C++14 or later is being used, or to nothing if not.

The SST_CPP17_CONSTEXPR macro expands to the constexpr keyword if C++17 or later is being used, or to nothing if not.

The SST_CPP20_CONSTEXPR macro expands to the constexpr keyword if C++20 or later is being used, or to nothing if not.

The SST_CPP17_INLINE macro expands to the inline keyword if C++17 or later is being used, or to nothing if not.

The SST_CONSTEXPR_ASSERT macro can be used to run dynamic assertions in constexpr functions.

The sst::bool_constant alias provides a convenient way to write std::integral_constant<bool, B>.

The sst::bool_constant alias was added to the library because the std::bool_constant alias is not available below C++17.

The sst::common_type_t alias provides a convenient way to write std::common_type<T...>::type that never requires the typename keyword to be used to disambiguate a dependent type.

The sst::common_type_t alias was added to the library because the std::common_type_t alias is not available below C++14.

The sst::conditional_t alias provides a convenient way to write std::conditional<B, T, F>::type that never requires the typename keyword to be used to disambiguate a dependent type.

The sst::conditional_t alias was added to the library because the std::conditional_t alias is not available below C++14.

The sst::copy_cv trait defines R to be Dst overwritten with the cv-qualifiers of Src. In other words, the following steps take place:

The sst::copy_cv_t alias provides a convenient way to write sst::copy_cv<Src, Dst>::type that never requires the typename keyword to be used to disambiguate a dependent type.

The sst::decay_t alias provides a convenient way to write std::decay<T>::type that never requires the typename keyword to be used to disambiguate a dependent type.

The sst::decay_t alias was added to the library because the std::decay_t alias is not available below C++14.

The sst::is_big_endian trait determines whether the byte ordering of T is big endian.

Any cv-qualifiers on T are ignored.

The sst::is_big_endian trait may produce false negatives.

The sst::is_bool type trait determines whether T is the type bool, ignoring any references and cv-qualifiers.

The sst::is_byte trait determines whether T is one of the following types, ignoring any reference and cv-qualifiers:

The sst::is_enum type trait determines whether T is an enumeration type, ignoring any references and cv-qualifiers.

The sst::is_exact_width_integer trait determines whether T is one of the exact-width integer types, i.e., one of int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, or uint64_t, ignoring any cv-qualifiers.

Let i be an object of type sst::decay_t<I>. The sst::is_input_iterator trait defines b to true if all of the following are true:

The sst::is_integer trait defines B to true if T is a fundamental integer type^[3], ignoring any cvref-qualifiers.

Let i be an object of type sst::decay_t<I>. The sst::is_iterator trait defines b to true if all of the following are true:

The sst::is_little_endian trait determines whether the byte ordering of T is little endian.

Any cv-qualifiers on T are ignored.

The sst::is_little_endian trait may produce false negatives.

The sst::is_non_bool_integer class defines value to be true if T is a possibly cv-qualified integer type other than bool, or false if not.

The sst::is_ones_complement class determines whether T is an integer type that uses ones’ complement representation.

In C++20 and later, signed integer types are required to use two’s complement representation^[4]. Before C++20, signed integer types are permitted to use ones’ complement or sign-magnitude representation instead, in which case negative zero may be a trap representation^[5].

Unsigned integer types are never considered to use ones’ complement representation.

Let i be an object of type sst::decay_t<I>. The sst::is_output_iterator trait defines b to true if all of the following are true:

The sst::is_sign_magnitude class determines whether T is an integer type that uses sign-magnitude representation.

In C++20 and later, signed integer types are required to use two’s complement representation^[4]. Before C++20, signed integer types are permitted to use ones’ complement or sign-magnitude representation instead, in which case negative zero may be a trap representation^[5].

Unsigned integer types are never considered to use sign-magnitude representation.

The sst::is_signed_integer trait determines whether T is a signed fundamental integer type^[3].

The sst::is_twos_complement class determines whether T is an integer type that uses two’s complement representation.

In C++20 and later, signed integer types are required to use two’s complement representation^[4]. Before C++20, signed integer types are permitted to use ones’ complement or sign-magnitude representation instead, in which case negative zero may be a trap representation^[5].

Unsigned integer types are always considered to use two’s complement representation.

The sst::is_unsigned_integer class defines value to be true if T is a possibly cv-qualified unsigned integer type, or false if not.

For more information, see std::is_unsigned and std::is_integral.

The sst::remove_cv_t alias provides a convenient way to write std::remove_cv<T>::type that never requires the typename keyword to be used to disambiguate a dependent type.

The sst::remove_cv_t alias was added to the library because the std::remove_cv_t alias is not available below C++14.

The sst::remove_cvref trait defines R to be T with any reference and cv-qualifiers removed. In other words, the following steps take place:

The sst::remove_cvref trait was added to the library because the std::remove_cvref trait is not available below C++20.

The sst::remove_cvref_t alias provides a convenient way to write std::remove_cvref<T>::type that never requires the typename keyword to be used to disambiguate a dependent type.

The sst::remove_reference_t alias provides a convenient way to write std::remove_reference<T>::type that never requires the typename keyword to be used to disambiguate a dependent type.

The sst::remove_reference_t alias was added to the library because the std::remove_reference_t alias is not available below C++14.

The sst::type_identity trait defines type to be T itself.

The sst::type_identity trait was added to the library because the std::type_identity trait is not available below C++20.

The sst::type_identity_t alias provides a convenient way to write sst::type_identity<T>::type that never requires the typename keyword to be used to disambiguate a dependent type.

The sst::undeduced trait defines R to T itself, making it functionally equivalent to the sst::type_identity trait. The difference is only of style: both of these traits can be used to prevent template argument deduction from occurring, in which case using sst::undeduced is a better indication of intent than using sst::type_identity.

The sst::undeduced_t alias provides a convenient way to write sst::undeduced<T>::type that never requires the typename keyword to be used to disambiguate a dependent type.

The sst::count_it function returns an iterator that compares equal to the iterator that would be produced by std::advance(x, n).

The type R of the returned iterator is unspecified. However, the following guarantees are made:

The sst::track_it function returns an iterator that wraps another iterator with functionality for tracking and limiting the iterator’s motion.

The sst::wrap_it function returns an iterator that wraps another iterator with functionality for tracking and limiting the iterator’s motion.

The sst::json::get_to function parses an nlohmann::json value into dst based on the type of dst and returns dst.

If ValueType is a std::vector-like type, then the internal type of src must be array_t. dst will first be cleared, and then each element of the array will be appended to dst after being parsed by calling sst::json::get_to recursively.

If ValueType is a std::map-like type, then the internal type of src must be object_t. dst will first be cleared, and then each member of the object will be inserted into dst after being parsed by calling sst::json::get_to recursively.

If ValueType is any other type, then the parsing will be forwarded to nlohmann::json’s built-in parsing logic by calling src.get_to(dst). In particular, this means that nlohmann::json’s arbitrary type parsing feature (i.e., user-provided from_json functions) will work when calling sst::json::get_to.

Except perhaps when parsing is forwarded to nlohmann::json’s built-in parsing logic, this function will reliably throw an exception if any kind of error occurs. In particular, it will throw an exception if ValueType is an integer type that cannot represent a parsed integer value.

The following functions are provided for parsing JSON object members:

The internal type of src must be object_t. For (1), src must contain a member named key, whose value will be parsed by calling sst::json::get_to recursively. For (2), the behavior is the same as (1) except that if src does not contain a member named key, then dst will be set to default_value.

Calling the sst::json::remove_to function is the same as calling the sst::json::get_to function with the same parameters, except key will also be removed from src, if present.

Calling the sst::json::remove_as function is the same as calling the sst::json::get_as function with the same parameters, except key will also be removed from src, if present.

The sst::json::unknown_key function (overload 1) checks for an unknown key in a JSON object.

If src is a JSON value other than an object, the function throws an sst::json::exception. Otherwise, if src does not contain any keys, the function takes no action. Otherwise, the function throws an sst::json::exception with a message that includes at least one of the keys.

This function is intended to be combined with the convention of deleting keys from a JSON object as they are parsed. After all known keys are parsed, any remaining keys are unknown, and calling this function will reject them.

The sst::get_bit function returns the bit at index \(\mathtt{q} \cdot \mathtt{CHAR\_BIT} + \mathtt{r}\) of the two’s complement representation of x (for (1) and (2)) or the region of bytes pointed to by x (for (3) and (4)). For (1) and (2), the bits of x are zero indexed starting with the least significant bit (and the most significant bit is the sign bit if X is signed). For (3) and (4), the bits of the region of bytes pointed to by x are zero indexed starting with the least significant bit of the first byte.

X, Q, and R may be any integer types. If x is a null pointer, q is negative, r is negative, or \(\mathtt{q} \cdot \mathtt{CHAR\_BIT} + \mathtt{r}\) is greater than or equal to the number of nonpadding bits in X or the number of bits in the region of bytes pointed to by x, the behavior is undefined. For (2) and (4), q is omitted and taken to be zero.

Prior to C++20, signed integers are permitted to use ones’ complement or sign-magnitude representation instead of two’s complement. This does not affect the behavior of (1) or (2).

The sst::set_bit function sets the bit at index \(\mathtt{q} \cdot \mathtt{CHAR\_BIT} + \mathtt{r}\) of the two’s complement representation of x (for (1) and (2)) or the region of bytes pointed to by x (for (3) and (4)) to b. For (1) and (2), the bits of x are zero indexed starting with the least significant bit (and the most significant bit is the sign bit if X is signed), and the function returns the resulting value. For (3) and (4), the bits of the region of bytes pointed to by x are zero indexed starting with the least significant bit of the first byte, and the function returns x.

X, Q, and R may be any integer types. If x is a null pointer, q is negative, r is negative, or \(\mathtt{q} \cdot \mathtt{CHAR\_BIT} + \mathtt{r}\) is greater than or equal to the number of nonpadding bits in X or the number of bits in the region of bytes pointed to by x, the behavior is undefined. For (2) and (4), q is omitted and taken to be zero.

Prior to C++20, signed integers are permitted to use ones’ complement or sign-magnitude representation instead of two’s complement. This does not affect the behavior of (1) or (2), except that if the resulting value cannot be represented by X (i.e., if X is signed, x is zero, and the most significant bit is being set to 1), the behavior is undefined.

The sst::from_bits function loads an integer from a sequence of bits of memory. First, the n bits of memory starting at bit index \(\mathtt{q} \cdot \mathtt{CHAR\_BIT} + \mathtt{r}\) of the region of bytes pointed to by x are interpreted as a two’s complement integer if SignExtend is true, or as an unsigned integer if SignExtend is false. The first bit is taken to be the least significant bit of the integer, and the last bit is taken to be the most significant bit of the integer (which is the sign bit if SignExtend is true). The bits of the region of bytes pointed to by x are zero indexed starting with the least significant bit of the first byte. Next, the least significant \(w\) bits of the infinite two’s complement representation of this integer are considered, where \(w\) is the number of nonpadding bits in Y. If Y is signed, these bits are interpreted as a two’s complement integer (with the most significant bit being the sign bit) and the resulting value is returned. If Y is unsigned, these bits are interpreted as an unsigned integer and the resulting value is returned.

Y, Q, R, and N may be any integer types. If x is a null pointer, q is negative, r is negative, n is not positive, or \(\mathtt{q} \cdot \mathtt{CHAR\_BIT} + \mathtt{r} + \mathtt{n}\) is greater than the number of bits in the region of bytes pointed to by x, the behavior is undefined. For (2), q is omitted and taken to be zero.

Prior to C++20, signed integers are permitted to use ones’ complement or sign-magnitude representation instead of two’s complement. This does not affect the behavior of this function, except that if the resulting value cannot be represented by Y (i.e., if Y is signed and the resulting value is \(-2^{1-w}\)), the behavior is undefined.

The sst::to_bits function stores an integer to a sequence of bits of memory. First, the two’s complement representation of y is considered, extending it with infinitely many copies of its most significant bit (which is the sign bit if Y is signed) if SignExtend is true, or with infinitely many 0’s if SignExtend is false. Next, the least significant n bits of this infinite representation are stored to the n bits of memory starting at bit index \(\mathtt{q} \cdot \mathtt{CHAR\_BIT} + \mathtt{r}\) of the region of bytes pointed to by x. The bits of the region of bytes pointed to by x are zero indexed starting with the least significant bit of the first byte. Finally, the function returns x.

Y, Q, R, and N may be any integer types. If x is a null pointer, q is negative, r is negative, n is not positive, or \(\mathtt{q} \cdot \mathtt{CHAR\_BIT} + \mathtt{r} + \mathtt{n}\) is greater than the number of bits in the region of bytes pointed to by x, the behavior is undefined. For (2), q is omitted and taken to be zero.

Prior to C++20, signed integers are permitted to use ones’ complement or sign-magnitude representation instead of two’s complement. This does not affect the behavior of this function.

The sst::min function returns a < b ? a : b.

This function was added to the library because std::min is not constexpr before C++14.

The sst::max function returns a < b ? b : a.

This function was added to the library because std::max is not constexpr before C++14.

The sst::floor_sqrt function returns \(\lfloor\sqrt{\mathtt{x}}\rfloor\). If x is negative, the behavior is undefined.

The sst::ceil_sqrt function returns \(\lceil\sqrt{\mathtt{x}}\rceil\). If x is negative, the behavior is undefined.

The sst::floor_lg function returns \(\lfloor\lg{\mathtt{x}}\rfloor\). If x is negative or zero, the behavior is undefined.

The sst::ceil_lg function returns \(\lceil\lg{\mathtt{x}}\rceil\). If x is negative or zero, the behavior is undefined.