| .TH "Slurm API" "3" "May 2009" "Morris Jette" "Slurm administrative calls" |
| .SH "NAME" |
| slurm_create_partition, slurm_create_reservation, |
| slurm_delete_partition, slurm_delete_reservation, |
| slurm_init_part_desc_msg, slurm_init_resv_desc_msg, |
| slurm_reconfigure, slurm_shutdown, slurm_takeover, slurm_update_job, |
| ,slurm_init_update_node_msg slurm_update_node, slurm_update_partition, |
| slurm_update_reservation |
| \- Slurm administrative functions |
| .SH "SYNTAX" |
| .LP |
| #include <slurm/slurm.h> |
| .LP |
| int \fBslurm_create_partition\fR ( |
| .br |
| update_part_msg_t *\fIupdate_part_msg_ptr\fP |
| .br |
| ); |
| .LP |
| int \fBslurm_create_reservation\fR ( |
| .br |
| reserve_request_msg_t *\fIupdate_resv_msg_ptr\fP |
| .br |
| ); |
| .LP |
| int \fBslurm_delete_partition\fR ( |
| .br |
| delete_part_msg_t *\fIdelete_part_msg_ptr\fP |
| .br |
| ); |
| .LP |
| int \fBslurm_delete_reservation\fR ( |
| .br |
| reservation_name_msg_t *\fIdelete_resv_msg_ptr\fP |
| .br |
| ); |
| .LP |
| void \fBslurm_init_part_desc_msg\fR ( |
| .br |
| update_part_msg_t *\fIupdate_part_msg_ptr\fP |
| .br |
| ); |
| .LP |
| void \fBslurm_init_resv_desc_msg\fR ( |
| .br |
| reserve_request_msg_t *\fIupdate_resv_msg_ptr\fP |
| .br |
| ); |
| .LP |
| int \fBslurm_reconfigure\fR ( ); |
| .LP |
| int \fBslurm_shutdown\fR ( |
| .br |
| uint16_t \fIshutdown_options\fP |
| .br |
| ); |
| .LP |
| int \fBslurm_takeover\fR ( ); |
| .LP |
| int \fBslurm_update_job\fR ( |
| .br |
| job_desc_msg_t *\fIupdate_job_msg_ptr\fP |
| .br |
| ); |
| .LP |
| void \fBslurm_init_update_node_msg\fR( |
| .br |
| update_node_msg_t *\fIupdate_node_msg_ptr\fP |
| .br |
| ); |
| .LP |
| int \fBslurm_update_node\fR ( |
| .br |
| update_node_msg_t *\fIupdate_node_msg_ptr\fP |
| .br |
| ); |
| .LP |
| int \fBslurm_update_partition\fR ( |
| .br |
| update_part_msg_t *\fIupdate_part_msg_ptr\fP |
| .br |
| ); |
| .LP |
| int \fBslurm_update_reservation\fR ( |
| .br |
| reserve_request_msg_t *\fIupdate_resv_msg_ptr\fP |
| .br |
| ); |
| .SH "ARGUMENTS" |
| .LP |
| .TP |
| \fIshutdown_options\fP |
| 0: all slurm daemons are shutdown |
| .br |
| 1: slurmctld generates a core file |
| .br |
| 2: only the slurmctld is shutdown (no core file) |
| .TP |
| \fIdelete_part_msg_ptr\fP |
| Specifies the pointer to a partition delete request specification. |
| See slurm.h for full details on the data structure's contents. |
| .TP |
| \fIdelete_resv_msg_ptr\fP |
| Specifies the pointer to a reservation delete request specification. |
| See slurm.h for full details on the data structure's contents. |
| .TP |
| \fIupdate_job_msg_ptr\fP |
| Specifies the pointer to a job update request specification. See slurm.h |
| for full details on the data structure's contents. |
| .TP |
| \fIupdate_node_msg_ptr\fP |
| Specifies the pointer to a node update request specification. See slurm.h |
| for full details on the data structure's contents. |
| .TP |
| \fIupdate_part_msg_ptr\fP |
| Specifies the pointer to a partition create or update request specification. |
| See slurm.h for full details on the data structure's contents. |
| .TP |
| \fIupdate_resv_msg_ptr\fP |
| Specifies the pointer to a reservation create or update request specification. |
| See slurm.h for full details on the data structure's contents. |
| .SH "DESCRIPTION" |
| .LP |
| \fBslurm_create_partition\fR Request that a new partition be created. |
| Initialize the data structure using the \fBslurm_init_part_desc_msg\fR |
| function prior to setting values of the parameters to be changed. |
| Note: \fBslurm_init_part_desc_msg\fR is not equivalent to setting the data |
| structure values to zero. A partition name must be set for the call to |
| succeed. |
| This function may only be successfully executed by user root. |
| .LP |
| \fBslurm_create_reservation\fR Request that a new reservation be created. |
| Initialize the data structure using the \fBslurm_init_resv_desc_msg\fR |
| function prior to setting values of the parameters to be changed. |
| Note: \fBslurm_init_resv_desc_msg\fR is not equivalent to setting the data |
| structure values to zero. The reservation's time limits, user or |
| account restrictions, and node names or a node count must be specified for |
| the call to succeed. |
| This function may only be successfully executed by user root. |
| .LP |
| \fBslurm_delete_partition\fR Request that the specified partition be deleted. |
| All jobs associated with the identified partition will be terminated and |
| purged. This function may only be successfully executed by user root. |
| .LP |
| \fBslurm_delete_reservation\fR Request that the specified reservation be |
| deleted. This function may only be successfully executed by user root. |
| .LP |
| \fBslurm_init_part_desc_msg\fR Initialize the contents of a partition |
| descriptor with default values. Note: \fBslurm_init_part_desc_msg\fR is |
| not equivalent to setting the data structure values to zero. Execute |
| this function before executing \fBslurm_create_partition\fR or |
| \fBslurm_update_partition\fR. |
| .LP |
| \fBslurm_init_resv_desc_msg\fR Initialize the contents of a reservation |
| descriptor with default values. Note: \fBslurm_init_resv_desc_msg\fR is |
| not equivalent to setting the data structure values to zero. Execute this |
| function before executing \fBslurm_create_reservation\fR or |
| \fBslurm_update_reservation\fR. |
| .LP |
| \fBslurm_reconfigure\fR Request that the Slurm controller re\-read its |
| configuration file. The new configuration parameters take effect |
| immediately. This function may only be successfully executed by user root. |
| .LP |
| \fBslurm_shutdown\fR Request that the Slurm controller terminate. This |
| function may only be successfully executed by user root. |
| .LP |
| \fBslurm_takeover\fR Request that the Slurm primary controller shutdown |
| immediately and the backup controller take over. |
| This function may only be successfully executed by user root. |
| .LP |
| \fBslurm_update_job\fR Request that the configuration of a job be updated. Note |
| that most, but not all parameters of a job may be changed by this function. |
| Initialize the data structure using the \fBslurm_init_job_desc_msg\fR function |
| prior to setting values of the parameters to be changed. Note: |
| \fBslurm_init_job_desc_msg\fR is not equivalent to setting the data structure |
| values to zero. This function may only be successfully executed by user root. |
| Note the job priority of zero represents a job that will not be scheduled. |
| Slurm uses the priority one to represent jobs that can not be scheduled until |
| additional nodes are returned to service (i.e. not DOWN, DRAINED, or FAILED). |
| This permits lower priority jobs to utilize those resources which are available. |
| .LP |
| \fBslurm_init_update_node_msg\fR Initialize the contents of an update mpde |
| descriptor with default values. Note: \fBslurm_init_update_node_msg\fR is |
| not equivalent to setting the data structure values to zero. Execute |
| this function before executing \fBslurm_update_node\fR. |
| .LP |
| \fBslurm_update_node\fR Request that the state of one or more nodes be updated. |
| Note that the state of a node (e.g. DRAINING, IDLE, etc.) may be changed, but |
| its hardware configuration may not be changed by this function. If the hardware |
| configuration of a node changes, update the Slurm configuration file and execute |
| the \fBslurm_reconfigure\fR function. This function may only be successfully |
| executed by user root. If used by some autonomous program, the state value |
| most likely to be used is \fBNODE_STATE_DRAIN\fR or \fBNODE_STATE_FAILING\fR. |
| The node state flag \fBNODE_STATE_NO_RESPOND\fR may be specified without |
| changing the underlying node state. Note that the node's |
| \fBNODE_STATE_NO_RESPOND\fR flag will be cleared as soon as the slurmd |
| daemon on that node communicates with the slurmctld daemon. |
| Likewise the state \fBNODE_STATE_DOWN\fR indicates that the slurmd daemon |
| is not responding (and has not responded for an interval at least as long |
| as the \fBSlurmdTimeout\fR configuration parameter). The node will leave the |
| \fBNODE_STATE_DOWN\fR state as soon as the slurmd daemon communicates. |
| .LP |
| \fBslurm_update_partition\fR Request that the configuration of a |
| partition be updated. Note that most, but not all parameters of a |
| partition may be changed by this function. Initialize the data |
| structure using the \fBslurm_init_part_desc_msg\fR function prior |
| to setting values of the parameters to be changed. Note: |
| \fBslurm_init_part_desc_msg\fR is not equivalent to setting the |
| data structure values to zero. This function may only be |
| successfully executed by user root. |
| .LP |
| \fBslurm_update_reservation\fR Request that the configuration of a |
| reservation be updated. Initialize the data structure using the |
| \fBslurm_init_resv_desc_msg\fR function prior to setting values of |
| the parameters to be changed. Note: \fBslurm_init_resv_desc_msg\fR |
| is not equivalent to setting the data structure values to zero. This |
| function may only be successfully executed by user root. |
| .SH "RETURN VALUE" |
| .LP |
| On success, zero is returned. On error, \-1 is returned, and the Slurm error |
| code is set appropriately. |
| .LP |
| Exception: A successful slurm_create_reservation call returns a string |
| containing the name of the reservation, in memory to be freed by the caller. |
| A failed call returns NULL and sets the Slurm error code. |
| .SH "ERRORS" |
| .LP |
| \fBSLURM_PROTOCOL_VERSION_ERROR\fR Protocol version has changed, re\-link your |
| code. |
| .LP |
| \fBESLURM_INVALID_NODE_NAME\fR The requested node name(s) is/are not valid. |
| .LP |
| \fBESLURM_INVALID_NODE_STATE\fR The specified state node state or requested |
| node state transition is not valid. |
| .LP |
| \fBESLURM_INVALID_PARTITION_NAME\fR The requested partition name is not valid. |
| .LP |
| \fBESLURM_INVALID_AUTHTYPE_CHANGE\fR The \fBAuthType\fR parameter can |
| not be changed using the \fBslurm_reconfigure\fR function, but all SLURM |
| daemons and commands must be restarted. See \fBslurm.conf\fR(5) for more |
| information. |
| .LP |
| \fBESLURM_INVALID_SCHEDTYPE_CHANGE\fR The \fBSchedulerType\fR parameter can |
| not be changed using the \fBslurm_reconfigure\fR function, but the |
| \fBslurmctld\fR daemon must be restarted. Manual changes to existing job |
| parameters may also be required. See \fBslurm.conf\fR(5) for more information. |
| .LP |
| \fBESLURM_INVALID_SWITCHTYPE_CHANGE\fR The \fBSwitchType\fR parameter can |
| not be changed using the \fBslurm_reconfigure\fR function, but all |
| SLURM daemons and commands must be restarted. All previously running |
| jobs will be lost. See \fBslurm.conf\fR(5) for more information. |
| .LP |
| \fBESLURM_ACCESS_DENIED\fR The requesting user lacks authorization for |
| the requested action (e.g. trying to delete or modify another user's job). |
| .LP |
| \fBSLURM_PROTOCOL_SOCKET_IMPL_TIMEOUT\fR Timeout in communicating with |
| SLURM controller. |
| .LP |
| \fBESLURM_RESERVATION_ACCESS\fR Requestor is not authorized to access the |
| reservation. |
| .LP |
| \fBESLURM_RESERVATION_INVALID\fR Invalid reservation parameter given, |
| e.g. wrong name given. |
| .LP |
| \fBESLURM_INVALID_TIME_VALUE\fR Invalid time value. |
| .LP |
| \fBESLURM_RESERVATION_BUSY\fR Reservation is busy, e.g. trying to delete a |
| reservation while in use. |
| .LP |
| \fBESLURM_RESERVATION_NOT_USABLE\fR Reservation not usable, e.g. trying to |
| use an expired reservation. |
| .SH "EXAMPLE" |
| .LP |
| #include <stdio.h> |
| .br |
| #include <slurm/slurm.h> |
| .br |
| #include <slurm/slurm_errno.h> |
| .LP |
| int main (int argc, char *argv[]) |
| .br |
| { |
| .br |
| job_desc_msg_t update_job_msg; |
| .br |
| update_node_msg_t update_node_msg; |
| .br |
| partition_desc_msg_t update_part_msg; |
| .br |
| delete_part_msg_t delete_part_msg; |
| .br |
| reserve_request_msg_t resv_msg; |
| .br |
| char *resv_name = NULL; |
| .LP |
| if (slurm_reconfigure ( )) { |
| .br |
| slurm_perror ("slurm_reconfigure error"); |
| .br |
| exit (1); |
| .br |
| } |
| .LP |
| slurm_init_job_desc_msg( &update_job_msg ); |
| .br |
| update_job_msg.job_id = 1234; |
| .br |
| update_job_msg time_limit = 200; |
| .br |
| if (slurm_update_job (&update_job_msg)) { |
| .br |
| slurm_perror ("slurm_update_job error"); |
| .br |
| exit (1); |
| .br |
| } |
| .LP |
| slurm_init_part_desc_msg ( &update_part_msg ); |
| .br |
| update_part_msg.name = "test.partition"; |
| .br |
| update_part_msg.state_up = 0; /* partition down */ |
| .br |
| if (slurm_create_partition (&update_part_msg)) { |
| .br |
| slurm_perror ("slurm_create_partition error"); |
| .br |
| exit (1); |
| .br |
| } |
| .LP |
| update_part_msg.state_up = 1; /* partition up */ |
| .br |
| if (slurm_update_partition (&update_part_msg)) { |
| .br |
| slurm_perror ("slurm_update_partition error"); |
| .br |
| exit (1); |
| .br |
| } |
| .LP |
| delete_part_msg.name = "test.partition"; |
| .br |
| if (slurm_delete_partition (&delete_part_msg)) { |
| .br |
| slurm_perror ("slurm_delete_partition error"); |
| .br |
| exit (1); |
| .br |
| } |
| .LP |
| slurm_init_update_node_msg (&update_node_msg); |
| .br |
| update_node_msg.node_names = "lx[10\-12]"; |
| .br |
| update_node_msg.node_state = NODE_STATE_DRAINING ; |
| .br |
| if (slurm_update_node (&update_node_msg)) { |
| .br |
| slurm_perror ("slurm_update_node error"); |
| .br |
| exit (1); |
| .br |
| } |
| .LP |
| slurm_init_resv_desc_msg ( &resv_msg ); |
| .br |
| resv_msg.start_time = time(NULL) + 60*60; /* One hour from now */ |
| .br |
| resv_msg.duration = 720; /* 12 hours/720 minutes */ |
| .br |
| resv_msg.node_cnt = 10; |
| .br |
| resv_msg.accounts = "admin"; |
| .br |
| resv_name = slurm_create_reservation (&resv_msg); |
| .br |
| if (!resv_name) { |
| .br |
| slurm_perror ("slurm_create_reservation error"); |
| .br |
| exit (1); |
| .br |
| } |
| .br |
| free(resv_name); |
| .br |
| exit (0); |
| .br |
| } |
| |
| .SH "NOTE" |
| These functions are included in the libslurm library, |
| which must be linked to your process for use |
| (e.g. "cc \-lslurm myprog.c"). |
| |
| .SH "COPYING" |
| Copyright (C) 2002\-2007 The Regents of the University of California. |
| 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://computing.llnl.gov/linux/slurm/>. |
| .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), \fBslurm_get_errno\fR(3), \fBslurm_init_job_desc_msg\fR(3), |
| \fBslurm_perror\fR(3), \fBslurm_strerror\fR(3), \fBslurm.conf\fR(5) |
