sia_collect_trm(3)					     Library Functions Manual						sia_collect_trm(3)

NAME

       sia_collect_trm	- Parameter collection routine for SIA (Security Integration Architecture)

LIBRARY

       Standard C library (libc.so and libc.a)

SYNOPSIS

       #include <sia.h>
       #include <siad.h>

       int sia_collect_trm(
	    int timeout,
	    int rendition,
	    unsigned char *title,
	    int num_prompts,
	    prompt_t *prompts);

PARAMETERS

       timeout	   The timeout parameter is the number of seconds that the sia_collect_trm() routine waits.

       rendition   The rendition parameter is used to determine the style of the presentation and is set to one of the following values:

       SIAMENUONE  Select one of the choices given.

       SIAMENUANY  Select any of the choices given.

       SIAFORM	   Fill out the form.

       SIAONELINER One question with one answer.

       SIAINFO	   Information only.

       SIAWARNING  ERROR or WARNING message.

       title	   Pointer to a title string. A null pointer indicates no title.

       num_prompts The number of prompts in this collection.

       prompts	   A pointer to a prompt_t prompts structure.

DESCRIPTION

       The  sia_collect_trm()  routine	provides parameter collection capability.  The SIA session interfaces and change secure information inter-
       faces use a pre-defined parameter collection capability. The calling application passes the  address  to  a  parameter  collection  routine
       through	the  SIA  middle layer to the siad_* routines. This collection routine allows different security mechanisms to prompt the user for
       different parameters without having to be aware of the user interface details.

EXAMPLES

       The following examples are coded to work with any collection routine callback, not just sia_collect_trm(); as such are not full	standalone
       modules.

       The  following  example shows how the sia_collect_trm() routine can be used to prompt for username and password (such as in login and xdm):
       extern int (*collect)();     /* current SIA collection callback */ prompt_t prompts[8];		/* space for  prompts  */  char  name[16],
       password[80];  /* where to store the data */

       /*  set	up  prompts  for  username  &  password, latter not echoed */ prompts[0].prompt = (unsigned char *) "login: "; prompts[0].result =
       (unsigned  char	*)  name;  prompts[0].min_result_length  =  1;	 prompts[0].max_result_length	=   8;	 prompts[0].control_flags   =	0;
       prompts[1].prompt=  (unsigned  char  *)	"Password:";  prompts[1].result  =  (unsigned  char *) password; prompts[1].min_result_length = 0;
       prompts[1].max_result_length = MAX_PWD_LENGTH; prompts[1].control_flags = SIARESINVIS; if((*collect)(0, SIAFORM, NULL, 2, &prompts) != SIA-
       COLSUCCESS)
	 return(SIADFAIL | SIADSTOP); /* could not collect name, password */

       The  following  example	shows how the sia_collect_trm() routine can choose from a menu: extern int (*collect)(); /* current SIA collection
       callback */ int i;		    /* indexing */ int collecterror;	    /* status */ prompt_t prompts[3];	       /*  prompt  control
       area */

       memset(prompts, 0, sizeof prompts); prompts[0].prompt = (unsigned char *) "a"; prompts[1].prompt = (unsigned char *) "b"; prompts[2].prompt
       = (unsigned char *) "c"; collecterror = (*collect)(SIAONEMIN, SIAMENUONE,      "Pick one of the following:
", 3, prompts); if  (collecter-
       ror  !=	SIACOLSUCCESS)	{	(void)	fputs("Collection  failed.
",	stderr);       return  -1;  }  for (i = 0;  i < 3;  i++) {	if
       (prompts[i].result) {	       (void) printf("You picked %s.
",		prompts[i].prompt);	      return 0;       }  }  (void)
       fputs("Collection return error.
", stderr); return -1;

       The  following  example shows how the sia_collect_trm() routine can put out an information message: extern int (*collect)(); /* current SIA
       collection callback */ prompt_t prompts[1];	    /* space for the output text control */

       prompts[0].prompt = (unsigned char *) "Example text"; (void)(*collect)(0, SIAINFO, "", 1, prompts); return 0;

RETURN VALUES

       The sia_collect_trm() routine returns either SIASUCCESS or SIAFAIL.

ERRORS

       The errno value is not (normally) set explicitly by sia_* routines.  The errno values are those returned from the dynamic loader interface,
       from  dependent	(siad_*)  routines,  or  from malloc.  Possible errors include resource constraints (no memory) and various authentication
       failures.

FILES

       /etc/sia/matrix.conf

RELATED INFORMATION

       sia_ses_init(3), sia_chg_finger(3), matrix.conf(4)

       Security delim off

																sia_collect_trm(3)