1Slurm API(3) Slurm job information reporting functions Slurm API(3)
2
6 slurm_get_end_time, slurm_get_rem_time, slurm_get_select_jobinfo,
7 slurm_job_cpus_allocated_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_get_select_jobinfo (
76 select_jobinfo_t jobinfo,
77 enum select_data_type data_type,
78 void *data );
79 int slurm_job_cpus_allocated_on_node_id (
81 job_resources_t *job_resrcs_ptr,
82 int node_id
83 );
84 int slurm_job_cpus_allocated_on_node (
86 job_resources_t *job_resrcs_ptr,
87 const char *node_name
88 );
89 int slurm_job_cpus_allocated_str_on_node_id (
91 char *cpus,
92 size_t cpus_len,
93 job_resources_t *job_resrcs_ptr,
94 int node_id
95 );
96 int slurm_job_cpus_allocated_str_on_node (
98 char *cpus,
99 size_t cpus_len,
100 job_resources_t *job_resrcs_ptr,
101 const char *node_name
102 );
103
106 INTEGER*4 JOBID, REM_TIME
107 REM_TIME = ISLURM_GET_REM_TIME(JOBID)
108 REM_TIME = ISLURM_GET_REM_TIME2()
109 ISLURM_GET_REM_TIME2() is equivalent to ISLURM_GET_REM_TIME() except
111 that the JOBID is taken from the SLURM_JOB_ID environment variable,
112 which is set by Slurm for tasks which it launches. Both functions
113 return the number of seconds remaining before the job reaches the end
114 of it's allocated time.
115
118 cpus Specifies a pointer to allocated memory into which the string
119 representing the list of allocated CPUs on the node is placed.
120 cpus_len
122 The size in bytes of the allocated memory space pointed by cpus.
123 data_type
125 Identifies the type of data to retrieve jobinfo. Note that dif‐
126 ferent types of data are associated with different computer
127 types and different configurations.
128 data The data value identified with data_type is returned in the
130 location specified by data. If a type of data is requested that
131 does not exist on a particular computer type or configuration,
132 slurm_get_select_jobinfo returns an error. See the slurm.h
133 header file for identification of the data types associated with
134 each value of data_type.
135 end_time_ptr
137 Specified a pointer to a storage location into which the
138 expected termination time of a job is placed.
139 job_info_msg_pptr
141 Specifies the double pointer to the structure to be created and
142 filled with the time of the last job update, a record count, and
143 detailed information about each job. Detailed job information is
144 written to fixed sized records and includes: ID number, name,
145 user ID, state, assigned or requested node names, indexes into
146 the node table, etc. In the case of indexes into the node table,
147 this is an array of integers with pairs of start and end index
148 number into the node information records and the data is termi‐
149 nated with a value of -1. See slurm.h for full details on the
150 data structure's contents.
151 job_id Specifies a slurm job id. If zero, use the SLURM_JOB_ID environ‐
153 ment variable to get the jobid.
154 job_id_ptr
156 Specifies a pointer to a storage location into which a Slurm job
157 id may be placed.
158 job_info_msg_ptr
160 Specifies the pointer to the structure created by slurm_load_job
161 or slurm_load_jobs.
162 jobinfo
164 Job-specific information as constructed by Slurm's NodeSelect
165 plugin. This data object is returned for each job by the
166 slurm_load_job or slurm_load_jobs function.
167 job_pid
169 Specifies a process id of some process on the current node.
170 job_ptr
172 Specifies a pointer to a single job records from the
173 job_info_msg_ptr data structure.
174 job_resrcs_ptr
176 Pointer to a job_resources_t structure previously using the
177 function slurm_load_job with a show_flags value of SHOW_DETAIL.
178 node_id
180 Zero origin ID of a node allocated to a job.
181 node_name
183 Name of a node allocated to a job.
184 one_liner
186 Print one record per line if non-zero.
187 out_file
189 Specifies the file to print data to.
190 show_flags
192 Job filtering flags, may be ORed. Information about jobs in
193 partitions that are configured as hidden and partitions that the
194 user's group is unable to utilize are not reported by default.
195 SHOW_ALL Report information about jobs in all partitions,
197 even partitions to which the user lacks access
198 (this access can be blocked by system administers).
199 SHOW_DETAIL Report detailed resource allocation information
201 (e.g. identification of the specific CPUs allocated
202 to a job on each node).
203 SHOW_LOCAL Report information only about jobs on the local
205 cluster, even if the cluster is part of a federa‐
206 tion.
207 SHOW_SIBLING Report information about all sibling jobs on a fed‐
209 erated cluster.
210 update_time
213 For all of the following informational calls, if update_time is
214 equal to or greater than the last time changes where made to
215 that information, new information is not returned. Otherwise
216 all the configuration. job, node, or partition records are
217 returned.
218 user_id
220 ID of user we want information for.
221
224 slurm_free_resource_allocation_response_msg Free slurm resource alloca‐
225 tion response message.
226 slurm_free_job_info_msg Release the storage generated by the
228 slurm_load_jobs function.
229 slurm_get_end_time Returns the expected termination time of a specified
231 Slurm job. The time corresponds to the exhaustion of the job´s or par‐
232 tition´s time limit. NOTE: The data is cached locally and only
233 retrieved from the Slurm controller once per minute.
234 slurm_get_rem_time Returns the number of seconds remaining before the
236 expected termination time of a specified Slurm job id. The time corre‐
237 sponds to the exhaustion of the job´s or partition´s time limit. NOTE:
238 The data is cached locally and only retrieved from the Slurm controller
239 once per minute.
240 slurm_job_cpus_allocated_on_node and slurm_job_cpus_allo‐
242 cated_on_node_id return the number of CPUs allocated to a job on a spe‐
243 cific node allocated to a job.
244 slurm_job_cpus_allocated_str_on_node and slurm_job_cpus_allo‐
246 cated_str_on_node_id return a string representing the list of CPUs
247 allocated to a job on a specific node allocated to a job.
248 slurm_load_job Returns a job_info_msg_t that contains an update time,
250 record count, and array of job_table records for some specific job ID.
251 slurm_load_jobs Returns a job_info_msg_t that contains an update time,
253 record count, and array of job_table records for all jobs.
254 slurm_load_job_yser Returns a job_info_msg_t that contains an update
256 time, record count, and array of job_table records for all jobs associ‐
257 ated with a specific user ID.
258 slurm_load_job_user issues RPC to get slurm information about all jobs
260 to be run as the specified user.
261 slurm_notify_job Sends the specified message to standard output of the
263 specified job ID.
264 slurm_pid2jobid Returns a Slurm job id corresponding to the supplied
266 local process id. This only works for processes which Slurm spawns and
267 their descendants.
268 slurm_print_job_info Prints the contents of the data structure describ‐
270 ing a single job records from the data loaded by the slurm_load_node
271 function.
272 slurm_print_job_info_msg Prints the contents of the data structure
274 describing all job records loaded by the slurm_load_node function.
275
278 For slurm_get_rem_time on success a number of seconds is returned. For
279 all other functions zero is returned on success. On error, -1 is
280 returned, and Slurm error code is set appropriately.
281
284 SLURM_NO_CHANGE_IN_DATA Data has not changed since update_time.
285 SLURM_PROTOCOL_VERSION_ERROR Protocol version has changed, re-link your
287 code.
288 ESLURM_INVALID_JOB_ID Request for information about a non-existent job.
290 SLURM_PROTOCOL_SOCKET_IMPL_TIMEOUT Timeout in communicating with Slurm
292 controller.
293 INVAL Invalid function argument.
295
298 #include <stdio.h>
299 #include <stdlib.h>
300 #include <slurm/slurm.h>
301 #include <slurm/slurm_errno.h>
302 #include <sys/types.h>
303 int main (int argc, char *argv[])
305 {
306 int i;
307 job_info_msg_t * job_buffer_ptr = NULL;
308 job_info_t * job_ptr;
309 uint32_t job_id;
310 /* get and dump some job information */
312 if ( slurm_load_jobs ((time_t) NULL,
313 &job_buffer_ptr, SHOW_ALL) ) {
314 slurm_perror ("slurm_load_jobs error");
315 exit (1);
316 }
317 /* The easy way to print... */
319 slurm_print_job_info_msg (stdout, job_buffer_ptr, 0);
320 /* A harder way.. */
322 for (i = 0; i < job_buffer_ptr->record_count; i++) {
323 job_ptr = &job_buffer_ptr->job_array[i];
324 slurm_print_job_info(stdout, job_ptr, 1);
325 }
326 /* The hardest way. */
328 printf ("Jobs updated at %lx, record count %d\n",
329 job_buffer_ptr->last_update,
330 job_buffer_ptr->record_count);
331 for (i = 0; i < job_buffer_ptr->record_count; i++) {
332 printf ("JobId=%u UserId=%u\n",
333 job_buffer_ptr->job_array[i].job_id,
334 job_buffer_ptr->job_array[i].user_id);
335 }
336 if (job_buffer_ptr->record_count >= 1) {
338 uint16_t nodes;
339 if (slurm_get_select_jobinfo(
340 job_buffer_ptr->job_array[0].select_jobinfo,
341 SELECT_JOBDATA_NODE_CNT,
342 &nodes) == SLURM_SUCCESS)
343 printf("JobId=%u Nodes=%u\n",
344 job_buffer_ptr->job_array[0].job_id,
345 nodes);
346 }
347 slurm_free_job_info_msg (job_buffer_ptr);
349 if (slurm_pid2jobid (getpid(), &job_id))
351 slurm_perror ("slurm_load_jobs error");
352 else
353 printf ("Slurm job id = %u\n", job_id);
354 exit (0);
356 }
357
360 These functions are included in the libslurm library, which must be
361 linked to your process for use (e.g. "cc -lslurm myprog.c").
362 The command field in the job record will be the name of user program to
364 be launched by the srun or sbatch command. The field is not set when
365 either the salloc command is used or the sbatch command is used with
366 the --wrap option.
367 Some data structures contain index values to cross-reference each
369 other. If the show_flags argument is not set to SHOW_ALL when getting
370 this data, these index values will be invalid.
371 The slurm_hostlist_ functions can be used to convert Slurm node list
373 expressions into a collection of individual node names.
374
377 Copyright (C) 2002-2006 The Regents of the University of California.
378 Copyright (C) 2008-2010 Lawrence Livermore National Security. Produced
379 at Lawrence Livermore National Laboratory (cf, DISCLAIMER).
380 CODE-OCEC-09-009. All rights reserved.
381 This file is part of Slurm, a resource management program. For
383 details, see <https://slurm.schedmd.com/>.
384 Slurm is free software; you can redistribute it and/or modify it under
386 the terms of the GNU General Public License as published by the Free
387 Software Foundation; either version 2 of the License, or (at your
388 option) any later version.
389 Slurm is distributed in the hope that it will be useful, but WITHOUT
391 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
392 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
393 for more details.
394
397 scontrol(1), squeue(1), slurm_hostlist_create(3),
398 slurm_hostlist_shift(3), slurm_hostlist_destroy(3), slurm_alloca‐
399 tion_lookup(3), slurm_get_errno(3), slurm_perror(3), slurm_strerror(3)
400April 2015 Slurm job information reporting functions Slurm API(3)