---
name: "usctest"
section: "3"
platform: "linux"
package: "ltp-dev"
version: "20091231+dfsg-1"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/usctest"
---

# usctest(3)

macros and libraries for common functions in system call tests

## 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)](/parse_opts/3.md)** 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)](/parse_opts/3.md)** 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)](/parse_opts/3.md)**).  All STD\_\* global variables used are set by the **[parse\_opts(3)](/parse_opts/3.md)** 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)](/parse_opts/3.md).

## 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.