.TH "Slurm API" "3" "Slurm job information reporting functions" "November 2020" "Slurm job information reporting functions"

.SH "NAME"
slurm_get_end_time, slurm_get_rem_time,
slurm_job_cpus_allocated_on_node, slurm_job_cpus_allocated_on_node_id,
slurm_job_cpus_allocated_str_on_node, slurm_job_cpus_allocated_str_on_node_id,
slurm_load_jobs, slurm_load_job_user, slurm_pid2jobid,
slurm_print_job_info, slurm_print_job_info_msg
\- Slurm job information reporting functions
.LP
ISLURM_GET_REM_TIME, ISLURM_GET_REM_TIME2
\- Fortran callable extensions

.SH "SYNTAX"
.LP
#include <stdio.h>
.br
#include <time.h>
.br
#include <slurm/slurm.h>
.br
#include <sys/types.h>
.LP
void \fBslurm_free_job_info_msg\fR (
.br
	job_info_msg_t *\fIjob_info_msg_ptr\fP
.br
);
.LP
int \fBslurm_load_job\fR (
.br
	job_info_msg_t **\fIjob_info_msg_pptr\fP,
.br
	uint32_t \fIjob_id\fP,
.br
	uint16_t \fIshow_flags\fP,
.br
);
.LP
int \fBslurm_load_job_user\fR (
.br
	job_info_msg_t **\fIjob_info_msg_pptr\fP,
.br
	uint32_t \fIuser_id\fP,
.br
	uint16_t \fIshow_flags\fP,
.br
);
.LP
int \fBslurm_load_jobs\fR (
.br
	time_t \fIupdate_time\fP,
.br
	job_info_msg_t **\fIjob_info_msg_pptr\fP,
.br
	uint16_t \fIshow_flags\fP
.br
);
.LP
int \fBslurm_notify_job\fR (
.br
	uint32_t \fIjob_id\fP,
.br
	char *\fImessage\fP
.br
);
.LP
int \fBslurm_pid2jobid\fR (
.br
	pid_t \fIjob_pid\fP,
.br
	uint32_t *\fIjob_id_ptr\fP
.br
);
.LP
int \fBslurm_get_end_time\fR (
.br
	uint32_t \fIjobid\fP,
.br
	time_t *\fIend_time_ptr\fP
.br
);
.LP
long \fBslurm_get_rem_time\fR (
.br
	uint32_t \fIjob_id\fP
.br
);
.LP
void \fBslurm_print_job_info\fR (
.br
	FILE *\fIout_file\fP,
.br
	job_info_t *\fIjob_ptr\fP,
.br
	int \fIone_liner\fP
.br
);
.LP
void \fBslurm_print_job_info_msg\fR (
.br
	FILE *\fIout_file\fP,
.br
	job_info_msg_t *\fIjob_info_msg_ptr\fP,
.br
	int \fIone_liner\fP
.br
);
.LP
int \fBslurm_job_cpus_allocated_on_node_id\fR (
.br
	job_resources_t *\fIjob_resrcs_ptr\fP,
.br
	int \fInode_id\fP
.br
);
.LP
int \fBslurm_job_cpus_allocated_on_node\fR (
.br
	job_resources_t *\fIjob_resrcs_ptr\fP,
.br
	const char *\fInode_name\fP
.br
);
.LP
int \fBslurm_job_cpus_allocated_str_on_node_id\fR (
.br
	char *\fIcpus\fP,
.br
	size_t \fIcpus_len\fP,
.br
	job_resources_t *\fIjob_resrcs_ptr\fP,
.br
	int \fInode_id\fP
.br
);
.LP
int \fBslurm_job_cpus_allocated_str_on_node\fR (
.br
	char *\fIcpus\fP,
.br
	size_t \fIcpus_len\fP,
.br
	job_resources_t *\fIjob_resrcs_ptr\fP,
.br
	const char *\fInode_name\fP
.br
);

.SH "FORTRAN EXTENSION"
.LP
INTEGER*4 JOBID, REM_TIME
.br
REM_TIME = ISLURM_GET_REM_TIME(JOBID)
.br
REM_TIME = ISLURM_GET_REM_TIME2()
.LP
ISLURM_GET_REM_TIME2() is equivalent to ISLURM_GET_REM_TIME() except
that the JOBID is taken from the SLURM_JOB_ID environment variable,
which is set by Slurm for tasks which it launches.
Both functions return the number of seconds remaining before the job
reaches the end of its allocated time.

.SH "ARGUMENTS"
.TP
\fIcpus\fP
Specifies a pointer to allocated memory into which the string representing the
list of allocated CPUs on the node is placed.
.TP
\fIcpus_len\fP
The size in bytes of the allocated memory space pointed by \fIcpus\fP.
.TP
\fIdata_type\fP
Identifies the type of data to retrieve \fIjobinfo\fP. Note that different types of
data are associated with different computer types and different configurations.
.TP
\fIdata\fP
The data value identified with \fIdata_type\fP is returned in the location specified
by \fIdata\fP. See the slurm.h header file for identification of the data types
associated with each value of \fIdata_type\fP.
.TP
\fIend_time_ptr\fP
Specified a pointer to a storage location into which the expected termination
time of a job is placed.
.TP
\fIjob_info_msg_pptr\fP
Specifies the double pointer to the structure to be created and filled with
the time of the last job update, a record count, and detailed information
about each job. Detailed job information is written to fixed sized records
and includes: ID number, name, user ID, state, assigned or requested node
names, indexes into the node table, etc. In the case of indexes into the
node table, this is an array of integers with pairs of start and end index
number into the node information records and the data is terminated with a
value of \-1. See slurm.h for full details on the data structure's contents.
.TP
\fIjob_id\fP
Specifies a slurm job id. If zero, use the SLURM_JOB_ID environment variable
to get the jobid.
.TP
\fIjob_id_ptr\fP
Specifies a pointer to a storage location into which a Slurm job id may be
placed.
.TP
\fIjob_info_msg_ptr\fP
Specifies the pointer to the structure created by \fBslurm_load_job\fR
or \fBslurm_load_jobs\fR.
.TP
\fIjobinfo\fP
Job\-specific information as constructed by Slurm's NodeSelect plugin.
This data object is returned for each job by the \fBslurm_load_job\fR or
\fBslurm_load_jobs\fR function.
.TP
\fIjob_pid\fP
Specifies a process id of some process on the current node.
.TP
\fIjob_ptr\fP
Specifies a pointer to a single job records from the \fIjob_info_msg_ptr\fP
data structure.
.TP
\fIjob_resrcs_ptr\fP
Pointer to a job_resources_t structure previously using the function
\fBslurm_load_job\fR with a \fIshow_flags\fP value of \fBSHOW_DETAIL\fP.
.TP
\fInode_id\fP
Zero origin ID of a node allocated to a job.
.TP
\fInode_name\fP
Name of a node allocated to a job.
.TP
\fIone_liner\fP
Print one record per line if non\-zero.
.TP
\fIout_file\fP
Specifies the file to print data to.
.TP
\fIshow_flags\fP
Job filtering flags, may be ORed.
Information about jobs in partitions that are configured as
hidden and partitions that the user's group is unable to utilize
are not reported by default.
.RS
.TP 13
\fBSHOW_ALL\fP
Report information about jobs in all partitions, even partitions to which the
user lacks access (this access can be blocked by system administers).
.TP
\fBSHOW_DETAIL\fP
Report detailed resource allocation information (e.g. identification of the
specific CPUs allocated to a job on each node).
.TP
\fBSHOW_LOCAL\fP
Report information only about jobs on the local cluster, even if the cluster
is part of a federation.
.TP
\fBSHOW_SIBLING\fP
Report information about all sibling jobs on a federated cluster.
.RE

.TP
\fIupdate_time\fP
For all of the following informational calls, if update_time is equal to or
greater than the last time changes where made to that information, new
information is not returned.  Otherwise all the configuration. job, node,
or partition records are returned.
.TP
\fIuser_id\fP
ID of user we want information for.

.SH "DESCRIPTION"
.LP
\fBslurm_free_resource_allocation_response_msg\fR Free slurm resource
allocation response message.
.LP
\fBslurm_free_job_info_msg\fR Release the storage generated by the
\fBslurm_load_jobs\fR function.
.LP
\fBslurm_get_end_time\fR Returns the expected termination time of a specified
Slurm job. The time corresponds to the exhaustion of the job's or partition's
time limit. NOTE: The data is cached locally and only retrieved from the
Slurm controller once per minute.
.LP
\fBslurm_get_rem_time\fR Returns the number of seconds remaining before the
expected termination time of a specified Slurm job id. The time corresponds
to the exhaustion of the job's or partition's time limit. NOTE: The data is
cached locally and only retrieved from the Slurm controller once per minute.
.LP
\fBslurm_job_cpus_allocated_on_node\fR and
\fBslurm_job_cpus_allocated_on_node_id\fR
return the number of CPUs allocated to a job on a specific node allocated to a job.
.LP
\fBslurm_job_cpus_allocated_str_on_node\fR and
\fBslurm_job_cpus_allocated_str_on_node_id\fR return a string representing the
list of CPUs allocated to a job on a specific node allocated to a job.
.LP
\fBslurm_load_job\fR Returns a job_info_msg_t that contains an update time,
record count, and array of job_table records for some specific job ID.
.LP
\fBslurm_load_jobs\fR Returns a job_info_msg_t that contains an update time,
record count, and array of job_table records for all jobs.
.LP
\fBslurm_load_job_yser\fR Returns a job_info_msg_t that contains an update
time, record count, and array of job_table records for all jobs associated
with a specific user ID.
.LP
\fBslurm_load_job_user\fR issues RPC to get slurm information about all jobs to
be run as the specified user.
.LP
\fBslurm_notify_job\fR Sends the specified message to standard output of
the specified job ID.
.LP
\fBslurm_pid2jobid\fR Returns a Slurm job id corresponding to the supplied
local process id. This only works for processes which Slurm spawns and their
descendants.
.LP
\fBslurm_print_job_info\fR Prints the contents of the data structure
describing a single job records from the data loaded by the
\fBslurm_load_node\fR function.
.LP
\fBslurm_print_job_info_msg\fR Prints the contents of the data structure
describing all job records loaded by the \fBslurm_load_node\fR function.

.SH "RETURN VALUE"
.LP
For \fBslurm_get_rem_time\fR on success a number of seconds is returned.
For all other functions zero is returned on success.
On error, \-1 is returned, and Slurm error code is set appropriately.

.SH "ERRORS"
.LP
\fBSLURM_NO_CHANGE_IN_DATA\fR Data has not changed since \fBupdate_time\fR.
.LP
\fBSLURM_PROTOCOL_VERSION_ERROR\fR Protocol version has changed, re\-link
your code.
.LP
\fBESLURM_INVALID_JOB_ID\fR Request for information about a non\-existent job.
.LP
\fBSLURM_PROTOCOL_SOCKET_IMPL_TIMEOUT\fR Timeout in communicating with
Slurm controller.
.LP
\fBINVAL\fR Invalid function argument.

.SH "EXAMPLE"
.LP
#include <stdio.h>
.br
#include <stdlib.h>
.br
#include <slurm/slurm.h>
.br
#include <slurm/slurm_errno.h>
.br
#include <sys/types.h>
.LP
int main (int argc, char *argv[])
.br
{
.br
	int i;
.br
	job_info_msg_t	* job_buffer_ptr = NULL;
.br
	job_info_t * job_ptr;
.br
	uint32_t job_id;
.LP
	/* get and dump some job information */
.br
	if ( slurm_load_jobs ((time_t) NULL,
.br
	                      &job_buffer_ptr, SHOW_ALL) ) {
.br
		slurm_perror ("slurm_load_jobs error");
.br
		exit (1);
.br
	}
.LP
	/* The easy way to print... */
.br
	slurm_print_job_info_msg (stdout, job_buffer_ptr, 0);
.LP
	/* A harder way.. */
.br
	for (i = 0; i < job_buffer_ptr\->record_count; i++) {
.br
		job_ptr = &job_buffer_ptr\->job_array[i];
.br
		slurm_print_job_info(stdout, job_ptr, 1);
.br
	}
.LP
	/* The hardest way. */
.br
	printf ("Jobs updated at %lx, record count %d\\n",
.br
	        job_buffer_ptr\->last_update,
.br
	        job_buffer_ptr\->record_count);
.br
	for (i = 0; i < job_buffer_ptr\->record_count; i++) {
.br
		printf ("JobId=%u UserId=%u\\n",
.br
			job_buffer_ptr\->job_array[i].job_id,
.br
			job_buffer_ptr\->job_array[i].user_id);
.br
	}
.LP
	slurm_free_job_info_msg (job_buffer_ptr);
.LP
	if (slurm_pid2jobid (getpid(), &job_id))
.br
		slurm_perror ("slurm_load_jobs error");
.br
	else
.br
		printf ("Slurm job id = %u\\n", job_id);
.LP
	exit (0);
.br
}

.SH "NOTES"
These functions are included in the libslurm library,
which must be linked to your process for use
(e.g. "cc \-lslurm myprog.c").
.LP
The \fIcommand\fR field in the job record will be the name of user program to
be launched by the srun or sbatch command. The field is not set when either the
salloc command is used or the sbatch command is used with the \-\-wrap option.
.LP
Some data structures contain index values to cross\-reference each other.
If the \fIshow_flags\fP argument is not set to SHOW_ALL when getting this
data, these index values will be invalid.
.LP
The \fBslurm_hostlist_\fR functions can be used to convert Slurm node list
expressions into a collection of individual node names.

.SH "COPYING"
Copyright (C) 2002\-2006 The Regents of the University of California.
Copyright (C) 2008\-2010 Lawrence Livermore National Security.
Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER).
CODE\-OCEC\-09\-009. All rights reserved.
.LP
This file is part of Slurm, a resource management program.
For details, see <https://slurm.schedmd.com/>.
.LP
Slurm is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option)
any later version.
.LP
Slurm is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
details.

.SH "SEE ALSO"
.LP
\fBscontrol\fR(1), \fBsqueue\fR(1),
\fBslurm_hostlist_create\fR(3), \fBslurm_hostlist_shift\fR(3),
\fBslurm_hostlist_destroy\fR(3),
\fBslurm_allocation_lookup\fR(3),
\fBslurm_get_errno\fR(3), \fBslurm_perror\fR(3), \fBslurm_strerror\fR(3)