<!--#include virtual="header.txt"-->

<h1><a name="top">Slurm APIs</a></h1>

<h3 id="overview">Overview<a class="slurm_link" href="#overview"></a></h3>
<p>All of the Slurm commands utilize a collection of Application Programming
Interfaces (APIs).
User and system applications can directly use these APIs as desired to
achieve tighter integration with Slurm.
For example, Slurm data structures and error codes can be directly
examined rather than executing Slurm commands and parsing their output.
This document describes Slurm APIs.
You should see the man pages for individual APIs to get more details.</p>

<h3 id="overall">Get Overall Slurm Information
<a class="slurm_link" href="#overall"></a>
</h3>
<ul>

<li><b>slurm_api_version</b> &mdash; Get Slurm API version number.</li>

<li><b>slurm_load_ctl_conf</b> &mdash; Load system-wide configuration
specifications. Free with <i>slurm_free_ctl_conf</i> to avoid memory
leak.</li>

<li><b>slurm_print_ctl_conf</b> &mdash; Print system-wide configuration
specifications.</li>

<li><b>slurm_free_ctl_conf</b> &mdash; Free storage allocated by
<i>slurm_load_ctl_conf</i>.</li>

</ul>


<h3 id="job">Get Job Information<a class="slurm_link" href="#job"></a></h3>
<ul>

<li><b>slurm_pid2jobid</b> &mdash; For a given process ID on a node
get the corresponding Slurm job ID.</li>

<li><b>slurm_get_end_time</b> &mdash; For a given Slurm job ID
get the expected termination time.</li>

<li><b>slurm_load_jobs</b> &mdash; Load job information.
Free with <i>slurm_free_job_info_msg</i> to avoid memory leak.</li>

<li><b>slurm_print_job_info_msg</b> &mdash; Print information about
all jobs.</li>

<li><b>slurm_print_job_info</b> &mdash; Print information about
a specific job.</li>

<li><b>slurm_free_job_info_msg</b> &mdash; Free storage allocated by
<i>slurm_load_jobs</i>.</li>

</ul>


<h3 id="step">Get Job Step Information
<a class="slurm_link" href="#step"></a>
</h3>
<ul>

<li><b>slurm_get_job_steps</b> &mdash; Load job step information.
Free with <i>slurm_free_job_step_info_response_msg</i> to
avoid memory leak.</li>

<li><b>slurm_print_job_step_info_msg</b> &mdash; Print information about
all job steps.</li>

<li><b>slurm_print_job_step_info</b> &mdash; Print information about
a specific job step.</li>

<li><b>slurm_free_job_step_info_response_msg</b> &mdash; Free storage
allocated by <i>slurm_get_job_steps</i>.</li>

</ul>


<h3 id="node">Get Node Information<a class="slurm_link" href="#node"></a></h3>
<ul>

<li><b>slurm_load_node</b> &mdash; Load node information.
Free with <i>slurm_free_node_info</i> to avoid memory leak.</li>

<li><b>slurm_print_node_info_msg</b> &mdash; Print information about
all nodes.</li>

<li><b>slurm_print_node_table</b> &mdash; Print information about
a specific node.</li>

<li><b>slurm_free_node_info</b> &mdash; Free storage
allocated by <i>slurm_load_node</i>.</li>

</ul>


<h3 id="partition">Get Partition Information
<a class="slurm_link" href="#partition"></a>
</h3>
<ul>

<li><b>slurm_load_partitions</b> &mdash; Load partition (queue) information.
Free with <i>slurm_free_partition_info</i> to avoid memory leak.</li>

<li><b>slurm_print_partition_info_msg</b> &mdash; Print information about
all partitions.</li>

<li><b>slurm_print_partition_info</b> &mdash; Print information about
a specific partition.</li>

<li><b>slurm_free_partition_info</b> &mdash; Free storage
allocated by <i>slurm_load_partitions</i>.</li>

</ul>


<h3 id="error">Error Handling<a class="slurm_link" href="#error"></a></h3>
<ul>

<li><b>slurm_get_errno</b> &mdash; Return the error code set by the
last Slurm API function executed.</li>

<li><b>slurm_perror</b> &mdash; Prin. Slurm error information to
standard output.</li>

<li><b>slurm_strerror</b> &mdash; Return a string describing a specific
Slurm error code.</li>

</ul>


<h3 id="resource_alloc">Resource Allocation
<a class="slurm_link" href="#resource_alloc"></a>
</h3>
<ul>

<li><b>slurm_init_job_desc_msg</b> &mdash; Initialize the data structure
used in resource allocation requests. You can then just set the fields
of particular interest and let the others use default values.</li>

<li><b>slurm_job_will_run</b> &mdash; Determine if a job would be
immediately initiated if submitted now.</li>

<li><b>slurm_allocate_resources</b> &mdash; Allocate resources for a job.
Response message must be freed using
<i>slurm_free_resource_allocation_response_msg</i> to avoid a
memory leak.</li>

<li><b>slurm_free_resource_allocation_response_msg</b> &mdash;
Frees memory allocated by <i>slurm_allocate_resources</i>.</li>

<li><b>slurm_allocate_resources_and_run</b> &mdash; Allocate resources for a
job and spawn a job step. Response message must be freed using
<i>slurm_free_resource_allocation_and_run_response_msg</i> to avoid a
memory leak.</li>

<li><b>slurm_free_resource_allocation_and_run_response_msg</b> &mdash;
Frees memory allocated by <i>slurm_allocate_resources_and_run</i>.</li>

<li><b>slurm_submit_batch_job</b> &mdash; Submit a script for later
execution. Response message must be freed using
<i>slurm_free_submit_response_response_msg</i> to avoid a
memory leak.</li>

<li><b>slurm_free_submit_response_response_msg</b> &mdash;
Frees memory allocated by <i>slurm_submit_batch_job</i>.</li>

<li><b>slurm_confirm_allocation</b> &mdash; Test if a resource allocation has
already been made for a given job id. Response message must be freed using
<i>slurm_free_resource_allocation_response_msg</i> to avoid a
memory leak. This can be used to confirm that an
allocation is still active or for error recovery.</li>

</ul>


<h3 id="step_creation">Job Step Creation
<a class="slurm_link" href="#step_creation"></a>
</h3>
<p>Slurm job steps involve numerous interactions with the
<i>slurmd</i> daemon. The job step creation is only the
first step in the process. We don't advise direct user
creation of job steps, but include the information here
for completeness.</p>
<ul>

<li><b>slurm_job_step_create</b> &mdash; Initiate a job step.
Allocated memory must be freed by
<i>slurm_free_job_step_create_response_msg</i> to avoid a
memory leak.</li>

<li><b>slurm_free_job_step_create_response_msg</b> &mdash; Free
memory allocated by <i>slurm_job_step_create</i>.

<li><b>slurm_step_ctx_create</b> &mdash; Create job step context.
Destroy using <i>slurm_step_ctx_destroy</i>.</li>

<li><b>slurm_step_ctx_destroy</b> &mdash; Destroy a job step context
created by <i>slurm_step_ctx_create</i>.</li>

<li><b>slurm_step_ctx_get</b> &mdash; Get values from job step context.</li>

<li><b>slurm_step_ctx_set</b> &mdash; Set values in job step context.</li>

<li><b>slurm_jobinfo_ctx_get</b> &mdash; Get values from a <i>jobinfo</i>
field as returned by <i>slurm_step_ctx_get</i>.</li>

<li><b>slurm_spawn</b> &mdash; Spawn tasks and establish communications.</li>

<li><b>slurm_spawn_kill</b> &mdash; Signal spawned tasks.</li>

</ul>


<h3 id="signal">Job and Job Step Signaling and Cancelling
<a class="slurm_link" href="#signal"></a>
</h3>
<ul>

<li><b>slurm_kill_job</b> &mdash; Signal or cancel a job.</li>

<li><b>slurm_kill_job_step</b> &mdash; Signal or cancel a job step.</li>

</ul>


<h3 id="completion">Job Completion
<a class="slurm_link" href="#completion"></a>
</h3>
<ul>

<li><b>slurm_complete_job</b> &mdash; Note completion of a job.
Releases resource allocation for the job.</li>

<li><b>slurm_complete_job_step</b> &mdash; Note completion of a
job step.</li>

</ul>


<h3 id="admin">Administrative Functions
<a class="slurm_link" href="#admin"></a>
</h3>
<p>Most of these functions can only be executed by user <i>root</i>.</p>
<ul>

<li><b>slurm_reconfigure</b> &mdash; Update slurm daemons
based upon current <i>slurm.conf</i> configuration file.
Use this after updating the configuration file to
ensure that it takes effect.</li>

<li><b>slurm_shutdown</b> &mdash; Terminate slurm daemons.</li>

<li><b>slurm_update_job</b> &mdash; Update state
information associated with a given job.</li>

<li><b>slurm_update_node</b> &mdash; Update state
information associated with a given node. NOTE: Most
of a node's characteristics can not be modified.</li>

<li><b>slurm_init_part_desc_msg</b> &mdash; Initialize a
partition update descriptor. Used this to initialize
the data structure used in <i>slurm_update_partition</i>.</li>

<li><b>slurm_update_partition</b> &mdash; Update state
information associated with a given partition.</li>

<li><b>slurm_delete_partition</b> &mdash; Destroy a partition.</li>

</ul>


<h3 id="host_list">Slurm Host List Support
<a class="slurm_link" href="#host_list"></a>
</h3>
<p>Slurm uses a condensed format to express node names.
For example <i>linux[1-3,6]</i> represents <i>linux1</i>,
<i>linux2</i>, <i>linux3</i>, and <i>linux6</i>. These
functions permit you to translate the Slurm expression
into a list of individual node names.</p>

<ul>

<li><b>slurm_hostlist_create</b> &mdash; Translate a Slurm
node name expression into a record used for parsing.
Use <i>slurm_hostlist_destroy</i> to free the allocated
storage.</li>

<li><b>slurm_hostlist_shift</b> &mdash; Get the next node
name.</li>

<li><b>slurm_hostlist_destroy</b> &mdash; Release storage
allocated by <i>slurm_hostlist_create</i>.

</ul>

<p style="text-align:center;">Last modified 23 November 2019</p>

<!--#include virtual="footer.txt"-->