NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

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

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

LIBRARY    [Toc]    [Back]

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

PARAMETERS    [Toc]    [Back]

       The timeout parameter is the number of  seconds  that  the
       sia_collect_trm()  routine waits.  The rendition parameter
       is used to determine the style of the presentation and  is
       set  to  one  of  the  following values: Select one of the
       choices given.  Select any of the choices given.  Fill out
       the  form.   One  question  with  one answer.  Information
       only.  ERROR or  WARNING  message.   Pointer  to  a  title
       string.  A null pointer indicates no title.  The number of
       prompts in this  collection.   A  pointer  to  a  prompt_t
       prompts structure.

DESCRIPTION    [Toc]    [Back]

       The  sia_collect_trm()  routine provides parameter collection
 capability.  The SIA session  interfaces  and  change
       secure  information interfaces 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.

RETURN VALUES    [Toc]    [Back]

       The sia_collect_trm() routine returns either SIASUCCESS or
       SIAFAIL.

ERRORS    [Toc]    [Back]

       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.

EXAMPLES    [Toc]    [Back]

       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) != SIACOLSUCCESS)
         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:\n", 3, prompts); if (collecterror !=
       SIACOLSUCCESS) {      (void) fputs("Collection failed.\n",
       stderr);       return  -1;  }  for (i = 0;  i < 3;  i++) {
            if (prompts[i].result) {           (void) printf("You
       picked      %s.\n",                    prompts[i].prompt);
                 return  0;       }  }  (void)  fputs("Collection
       return error.\n", 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;

FILES    [Toc]    [Back]

       /etc/sia/matrix.conf

SEE ALSO    [Toc]    [Back]

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

       Security



                                               sia_collect_trm(3)