Provided by: ltp-dev_20091231+dfsg-1ubuntu2_amd64 bug

NAME

       usctest -  macros and libraries for common functions in system call tests

SYNOPSIS

       Routines:
        char *parse_opts(...)

       Macros
        TEST_PAUSE
        TEST_PAUSEF(hand)
        TEST(syscall)
        TEST_VOID(syscall)
        TEST_CLEANUP
        TEST_LOOPING(counter)
        TEST_ERROR_LOG(errno)
        TEST_EXP_ENOS(array)

       Global Variable(s) (see parse_opts(3) for complete list):
        int TEST_RETURN;    /* set by the TEST macro to the return code from syscall */
        int  TEST_ERRNO;     /* set by the TEST macro to the value of errno after syscall returns
        */
        /* All STD_* variables referenced below are set by the parse_opts(3) routine. */

DESCRIPTION

       The TEST_PAUSE macro checks if the global variable STD_PAUSE is set.  If so, it pauses for
       a  SIGUSR1  before continuing execution.  The signal handler used does nothing.  After the
       signal is processed, the previous action is replaced for SIGUSR1.

       The TEST_PAUSEF(hand) macro checks if the global variable STD_PAUSE is  set.   If  so,  it
       pauses  for  a SIGUSR1 before continuing execution.  The hand argument is a function to be
       used to handle the SIGUSR1 signal when it is received.  After the signal is processed, the
       previous action is replaced for SIGUSR1.

       The  TEST(syscall)  macro  executes  (syscall)  and times its execution.  It saves the max
       time, min time, accumulated time, and execution count, if STD_TIMING_ON is set.

       The TEST_VOID(syscall) macro works exactly the same as the TEST()  macro  except  that  it
       does  NOT set the global TEST_RETURN.  It is intended to be used with system calls that do
       not have a return value.

       The TEST_CLEANUP macro prints timing statistics, accumulated through the  TEST  macro,  if
       STD_TIMING_ON   is   set.   Also,  prints  the  errno  return  counts  as  logged  by  the
       TEST_ERROR_LOG macro, if STD_ERR_LOG is set.  TEST_CLEANUP uses tst_resm(3) to output this
       information.

       The   TEST_LOOPING(counter)   macro   checks   counter   against   the   global   variable
       STD_LOOP_COUNTER.  If counter is less than STD_LOOP_COUNTER or  STD_INFINITE  is  set,  it
       returns TRUE.

       The  TEST_ERROR_LOG  macro records the return of errno as unexpected, unless the option to
       turn it off is specified on the command line.

       The TEST_EXP_ENOS(array) macro sets an internal flag for each errno in  array,  indicating
       that  the  errno  is expected at some point in the test.  This is used by the TEST_CLEANUP
       macro to determine which errnos are expected when printing the log.   The  array  must  be
       zero terminated.

       The  parse_opts  routine  parses  the  command line (see parse_opts(3)).  All STD_* global
       variables used are set by the parse_opts(3) routine.

EXAMPLES

       Below is a partial template of a system call test using these routines, macros, and global
       variables.   A  complete template may be found in the CUTS/sun/skel directory, in the file
       usctest.c.

       void
       setup()
       {
            TEST_PAUSE;    /* Pause  if option specified */
       }

       void
       cleanup()
       {
            TEST_CLEANUP;
       }

       int main(ac, av)
       {
            int lc;        /* loop counter */
            char *msg;     /* return from parse_opts */

            int exp_enos[]={EACCESS, 0};  /* expected errnos */

            TEST_EXP_ENOS(exp_enos); /* set expected errnos */

            setup();  /* execute setup */

            /* parse options */
            msg=parse_opts(ac, av, (option_t *)NULL);

            /* Check parse_opts return */

            for (lc=0; TEST_LOOPING(lc); lc++) {
                 TEST(open("file", O_RDWR))

                 if ( TEST_RETURN == -1) {
                      TEST_ERROR_LOG(TEST_ERRNO)
                      /* BREAK test case, or whatever... */
                 }

            }

            cleanup();

            return 0;
       }

SEE ALSO

       parse_opts(3).

RETURN VALUES

       The TEST_LOOPING macro evaluates to TRUE (1) or FALSE (0), and  is  intended  for  use  in
       while  or  for  loops.   The TEST macro places the return value from syscall in the global
       variable TEST_RETURN and the errno in the global  variable  TEST_ERRNO.   The  TEST_PAUSE,
       TEST_PAUSEF, TEST_CLEANUP, TEST_ERROR_LOG, and TEST_EXP_ENOS macros do not have any return
       values.