1Slurm API(3) Slurm job information reporting functions Slurm API(3)
2
6 slurm_get_end_time, slurm_get_rem_time, slurm_job_cpus_allo‐
7 cated_on_node, slurm_job_cpus_allocated_on_node_id,
8 slurm_job_cpus_allocated_str_on_node, slurm_job_cpus_allo‐
9 cated_str_on_node_id, slurm_load_jobs, slurm_load_job_user,
10 slurm_pid2jobid, slurm_print_job_info, slurm_print_job_info_msg - Slurm
11 job information reporting functions
12 ISLURM_GET_REM_TIME, ISLURM_GET_REM_TIME2 - Fortran callable extensions
14
17 #include <stdio.h>
18 #include <time.h>
19 #include <slurm/slurm.h>
20 #include <sys/types.h>
21 void slurm_free_job_info_msg (
23 job_info_msg_t *job_info_msg_ptr
24 );
25 int slurm_load_job (
27 job_info_msg_t **job_info_msg_pptr,
28 uint32_t job_id,
29 uint16_t show_flags,
30 );
31 int slurm_load_job_user (
33 job_info_msg_t **job_info_msg_pptr,
34 uint32_t user_id,
35 uint16_t show_flags,
36 );
37 int slurm_load_jobs (
39 time_t update_time,
40 job_info_msg_t **job_info_msg_pptr,
41 uint16_t show_flags
42 );
43 int slurm_notify_job (
45 uint32_t job_id,
46 char *message
47 );
48 int slurm_pid2jobid (
50 pid_t job_pid,
51 uint32_t *job_id_ptr
52 );
53 int slurm_get_end_time (
55 uint32_t jobid,
56 time_t *end_time_ptr
57 );
58 long slurm_get_rem_time (
60 uint32_t job_id
61 );
62 void slurm_print_job_info (
64 FILE *out_file,
65 job_info_t *job_ptr,
66 int one_liner
67 );
68 void slurm_print_job_info_msg (
70 FILE *out_file,
71 job_info_msg_t *job_info_msg_ptr,
72 int one_liner
73 );
74 int slurm_job_cpus_allocated_on_node_id (
76 job_resources_t *job_resrcs_ptr,
77 int node_id
78 );
79 int slurm_job_cpus_allocated_on_node (
81 job_resources_t *job_resrcs_ptr,
82 const char *node_name
83 );
84 int slurm_job_cpus_allocated_str_on_node_id (
86 char *cpus,
87 size_t cpus_len,
88 job_resources_t *job_resrcs_ptr,
89 int node_id
90 );
91 int slurm_job_cpus_allocated_str_on_node (
93 char *cpus,
94 size_t cpus_len,
95 job_resources_t *job_resrcs_ptr,
96 const char *node_name
97 );
98
101 INTEGER*4 JOBID, REM_TIME
102 REM_TIME = ISLURM_GET_REM_TIME(JOBID)
103 REM_TIME = ISLURM_GET_REM_TIME2()
104 ISLURM_GET_REM_TIME2() is equivalent to ISLURM_GET_REM_TIME() except
106 that the JOBID is taken from the SLURM_JOB_ID environment variable,
107 which is set by Slurm for tasks which it launches. Both functions
108 return the number of seconds remaining before the job reaches the end
109 of its allocated time.
110
113 cpus Specifies a pointer to allocated memory into which the string
114 representing the list of allocated CPUs on the node is placed.
115 cpus_len
117 The size in bytes of the allocated memory space pointed by cpus.
118 data_type
120 Identifies the type of data to retrieve jobinfo. Note that dif‐
121 ferent types of data are associated with different computer
122 types and different configurations.
123 data The data value identified with data_type is returned in the
125 location specified by data. See the slurm.h header file for
126 identification of the data types associated with each value of
127 data_type.
128 end_time_ptr
130 Specified a pointer to a storage location into which the
131 expected termination time of a job is placed.
132 job_info_msg_pptr
134 Specifies the double pointer to the structure to be created and
135 filled with the time of the last job update, a record count, and
136 detailed information about each job. Detailed job information is
137 written to fixed sized records and includes: ID number, name,
138 user ID, state, assigned or requested node names, indexes into
139 the node table, etc. In the case of indexes into the node table,
140 this is an array of integers with pairs of start and end index
141 number into the node information records and the data is termi‐
142 nated with a value of -1. See slurm.h for full details on the
143 data structure's contents.
144 job_id Specifies a slurm job id. If zero, use the SLURM_JOB_ID environ‐
146 ment variable to get the jobid.
147 job_id_ptr
149 Specifies a pointer to a storage location into which a Slurm job
150 id may be placed.
151 job_info_msg_ptr
153 Specifies the pointer to the structure created by slurm_load_job
154 or slurm_load_jobs.
155 jobinfo
157 Job-specific information as constructed by Slurm's NodeSelect
158 plugin. This data object is returned for each job by the
159 slurm_load_job or slurm_load_jobs function.
160 job_pid
162 Specifies a process id of some process on the current node.
163 job_ptr
165 Specifies a pointer to a single job records from the
166 job_info_msg_ptr data structure.
167 job_resrcs_ptr
169 Pointer to a job_resources_t structure previously using the
170 function slurm_load_job with a show_flags value of SHOW_DETAIL.
171 node_id
173 Zero origin ID of a node allocated to a job.
174 node_name
176 Name of a node allocated to a job.
177 one_liner
179 Print one record per line if non-zero.
180 out_file
182 Specifies the file to print data to.
183 show_flags
185 Job filtering flags, may be ORed. Information about jobs in
186 partitions that are configured as hidden and partitions that the
187 user's group is unable to utilize are not reported by default.
188 SHOW_ALL Report information about jobs in all partitions,
190 even partitions to which the user lacks access
191 (this access can be blocked by system administers).
192 SHOW_DETAIL Report detailed resource allocation information
194 (e.g. identification of the specific CPUs allocated
195 to a job on each node).
196 SHOW_LOCAL Report information only about jobs on the local
198 cluster, even if the cluster is part of a federa‐
199 tion.
200 SHOW_SIBLING Report information about all sibling jobs on a fed‐
202 erated cluster.
203 update_time
206 For all of the following informational calls, if update_time is
207 equal to or greater than the last time changes where made to
208 that information, new information is not returned. Otherwise
209 all the configuration. job, node, or partition records are
210 returned.
211 user_id
213 ID of user we want information for.
214
217 slurm_free_resource_allocation_response_msg Free slurm resource alloca‐
218 tion response message.
219 slurm_free_job_info_msg Release the storage generated by the
221 slurm_load_jobs function.
222 slurm_get_end_time Returns the expected termination time of a specified
224 Slurm job. The time corresponds to the exhaustion of the job's or par‐
225 tition's time limit. NOTE: The data is cached locally and only
226 retrieved from the Slurm controller once per minute.
227 slurm_get_rem_time Returns the number of seconds remaining before the
229 expected termination time of a specified Slurm job id. The time corre‐
230 sponds to the exhaustion of the job's or partition's time limit. NOTE:
231 The data is cached locally and only retrieved from the Slurm controller
232 once per minute.
233 slurm_job_cpus_allocated_on_node and slurm_job_cpus_allo‐
235 cated_on_node_id return the number of CPUs allocated to a job on a spe‐
236 cific node allocated to a job.
237 slurm_job_cpus_allocated_str_on_node and slurm_job_cpus_allo‐
239 cated_str_on_node_id return a string representing the list of CPUs
240 allocated to a job on a specific node allocated to a job.
241 slurm_load_job Returns a job_info_msg_t that contains an update time,
243 record count, and array of job_table records for some specific job ID.
244 slurm_load_jobs Returns a job_info_msg_t that contains an update time,
246 record count, and array of job_table records for all jobs.
247 slurm_load_job_yser Returns a job_info_msg_t that contains an update
249 time, record count, and array of job_table records for all jobs associ‐
250 ated with a specific user ID.
251 slurm_load_job_user issues RPC to get slurm information about all jobs
253 to be run as the specified user.
254 slurm_notify_job Sends the specified message to standard output of the
256 specified job ID.
257 slurm_pid2jobid Returns a Slurm job id corresponding to the supplied
259 local process id. This only works for processes which Slurm spawns and
260 their descendants.
261 slurm_print_job_info Prints the contents of the data structure describ‐
263 ing a single job records from the data loaded by the slurm_load_node
264 function.
265 slurm_print_job_info_msg Prints the contents of the data structure
267 describing all job records loaded by the slurm_load_node function.
268
271 For slurm_get_rem_time on success a number of seconds is returned. For
272 all other functions zero is returned on success. On error, -1 is
273 returned, and Slurm error code is set appropriately.
274
277 SLURM_NO_CHANGE_IN_DATA Data has not changed since update_time.
278 SLURM_PROTOCOL_VERSION_ERROR Protocol version has changed, re-link your
280 code.
281 ESLURM_INVALID_JOB_ID Request for information about a non-existent job.
283 SLURM_PROTOCOL_SOCKET_IMPL_TIMEOUT Timeout in communicating with Slurm
285 controller.
286 INVAL Invalid function argument.
288
291 #include <stdio.h>
292 #include <stdlib.h>
293 #include <slurm/slurm.h>
294 #include <slurm/slurm_errno.h>
295 #include <sys/types.h>
296 int main (int argc, char *argv[])
298 {
299 int i;
300 job_info_msg_t * job_buffer_ptr = NULL;
301 job_info_t * job_ptr;
302 uint32_t job_id;
303 /* get and dump some job information */
305 if ( slurm_load_jobs ((time_t) NULL,
306 &job_buffer_ptr, SHOW_ALL) ) {
307 slurm_perror ("slurm_load_jobs error");
308 exit (1);
309 }
310 /* The easy way to print... */
312 slurm_print_job_info_msg (stdout, job_buffer_ptr, 0);
313 /* A harder way.. */
315 for (i = 0; i < job_buffer_ptr->record_count; i++) {
316 job_ptr = &job_buffer_ptr->job_array[i];
317 slurm_print_job_info(stdout, job_ptr, 1);
318 }
319 /* The hardest way. */
321 printf ("Jobs updated at %lx, record count %d\n",
322 job_buffer_ptr->last_update,
323 job_buffer_ptr->record_count);
324 for (i = 0; i < job_buffer_ptr->record_count; i++) {
325 printf ("JobId=%u UserId=%u\n",
326 job_buffer_ptr->job_array[i].job_id,
327 job_buffer_ptr->job_array[i].user_id);
328 }
329 slurm_free_job_info_msg (job_buffer_ptr);
331 if (slurm_pid2jobid (getpid(), &job_id))
333 slurm_perror ("slurm_load_jobs error");
334 else
335 printf ("Slurm job id = %u\n", job_id);
336 exit (0);
338 }
339
342 These functions are included in the libslurm library, which must be
343 linked to your process for use (e.g. "cc -lslurm myprog.c").
344 The command field in the job record will be the name of user program to
346 be launched by the srun or sbatch command. The field is not set when
347 either the salloc command is used or the sbatch command is used with
348 the --wrap option.
349 Some data structures contain index values to cross-reference each
351 other. If the show_flags argument is not set to SHOW_ALL when getting
352 this data, these index values will be invalid.
353 The slurm_hostlist_ functions can be used to convert Slurm node list
355 expressions into a collection of individual node names.
356
359 Copyright (C) 2002-2006 The Regents of the University of California.
360 Copyright (C) 2008-2010 Lawrence Livermore National Security. Produced
361 at Lawrence Livermore National Laboratory (cf, DISCLAIMER).
362 CODE-OCEC-09-009. All rights reserved.
363 This file is part of Slurm, a resource management program. For
365 details, see <https://slurm.schedmd.com/>.
366 Slurm is free software; you can redistribute it and/or modify it under
368 the terms of the GNU General Public License as published by the Free
369 Software Foundation; either version 2 of the License, or (at your
370 option) any later version.
371 Slurm is distributed in the hope that it will be useful, but WITHOUT
373 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
374 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
375 for more details.
376
379 scontrol(1), squeue(1), slurm_hostlist_create(3),
380 slurm_hostlist_shift(3), slurm_hostlist_destroy(3), slurm_alloca‐
381 tion_lookup(3), slurm_get_errno(3), slurm_perror(3), slurm_strerror(3)
382November 2020 Slurm job information reporting functions Slurm API(3)