Updated API demo code in programmer.guide.html

Initial version of get/free info API man page in slurm_info.3

doc/man/man3/slurm_info.3

+.TH "Slurm API" "3" "Release 0.0.0" "Morris Jette" "Slurm informational calls"
+.SH "NAME"
+.LP 
+\fBslurm_info\fR \- Slurm informational calls
+.SH "SYNTAX"
+.LP 
+#include <slurm.h>
+.br 
+int \fBslurm_load_ctl_conf\fR (
+.br 
+	time_t \fIupdate_time\fP,
+.br 
+	slurm_ctl_conf_info_msg_t **\fIconf_info_msg_pptr\fP
+.br 
+);
+.LP
+void \fBslurm_free_ctl_conf\fR (
+.br 
+	slurm_ctl_conf_info_msg_t *\fIconf_info_msg_ptr\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 
+);
+.LP
+void \fBslurm_free_job_info\fR (
+.br 
+	job_info_msg_t *\fIjob_info_msg_ptr\fP
+.br 
+);
+.LP 
+int \fBslurm_load_node\fR (
+.br 
+	time_t \fIupdate_time\fP, 
+.br 
+	node_info_msg_t **\fInode_info_msg_pptr\fP
+.br 
+);
+.LP
+void \fBslurm_free_node_info\fR (
+.br 
+	node_info_msg_t *\fInode_info_msg_ptr\fP
+.br 
+);
+.LP 
+int \fBslurm_load_partitions\fR (
+.br 
+	time_t \fIupdate_time\fR, 
+.br 
+	partition_info_msg_t **\fIpartition_info_msg_pptr\fP
+.br 
+ );
+.LP
+void \fBslurm_free_partition_info\fR (
+.br 
+	partition_info_msg_t *\fIpartition_info_msg_ptr\fP
+.br 
+);
+.SH "ARGUMENTS"
+.LP 
+.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 
+\fIconf_info_msg_pptr\fP
+Specifies the double pointer to the structure to be created and filled with the time of the last configuration update and detailed configuration information. Configuration information includes control machine names, file names, timer values, etc. See slurm.h for full details on the data structure's contents. 
+.TP 
+\fIconf_info_msg_ptr\fP
+Specifies the pointer to the structure created by slurm_load_ctl_conf. 
+.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, indecies into the node table, etc. In the case of indecies into the node table, this is an array of integers with pairs of start and end index number ino the node infomration 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_info_msg_ptr\fP
+Specifies the pointer to the structure created by slurm_load_jobs. 
+.TP 
+\fInode_info_msg_pptr\fP
+Specifies the double pointer to the structure to be created and filled with the time of the last node update, a record count, and detailed information about each node. Detailed node information is written to fixed sized records and includes: name, state, processor count, memory size, etc. See slurm.h for full details on the data structure's contents. 
+.TP 
+\fInode_info_msg_ptr\fP
+Specifies the pointer to the structure created by slurm_load_node. 
+.TP 
+\fIpartition_info_msg_pptr\fP
+Specifies the double pointer to the structure to be created and filled with the time of the last partition update, a record count, and detailed information about each partition. Detailed partition information is written to fixed sized records and includes: name, state, job time limit, job size limit, node names, indecies into the node table, etc. In the case of indecies into the node table, this is an array of integers with pairs of start and end index number ino the node infomration records and the data is terminated with a value of -1. See slurm.h for full details on the data structure's contents. 
+.TP 
+\fIpartition_info_msg_ptr\fP
+Specifies the pointer to the structure created by slurm_load_partitions. 
+.SH "DESCRIPTION"
+.LP 
+\fBslurm_load_ctl_conf\fR Returns a slurm_ctl_conf_info_msg_t that contains an slurm configuration records.
+.LP 
+\fBslurm_free_ctl_conf\fR Release the storage generated by the slurm_load_ctl_conf function.
+.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_free_job_info\fR Release the storage generated by the slurm_load_jobs function.
+.LP 
+\fBslurm_load_node\fR Returns a node_info_msg_t that contains an update time, record count, and array of node_table records for all nodes.
+.LP 
+\fBslurm_free_node_info\fR Release the storage generated by the slurm_load_node function.
+.LP 
+\fBslurm_load_partitions\fR Returns a partition_info_msg_t that contains an update time, record count, and array of partition_table records for all partitions.
+.LP 
+\fBslurm_free_partition_info\fR Release the storage generated by the slurm_load_partitions function.
+.SH "RETURN VALUE"
+.LP
+On success, zero is returned. On error, -1 is returned, and errno 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.
+.SH "EXAMPLE"
+.eo
+.LP 
+#include <stdio.h>
+.br
+#include <slurm.h>
+.LP 
+int main (int argc, char *argv[])
+.br 
+{
+.br 
+	int error_code, i, j, k;
+.br
+	slurm_ctl_conf_info_msg_t * conf_info_msg_ptr = NULL;
+.br
+	job_info_msg_t	* job_info_msg = NULL;
+.br
+	node_info_msg_t *node_info_ptr = NULL;
+.br
+	partition_info_msg_t *part_info_ptr = NULL;
+.LP
+	/* get and print some configuration information */
+.br
+	if ( slurm_load_ctl_conf ((time_t) NULL, &conf_info_msg_ptr ) ) {
+.br
+		printf ("slurm_load_ctl_conf errno %d\n", errno);
+.br
+		exit (1);
+.br
+	}
+.br
+	printf ("control_machine = %s\n", slurm_ctl_conf_ptr->control_machine);
+.br
+	printf ("server_timeout = %u\n", slurm_ctl_conf_ptr->server_timeout);
+.br
+	slurm_free_ctl_conf (conf_info_msg_ptr);
+.LP
+	/* get and dump some job information */
+.br
+	if ( slurm_load_jobs ((time_t) NULL, &job_buffer_ptr) ) {
+.br
+		printf ("slurm_load_jobs errno %d\n", errno);
+.br
+		exit (1);
+.br
+	}
+.br
+	printf ("Jobs updated at %lx, record count %d\n",
+.br
+		job_buffer_ptr->last_update, 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
+	}			
+.br
+	slurm_free_job_info (job_buffer_ptr);
+.LP
+	/* get and dump some node information */
+.br
+	if ( slurm_load_node ((time_t) NULL, &node_buffer_ptr) ) {
+.br
+		printf ("slurm_load_node errno %d\n", errno);
+.br
+		exit (1);
+.br
+	}
+.br
+	for (i = 0; i < node_buffer_ptr->node_count; i++) {
+.br
+		printf ("NodeName=%s CPUs=%u\n", 
+.br
+			node_buffer_ptr->node_array[i].name, 
+.br
+			node_buffer_ptr->node_array[i].cpus);
+.br
+	}			
+.LP
+	/* get and dump some partition information */
+.br
+	/* note that we use the node information loaded above and */
+.br
+	/* we assume the node table entries have not changed since */
+.br
+	if ( slurm_load_partitions ((time_t) NULL, &part_buffer_ptr) ) {
+.br
+		printf ("slurm_load_part errno %d\n", errno);
+.br
+		exit (1);
+.br
+	}
+.br
+	printf("Partitions updated at %lx, record count %d\n",
+.br
+		part_buffer_ptr->last_update, part_buffer_ptr->record_count);
+.br
+	for (i = 0; i < part_buffer_ptr->record_count; i++) {
+.br
+		printf ("PartitionName=%s MaxTime=%u Nodes=%s:", 
+.br
+			part_info_ptr->partition_array[i].name, 
+.br
+			part_info_ptr->partition_array[i].max_time,
+.br
+			part_info_ptr->partition_array[i].nodes );
+.br
+		for (j = 0; part_info_ptr->partition_array[i].node_inx; j+=2) {
+.br
+			if (part_info_ptr->partition_array[i].node_inx[j] == -1)
+.br
+				break;
+.br
+			for (k = part_info_ptr->partition_array[i].node_inx[j];
+.br
+			     k <= part_info_ptr->partition_array[i].node_inx[j+1]; 
+.br
+			     k++) {
+.br
+				printf ("%s ", node_buffer_ptr->node_array[k].name);
+.br
+			}
+.br
+		}
+.br
+		printf("\n\n");
+.br
+	}
+.br
+	slurm_free_node_info (node_buffer_ptr);
+.br
+	slurm_free_partition_info (part_buffer_ptr);
+.br
+	exit (0);
+.br 
+}
+.ec
+.SH "SEE ALSO"
+.LP 
+\fBslurm_strerror\fR(3), \fBslurm_perror\fR(3)
+