hostlist_create(3)
SYNOPSIS
#include <flux/hostlist.h>
struct hostlist *hostlist_create (void);
void hostlist_destroy (struct hostlist *hl);
struct hostlist *hostlist_decode (const char *s);
char *hostlist_encode (struct hostlist *hl);
struct hostlist *hostlist_copy (const struct hostlist *hl);
int hostlist_count (struct hostlist *hl);
int hostlist_append (struct hostlist *hl, const char *hosts);
int hostlist_append_list (struct hostlist *hl1, struct hostlist *hl2);
const char *hostlist_nth (struct hostlist *hl, int n);
int hostlist_find (struct hostlist *hl, const char *hostname);
int hostlist_delete (struct hostlist *hl, const char *hosts);
void hostlist_sort (struct hostlist *hl);
void hostlist_uniq (struct hostlist *hl);
const char *hostlist_first (struct hostlist *hl);
const char *hostlist_last (struct hostlist *hl);
const char *hostlist_next (struct hostlist *hl);
const char *hostlist_current (struct hostlist *hl);
int hostlist_remove_current (struct hostlist *hl);
Link with -lflux-hostlist.
DESCRIPTION
A hostlist is an ordered list of hostnames that can be encoded as a
compact string when the hostnames contain numerical indices. For example,
the hostnames test0, test1, ... test127 may be encoded to
test[0-127]. Hostlists are further described in
Flux RFC 29.
The hostlist contains an internal cursor that is used for iteration.
For the functions below that return a const char * hostname,
the returned value may be assumed to remain valid only until the next
call to a function that updates the cursor.
hostlist_create() creates an empty hostlist.
hostlist_destroy() destroys a hostlist.
hostlist_decode() converts an RFC 29 hostlist string into a hostlist.
The caller must free the result with hostlist_destroy().
hostlist_encode() converts a hostlist into an RFC 29 hostlist string.
The caller must free the result with free(3).
hostlist_copy() makes a copy of a hostlist.
The caller must free the result with hostlist_destroy().
hostlist_count() returns the number of hostnames in a hostlist.
hostlist_append() decodes an RFC 29 hostlist string and appends its
hostnames to another hostlist.
hostlist_append_list() appends the hostnames of a hostlist to another
hostlist.
hostlist_nth() sets the cursor to the hostname at index n
(zero origin) and returns it.
hostlist_find() sets the cursor to the position of hostname
and returns its zero-origin index.
hostlist_delete() deletes an RFC 29 hostlist string from a hostlist.
If the cursor hostname is deleted, the cursor is advanced to the next valid
hostname.
hostlist_sort() sorts a hostlist object. The cursor may be updated.
hostlist_uniq() sorts a hostlist object, then removes duplicate
hostnames. The cursor may be updated.
hostlist_first() sets the cursor to the first hostname and returns it.
hostlist_last() sets the cursor to the last hostname and returns it.
hostlist_next() sets the cursor to next hostname and returns it.
hostlist_current() returns the hostname at the cursor.
hostlist_remove_current() removes the hostname at the cursor and sets
the cursor to the next hostname.
RETURN VALUE
hostlist_create(), hostlist_decode(), and hostlist_copy()
return a hostlist on success which must be freed with hostlist_destroy().
On failure, NULL is returned with errno set.
hostlist_encode() returns a string on success that must be freed.
On failure, NULL is returned with errno set.
hostlist_append(), hostlist_append_list(), hostlist_delete(),
and hostlist_remove_current() return a count on success.
On failure, -1 is returned with errno set.
hostlist_count() returns a count. If the hostlist is invalid, zero
is returned.
hostlist_find() returns an index on success.
On failure, -1 is returned with errno set.
hostlist_sort() and hostlist_uniq() return nothing.
Other functions return a string on success, or NULL on failure with
errno set.
ERRORS
- EINVAL
One or more arguments were invalid.
- ENOMEM
Out of memory.
- ERANGE
Internal maximum numerical range span was exceeded.
- ENOENT
Index or hostname was not found.
RESOURCES
Flux: http://flux-framework.org
Flux RFC: https://flux-framework.readthedocs.io/projects/flux-rfc
Issue Tracker: https://github.com/flux-framework/flux-core/issues