.\"############################################################################
.\"  $Id: genders_testattr.3,v 1.15 2010-02-02 00:04:34 chu11 Exp $
.\"############################################################################
.\"  Copyright (C) 2007-2011 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_TESTATTR 3 "August 2003" "LLNL" "LIBGENDERS"
.SH NAME
genders_testattr \- test if a node has an attribute  
.SH SYNOPSIS
.B #include <genders.h>
.sp
.BI "int genders_testattr(genders_t handle, const char *node, const char *attr, char *val, int len);"
.sp
.BI "int genders_testattrval(genders_t handle, const char *node, const char *attr, const char *val);"
.br
.SH DESCRIPTION
\fBgenders_testattr()\fR tests if the node pointed to by \fInode\fR
contains the attribute pointed to by \fIattr\fR.  If \fInode\fR is
NULL, the current node is tested.  If the attribute is found, its
value is stored in the buffer pointed to by \fIval\fR.  \fIlen\fR
should indicate the length of the buffer.  If the attribute value is
not needed, \fIval\fR can be set to NULL.

To avoid passing in an attribute value buffer that is not large enough
to store the attribute value,
.BR genders_getmaxvallen (3)
should be used to determine the minimum buffer size that should be used.

\fBgenders_testattrval()\fR tests if the node pointed to by \fInode\fR
contains the attribute pointed to by \fIattr\fR and if that attribute
is equal to the attribute value pointed to by \fIval\fR.  If \fIval\fR
is NULL, only the attribute is tested.
.br
.SH RETURN VALUES
For \fBgenders_testattr()\fR, if the node contains the attribute, 1 is
returned.  0 is returned if the node does not contain the attribute.

For \fBgenders_testattrval()\fR, if the node contains the attribute
and it is equal to the attribute value, 1 is returned.  0 is returned
if the node does not contain the attribute, or if the attribute is not
equal to the attribute value.

For both \fBgenders_testattr()\fR and \fBgenders_testattrval()\fR, -1
is returned on error, 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.
.TP
.B GENDERS_ERR_OVERFLOW
The buffer pointed to by \fIval\fR is not large enough to store the
attribute value.
.TP
.B GENDERS_ERR_PARAMETERS
An incorrect parameter has been passed in.  
.TP
.B GENDERS_ERR_NOTFOUND
The node pointed to by \fInode\fR cannot be found in the genders file
or if \fInode\fR=NULL, the machine genders is running on is not listed
in the genders database.
.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_getmaxvallen(3), genders_errnum(3), genders_strerror(3)