genders/source/man/genders_nodelist_create.3

.\"############################################################################
.\"  $Id: genders_nodelist_create.3,v 1.8 2010-02-02 00:04:34 chu11 Exp $
.\"############################################################################
.\"  Copyright (C) 2007-2019 Lawrence Livermore National Security, LLC.
.\"  Copyright (C) 2001-2007 The Regents of the University of California.
.\"  Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER).
.\"  Written by Jim Garlick <garlick@llnl.gov> and Albert Chu <chu11@llnl.gov>.
.\"  UCRL-CODE-2003-004.
.\"  
.\"  This file is part of Genders, a cluster configuration database.
.\"  For details, see <http://www.llnl.gov/linux/genders/>.
.\"  
.\"  Genders 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.
.\"  
.\"  Genders 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.
.\"  
.\"  You should have received a copy of the GNU General Public License along
.\"  with Genders.  If not, see <http://www.gnu.org/licenses/>.
.\"############################################################################
.TH GENDERS_NODELIST_CREATE 3 "August 2003" "LLNL" "LIBGENDERS"
.SH NAME
genders_nodelist_create, genders_nodelist_clear,
genders_nodelist_destroy, genders_attrlist_create,
genders_attrlist_clear, genders_attrlist_destroy,
genders_vallist_create, genders_vallist_clear, genders_vallist_destroy
- list create, clear, and destroy routines
.SH SYNOPSIS
.B #include <genders.h>
.sp
.BI "int genders_nodelist_create(genders_t handle, char ***nodelist);"
.sp
.BI "int genders_nodelist_clear(genders_t handle, char **nodelist);"
.sp
.BI "int genders_nodelist_destroy(genders_t handle, char **nodelist);"
.sp
.BI "int genders_attrlist_create(genders_t handle, char ***attrlist);"
.sp
.BI "int genders_attrlist_clear(genders_t handle, char **attrlist);"
.sp
.BI "int genders_attrlist_destroy(genders_t handle, char **attrlist);"
.sp
.BI "int genders_vallist_create(genders_t handle, char ***vallist);"
.sp
.BI "int genders_vallist_clear(genders_t handle, char **vallist);"
.sp
.BI "int genders_vallist_destroy(genders_t handle, char **vallist);"
.br
.SH DESCRIPTION
\fBgenders_nodelist_create()\fR, \fBgenders_nodelist_clear()\fR,
\fBgenders_nodelist_destroy()\fR, \fBgenders_attrlist_create()\fR,
\fBgenders_attrlist_clear()\fR, \fBgenders_attrlist_destroy()\fR,
\fBgenders_vallist_create()\fR, \fBgenders_vallist_clear()\fR, and
\fBgenders_vallist_destroy()\fR are used to create, clear, and destroy
lists (arrays of strings) for use with
.BR genders_getnodes (3),
.BR genders_getattr (3),
and
.BR genders_getattr_all (3).  

\fBgenders_nodelist_create()\fR, \fBgenders_attrlist_create()\fR, and
\fBgenders_vallist_create()\fR creates a list with minimum size to
store nodes, attributes, and attribute values respectively.
\fInodelist\fR, \fIattrlist\fR, and \fIvallist\fR are respectively set
to point to the created list.  The created lists are guaranteed to
store all the node, attribute, and value information returned from
.BR genders_getnodes (3),
.BR genders_getattr (3),
and
.BR genders_getattr_all (3).  

\fBgenders_nodelist_clear()\fR, \fBgenders_attrlist_clear()\fR, and
\fBgenders_vallist_clear()\fR clear any information stored in the
lists pointed to by \fInodelist\fR, \fIattrlist\fR, and \fIvallist\fR
repectively.  They do not have be called after their respective create
functions.  They only have to be called after they are used in
.BR genders_getnodes (3),
.BR genders_getattr (3),
and
.BR genders_getattr_all (3),
and the programmer wishes to re-use the list.  

\fBgenders_nodelist_destroy()\fR, \fBgenders_attrlist_destroy()\fR,
and \fBgenders_vallist_destroy()\fR destroy the lists pointed to by
\fInodelist\fR, \fIattrlist\fR, and \fIvallist\fR respectively.

If no attributes or values are listed in the genders database all of
the attrlist and vallist functions will do nothing.  The pointer
passed into \fBgenders_attrlist_create()\fR and
\fBgenders_vallist_create()\fR will not be set.

.br
.SH RETURN VALUES
On success, \fBgenders_nodelist_create()\fR,
\fBgenders_attrlist_create()\fR, and \fBgenders_vallist_create()\fR
return the number of elements the created list can store.  On success,
\fBgenders_nodelist_clear()\fR, \fBgenders_attrlist_clear()\fR,
\fBgenders_vallist_clear()\fR \fBgenders_nodelist_destroy()\fR,
\fBgenders_attrlist_destroy()\fR, \fBgenders_vallist_destroy()\fR
return 0.  On error, -1 is returned, and an error code is returned in
\fIhandle\fR.  The error code can be retrieved via
.BR genders_errnum (3)
, and a description of the error code can be retrieved via 
.BR genders_strerror (3).  
Error codes are defined in genders.h.
.br
.SH ERRORS
.TP
.B GENDERS_ERR_NULLHANDLE
The \fIhandle\fR parameter is NULL.  The genders handle must be
created with
.BR genders_handle_create (3).
.TP
.B GENDERS_ERR_NOTLOADED
.BR genders_load_data (3)
has not been called to load genders data.  Before lists of appropriate
size can be created, the genders file must be read and parsed.
.TP
.B GENDERS_ERR_PARAMETERS
An incorrect parameter has been passed in.  
.TP
.B GENDERS_ERR_NULLPTR
A null pointer has been found in the list passed in.
.TP
.B GENDERS_ERR_OUTMEM
.BR malloc (3)
has failed internally, system is out of memory.
.TP
.B GENDERS_ERR_MAGIC 
\fIhandle\fR has an incorrect magic number.  \fIhandle\fR does not
point to a genders handle or \fIhandle\fR has been destroyed by
.BR genders_handle_destroy (3).
.br
.SH FILES
/usr/include/genders.h
.SH SEE ALSO
libgenders(3), genders_handle_create(3), genders_load_data(3),
genders_getnodes(3), genders_getattr(3), genders_getattr_all(3),
genders_errnum(3), genders_strerror(3)