getava(IAC)

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(S). 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(S) to obtain space for a copy of the strings in the list. Once setava has been called, the space used by the AVAs 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(S)) 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(S) for the list or the strings in the list.

References

invoke(IAC), malloc(S)

Notices

Calling putava with a list argument of NULL can be used to initialize a dynamically allocated AVA list.

putava uses realloc (see malloc(S)) 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.