getava(3I) getava(3I)
NAME
getava, putava, retava, setava - library functions used by IAF
schemes
SYNOPSIS
cc [options] file -liaf
#include <iaf.h>
char *getava(const char *attribute, char **avalist);
char **putava(char *ava, char **avalist);
char **retava(int fd);
int setava(int fd, char **avalist);
DESCRIPTION
getava, putava, retava, and setava are library functions that
provide components of the Identification and Authentication
Facility (IAF) with a means of communicating the values of
Attribute Value Assertion (AVA) attributes.
getava retrieves a value for an AVA attribute. It searches
the AVA list avalist for a string of the form
attribute[=value] and, if the string is present, returns a
pointer to the value portion of the string (which can be the
empty string); otherwise, it returns a NULL pointer.
putava changes a value or adds an attribute to the AVA list.
ava points to a string of the form attribute[=value]. putava
makes the value of the attribute variable attribute equal to
value by replacing an existing AVA string or adding a new one.
In either case, the string pointed to by ava becomes part of
the list, so altering the string will change the list.
Because of this limitation, the ava string should be declared
static if it is declared within a function. The space used by
ava is no longer used once a new string-defining attribute is
passed to putava.
retava retrieves an AVA list previously associated with the
file descriptor fd by setava. Space for the list is allocated
using malloc(3C). If no information is available, or if
sufficient space cannot be allocated, a NULL pointer is
returned; otherwise, a pointer to the list is returned.
setava makes information available to subsequent IAF schemes
and/or applications. fd indicates the file descriptor with
which the information in avalist is associated. setava uses
malloc(3C) to obtain space for a copy of the strings in the
list. Once setava has been called, the space used by the AVAs
Copyright 1994 Novell, Inc. Page 1
getava(3I) getava(3I)
may be reused as the application sees fit.
Return Values
getava returns NULL if the attribute is not in the list.
putava returns NULL if it is unable to obtain enough space via
realloc [see malloc(3C)] for an expanded list; otherwise, it
returns a pointer to the expanded list.
retava returns NULL if there is no information associated with
the file descriptor indicated, or if sufficient storage cannot
be allocated to hold the information.
setava returns NULL if it is unable to obtain enough space via
malloc(3C) for the list or the strings in the list.
REFERENCES
invoke(3I), malloc(3C)
NOTICES
Calling putava with a list argument of NULL can be used to
initialize a dynamically allocated AVA list.
putava uses realloc [see malloc(3C)] to enlarge the list.
Passing a statically allocated list will cause unpredictable
results if the list needs to be expanded.
After putava is called, attribute variables are not
necessarily in alphabetical order.
A potential error is to call the function putava with a
pointer to an automatic variable as the argument and then to
exit the calling function while string is still part of the
list.
Calling setava with a list argument of NULL can be used to
disassociate all AVA information from a given file descriptor.
Copyright 1994 Novell, Inc. Page 2