Vue functions

This section describes Vue functions.

The Vue language supports the following list of functions:

add_range

Purpose:

Initializes the string range data type and adds strings in a slot.

Syntax:

add_range(range_t range_data, String S1, String S2, ..., String Sn);

Description:

This routine initializes the range_data as a string range data type and also adds all the strings passed as arguments to the routine in one slot. If this routine is called the first time for a range data type, strings will be added in first slot. Otherwise, strings are added in the next slot.

Parameters:

range_data

A range_t data type.

S1, S2,...

Strings to be added to the range_data parameter.

append

Purpose

Appends a value to a list.

Syntax

void append ( List listvar, long long val );

Description

The append function is the only list concatenation function available in Vue. It appends the value specified by the second parameter to the list variable specified by the first parameter. Each call to the append function adds a new value to the set of values already saved in the list variable and the size of the list variable grows. The append function also accepts another list as an argument, allowing you to join two lists.

The append function has no return value.

For more information about the list data type, see Data types in Vue. The preceding list section has an example script that uses the append function.

Parameters

atoi

Purpose

Returns the integer value of a string.

Syntax

int atoi( String str ); 

Description

The atoi function returns the integer whose value is represented by the string specified by the str parameter. It reads the string up to the first character that is not a numerical digit (0-9) and translates the scanned characters into the equivalent integer. Leading white-space characters are ignored, and an optional sign indicator can precede the digits.

The atoi function is useful in converting strings back to integers when running the sprobevue shell script that wraps double-quotes around all arguments. The following script is an example that captures a process forking faster than expected.

/* File: ffork.e 
 *
 * Usage: sprobevue ffork.e processname delta
 *
 *	Traces whenever a specified process is forking faster than
 *	the "delta" value passed. Specify a process name and the time
 *	in milliseconds as parameters.
 */

/* Ignore other parameters to execve */
int execve(char *path);

@@BEGIN
{
	int done;
	int pid;

	pname = $1;		/* name of process we are monitoring */

	/* 
	 * Since sprobevue is used, need to extract the integer value
	 * from the string (double quotes around the delta).
	 */
	delta = atoi($2);	/* minimum delta in millisecs between forks */
	printf("pname = %s, delta = %d\n", pname, delta);
}

@@syscall:*:execve:entry
	when (done == 0)
{
	__auto String exec[128];
	__thread int myproc;

	/* Find process being 'exec'ed */
	exec = get_userstring(__arg1, 128);

	/* Got it. Set a thread-local and reset 'done' so that we 
	 * avoid entering this probe from now on.
	 */
	if (exec == pname) {
		pid = __pid;
		myproc = 1;
		done = 1;
		printf("Process name = %s, pid = %d\n", __pname, pid);
	}
}

@@syscall:*:fork:entry
	when (thread:myproc == 1)
{
	/* old_ts is initialized to zero */
	probev_timestamp_t old_ts, new_ts;
	unsigned long long interval;

	/* Get current time stamp */
	new_ts = timestamp();

	/* Find time from last fork */
	if (old_ts != 0) {
		interval = diff_time(old_ts, new_ts, MILLISECONDS);

		/* if below the specified limit, trace that */
		if (interval < delta)
			printf("%s (%ld) forking too fast (%d milliseconds)\n",
					pname, __pid, interval);
	}

	/* Save current fork timestamp */
	old_ts = new_ts;
}

@@syscall:*:exit:entry
	when (__pid == pid)
{
	/* Catch process exit and terminate ourselves */
	printf("Process '%s' exited.\n", pname);
	exit();
}

Parameter

avg

Purpose

Returns the average of all the elements in a list.

Syntax

long long avg ( List listvar );

Description

The avg function returns the average of all the elements that have been appended to the list variable specified by the listvar parameter.

Parameter

commit_tentative, discard_tentative

Purpose

Commits or discards the data in a tentative trace buffer.

Syntax

void commit_tentative( String bufID );
void discard_tentative( String bufID );

Description

The commit_tentative function commits the trace data associated with the tentative trace buffer identified by the bufID parameter. This saves the data and makes it available to the trace consumer.

The discard_tentative function discards all the data in the tentative trace buffer indicated by the bufID parameter. This frees up the space in the trace buffers occupied by the tentative trace data.

When tentative trace data is being saved along with regular trace data, erstwhile tentative, but later committed trace data and regular trace data will be made available to the trace consumer in timestamp order. Thus, it is a good idea to commit or discard tentative data at the earliest opportunity to free up the trace buffers.

All tentative trace data that has not been committed is discarded when the ProbeVue session ends.

Tentative tracing describes tentative tracing in more detail and includes an example Vue script that uses tentative tracing.

Parameter

convert_ip4_addr

Purpose

Converts the IPV4 address (data) into ProbeVue IP address data-type format.

Syntax

ip_addr_t convert_ip4_addr (unsigned int ipv4_data);

Description

The convert_ip4_addr function converts the IPv4 address in the in_addr structure defined in the /usr/include/netinet/in.h file to ProbeVue IP address data-type ip_addr_t. This function returns the converted ip_addr_t value.

Parameters

ipv4_data

Specifies the ipv4 address data that needs to be converted into the ip_addr_t format.

convert_ip6_addr

Purpose

Converts the IPv6 address (data) into ProbeVue IP address data-type format.

Syntax

ip_addr_t convert_ip6_addr (int *ipv6_data);

Description

The convert_ip6_addr function converts the IPv6 address in the in6_addr structure defined in the /usr/include/netinet/in.h file to ProbeVue IP address data-type of type ip_addr_t. This function returns the converted ip_addr_t value.

Parameters

ipv6_data

Specifies the ipv6 address data that needs to be converted into the ip_addr_t format.

/* Declare the Function prototype */
int sendto(int s,  char * uap_buf,   int len,  int flags,  char * uap_to,  int tolen);

typedef unsigned int in_addr_t;

/* Structure Declarations */

/* Declare the in_addr structure */
struct in_addr {
        in_addr_t        s_addr;
};

/* Declare the sockaddr_in structure */
struct sockaddr_in {
        unsigned char           sin_len;
        unsigned char           sin_family;
        unsigned short          sin_port;
        struct in_addr          sin_addr;
        unsigned char           sin_zero[8];
};
/* Declare the in6_addr structure */
struct in6_addr {
        union {
                int s6_addr32[4];
                unsigned short s6_addr16[8];
                unsigned char  s6_addr8[16];
        } s6_addr;
};
/* Declare the sockaddr_in6 structure */
struct sockaddr_in6 {
        unsigned char          sin6_len;
        unsigned char          sin6_family;
        unsigned short         sin6_port;
        unsigned int           sin6_flowinfo;
        struct   in6_addr      sin6_addr;
        unsigned int           sin6_scope_id;  /* set of interfaces for a scope */
};


/* Print the information about to whom it is sending data */
@@syscall:*:sendto:entry
{
        struct sockaddr_in6 in6;
        struct sockaddr_in in4;
        ip_addr_t ip;

                /* Copy the arg5 data into sockaddr_storage variable */
                /* using copy_userdata( ) Vue function */
        copy_userdata(__arg5, in4);

       /*
        * Verify  whether the destination address is IPv4 or IPv6 and based on that call the
        * corresponding IPv4 or IPV6 conversion routine.
        */
       if (in4.sin_family == AF_INET)
       {
               /* Copy the ipv4 data into sockaddr_in structure using copy_userdata routine */
                copy_userdata(__arg5, in4);

               /* Convert Ipv4 data into ip_addr_t format */
                ip = convert_ip4_addr(in4.sin_addr.s_addr);

               /* Print the destination address and hostname  using %H and %I format specifier */
               printf("It is sending the data to node %H(%I)\n",ip,ip);
        }
        else if(in4.sin_family == AF_INET6)
        {
              /* Copy the ipv6 data into sockaddr_in6 structure using copy_userdata routine */
               copy_userdata(__arg5, in6);

              /* Convert Ipv6 data into ip_addr_t format */
               ip = convert_ip6_addr(in6.sin6_addr.s6_addr.s6_addr32);

              /* Print the destination address and hostname using %H and %I format specifier */
              printf("It is sending the data to node %H(%I)\n", ip,ip);
        }
}

count

Purpose

Returns the number of elements in a list.

Syntax

long long count ( List listvar );

Description

The count function returns the number of elements that have been appended to the list variable specified by the listvar parameter.

For more information about the list data type, see Data types in Vue. The preceding list section has an example script that uses the count function.

Parameter

copy_kdata

Purpose

Copies data from kernel memory into a Vue script variable.

Syntax

void copy_kdata( <type> *kaddr,<type>svar);

Description

The copy_kdata function reads data from the kernel memory into a Vue script variable. The variable might be of any of C-89 types that are supported by Vue except for pointer types. The length that is copied is equal to the size of the variable. For example, 4 bytes are copied if the target Vue script variable is of the type int, 8 bytes are copied if it is of type long long, and 48 bytes are copied if it is an array of 12 integers or int[12].

Data in kernel space must be copied before it can be used in expressions or passed as parameters to a Vue function.

If an exception occurs while the process is running this function, for example, when a bad kernel address is passed to the function, the ProbeVue session is aborted with an error message.

Parameter

kaddr

Specifies the address of the kernel space data.

svar

Specifies the script variable in which kernel data is copied. The script variable type can be of the type kernel data.

copy_userdata

Purpose

Copies data from user memory into a Vue script variable

Syntax

void copy_userdata( <type> *uaddr,<type>svar);

Description

The copy_userdata function reads data from user memory into a Vue script variable. The variable might be of any of the C-89 types that are supported by Vue . The length that is copied is equal to the size of the variable type. For example, 4 bytes are copied if the target Vue script variable is of the type int, 8 bytes are copied if it is of type long long, and 48 bytes are copied if it is an array of 12 integers or int[12].

Data in user space must be copied in before it can be used in expressions or passed as parameters to a Vue function.

If an exception occurs while the process is running this function, as for example when a bad user address is passed to the function, the ProbeVue session is aborted with an error message.

Parameter

uaddr

Specifies the address of the user space data.

svar

Specifies the script variable in which user data is copied. The script variable type must be of the type user data.

diff_time

Purpose

Returns the difference between two timestamps.

Syntax

unsigned long long diff_time( probev_timestamp_t ts1, probev_timestamp_t ts2, intformat );

Description

The diff_time function returns the time difference between two timestamps that were recorded using the timestamp function. This function can return time difference in microseconds or milliseconds as specified by the format parameter.

The get_location_point and list sections have example scripts that use the diff_time function.

Parameter

eprintf

Purpose

Formats and prints data to the standard error.

Syntax

void eprintf ( String format[ , data, ... ]);

Description

The eprintf function is similar to printf function except that the output is sent to the standard error. The eprintf function converts, formats, and copies the data parameter values to the trace buffer under the control of the format parameter. As indicated by the syntax, a varying list of arguments can be passed as data parameters to the eprintf function. Vue supports all the conversion specifiers supported by the printf subroutine that is provided by the C library except for the %p conversion specifier.

The eprintf function cannot be used to print variables of list type. However, a variable of string type can be printed by using the %s conversion specifier. A variable of probev_timestamp_t type is printed in numerical form by using the %lld or %16llx specifier. A variable of type probev_timestamp_t is printed in the date format by using the %A or %W specifier.

Parameter

exit

Purpose

Terminates the Vue script.

Syntax

void exit();

Description

The exit function terminates the Vue script. This disables all the probes enabled in the dynamic tracing session, discards any tentative trace data, issues the actions indicated in @@END probe and flushes all the captured trace data to the trace consumer. After the trace consumer prints any output traced in the @@END probe, the tracing session is terminated and the probevue process exits.

The same effect can be obtained by typing a Ctrl-C on the terminal where the probevue command was issued if it is running as the foreground task. Alternatively, you can directly send a SIGINT to the probevue process using the kill command or the kill system call.

The list section has an example script that uses the exit function. The atoi section has an example script for how to exit at the same time as the process that you are probing terminates.

Parameter

The exit function does not take any parameters, unlike the exit subroutine that is provided by the C library.

fd_fname

Purpose

Returns the file name for a particular file descriptor.

Syntax

char * fd_fname(int fd); 

Description

This function gets the name of the file for a specific file descriptor. This returns the same value as that of the __file->fname (refer to __file built-in of I/O probe manager) for the same file.

Parameters

fd_fstype

Purpose

Returns the file system type for a particular file descriptor.

Syntax

int fd_fstype(int fd);

Description

This function gets the type of the file system that the file of the specific file descriptor belongs to. It returns the same values as that of __file->fs_type (refer to __file built-in of I/O probe manager).

Parameters

fd_ftype

Purpose

Returns the file type for a specific file descriptor.

Syntax

int fd_ftype(int fd);

Description

This function gets the file type for a specific file descriptor. It returns the same values as that of __file->f_type (refer to __file built-in of I/O probe manager).

Parameters

fd_inodeid

Purpose

Returns the inode ID for a specific file descriptor.

Syntax

unsigned long long fd_inodeid(int fd);

Description

This function returns the inode ID for the file that is related to a specific file descriptor. The inode ID is a system-wide unique unsigned long long value (it is different from the file system inode number and can change value if the system is rebooted). This value matches with the value that is returned by the fpath_inodeid() function for the same file.

Parameters

fd_mpath

Purpose

Get the mount path of the file system for a specific file descriptor.

Syntax

char * fd_mpath(int fd);

Description

This function gets mount path of the file system that the file of a specific file descriptor belongs to. It returns the same value as that of __file->mount_path (refer to __file built-in of I/O probe manager) for the same file.

Parameters

fd_path

Purpose

Returns the absolute path of the file for a specific file descriptor.

Syntax

path_t fd_path(int fd); 

Description

This function returns the absolute path of the file for a specific file descriptor. The return value is of type path_t. It returns the same value as that of __file->path (refer to __file built-in of I/O probe manager) for the same file.

Parameters

fpath_inodeid

Purpose

Returns the inode ID for a specific file path.

Syntax

unsigned long long fpath_inodeid(String file_path); 

Description

This function returns the inode ID for a specific file path. The inode ID is a system-wide unique unsigned long long value (it is different from the file system inode number and can change value if the system is restarted). If the file path does not exist, then the Vue script is rejected by the probevue command. The inode ID value remains the same as provided by the __file->inode_id in vfs probe events for the same file (refer to __file built-in of I/O probe manager).

Parameters

get_function

Purpose

Returns the name of the function that encloses the current probe. When the get_function function is called from interval, systrace, BEGIN, and END clause, the function returns an empty string.

Syntax

String get_function ( );

Description

The get_function function returns the name of the probed function, that is the function that encloses the current probe point. Generally, the name of the probed function is the probe point tuple field that precedes the location field.

The preceding get_probe section has an example script that uses the get_function function.

The get_function function returns an empty string when called from the interval probe manager.

Parameter

The get_function function does not take any parameters.

get_kstring

Purpose

Copies data from kernel memory into a String variable.

Syntax

String get_kstring( char *kaddr,int len);

Description

The get_kstring function reads data in kernel memory into a variable of type String.

Strings in kernel space must be copied in before they can be used in expressions or passed as parameters to a Vue function.

The target of the get_kstring function must always be a variable of type String. If a value of -1 is specified for the len parameter, data is copied from kernel memory until a NULL byte is read (NULL bytes are used to stop text strings in the C language). If the length of the string is larger than the declared size of the target String variable, only the string characters up to the size of the variable is copied to it. However, the string in its entirety that is until a NULL byte is read it is initially copied into the temporary string buffer area. Users of the function must be careful that the kernel address points to a NULL-terminated string to avoid temporary string buffer area overflows, which cause the ProbeVue session to be stopped.

The maximum length of the string to be read in from kernel memory can be fixed by specifying a non-negative value for the len parameter. In this case, the copy proceeds until either a NULL byte is read or the specified number of bytes are read. This feature allows long strings in kernel memory to be copied more safely as the copy is limited by the value of the len parameter and does not cause ProbeVue's internal temporary string buffer to overflow.

If an exception occurs when this function is running, as for example when a bad kernel address is passed to the function, the ProbeVue session is aborted with an error message.

Parameter

addr

Specifies the address of the kernel space data.

len

Specifies the number of bytes of the kernel data to be copied. A value of -1 indicates that the kernel data be treated as a "C" string and the copy to continue until a null byte (the '\0' character) is read. Be careful when you specify a -1 as the value of the len parameter.

get_location_point

Purpose

Returns the current probe location point.

Syntax

int get_location_point ( );

Description

The get_location_point function returns the current probe location point as an offset from the enclosing function entry point. Specifically, it will return FUNCTION_ENTRY or zero if the probe point is at the entry point of the function and FUNCTION_EXIT or -1 if it is at any exit point; else, it returns the actual address offset.

The following script shows an example of using the get_location_point function:

@@syscall:$1:read:entry, @@syscall:$1:read:exit
	{
		probev_timestamp_t ts1, ts2;
		int diff;

		if (get_location_point() == FUNCTION_ENTRY) 
			ts1 = timestamp();
		else if (get_location_point() == FUNCTION_EXIT) {
			ts2 = timestamp();
			diff = diff_time(ts1, ts2, MICROSECONDS);
			printf("Time for read system call = %d\n", diff);
		}
	}

This function is not supported when called from the interval probe manager.

Parameter

The get_location_point function does not take any parameters.

get_probe

Purpose

Returns the current probe point specification.

Syntax

String get_probe ( );

Description

The get_probe function returns the internal representation of the current probe point specification. When saved internally, the probe point does not include the initial @@ prefix or the process ID, if any.

The following script shows an example of using the get_probe function:

#cat get_probe.e 
	@@uft:312678:*:run_prog:entry
	{
		printf("function '%s' probe '%s'\n", get_function(), get_probe());
	}

	#probevue get_probe.e
	function 'run_prog' probe 'uft:*:*:run_prog:entry'

Parameter

The get_probe function does not take any parameters.

get_stktrace

Purpose

Returns current stack trace.

Syntax

stktrace_t get_stktrace(int level); 

Description

Parameter

Purpose

Syntax

Description

The get_stktrace function returns stack trace of current thread. This stack trace is either stored in a stktrace_t type variable or printed with the %t specifier in the ProbeVue built-in printf function. The level parameter indicates the number of levels up to which the stack trace is to be printed. The behavior of the get_stktrace function that is used inside the printf function is similar to the stktrace built-in function. The only difference is that by default symbol with address is printed if the thread is in a running state, otherwise only address is printed. Also, it prints the whole CPU stack by traversing all the machine states.

The following script shows an example of using the get_stktrace function:

t1 = get_stktrace(3)               // Returns the current stack trace & stores in stktrace_t 
                                   // type variable t1.
printf(“%t\n”, get_stktrace(4));   // Prints the current stack trace up to level 4.

Parameter

get_userstring

Purpose

Copies data from user memory.

Syntax

String get_userstring( char * addr, int len );

Description

The get_userstring function reads data in user memory into a variable of type String.

Data in user space must be copied in before you can use it in expressions or pass it as parameters to a Vue function. The target of the get_userstring function is generally a variable of type String. If a value of -1 is specified for the len parameter, data will be copied from user memory until a NULL byte is read (NULL bytes are used to terminate text strings in the C language). If the length of the string is larger than the declared size of the target String variable, only the string characters up to the size of the variable will be copied to it. However, the string in its entirety, that is until a NULL byte is read will initially need to be copied into the temporary string buffer area. Users of the function need to be careful that the user address points to a NULL-terminated string to avoid temporary string buffer area overflows which can cause the ProbeVue session to be aborted.

This function is only allowed in user space probes (like the uft probe type) or probes provided by the syscall probe manager. If a page fault occurs while copying the data, the copy operation is terminated and the String variable will contain only the data that was successfully copied. If an exception occurs while issuing this function, as for example when a bad user address is passed to the function, the ProbeVue session is aborted with an error message.

The following code block has an example script that uses the get_userstring function.

/* File: string2int.e
 *
 * Reads an integer passed in a pointer using get_userstring()
 *
 */
int get_file_sizep(int *fd);

@@BEGIN
{
	
	int i;
}

@@uft:$1:*:get_file_sizep:entry
{
	i = *(int *)(get_userstring(__arg1, 4));

	printf("fd = %d\n", i);
}

Parameter

list

Purpose

Creates and returns an empty list.

Syntax

List list ( );

Description

The list function is the constructor function for the list data type. It returns an empty list and auto-declares the target to be a list data type. There is no explicit way to declare a variable to be a list data type. A list variable is always created as a variable of global class.

The list function can be invoked from any clause. If you specify an existing list name when invoking the list function, the existing list is cleared.

A list variable can be used to collect values that are of integral type. Any value stored in the list is automatically promoted to a long long (or 64-bit integer) data type.

The following script shows an example of using the list function. It assumes that the sprobevue shell program, which encloses double quotes around each argument, invokes the Vue script.

/* File: list.e
 * 
 * Collect execution time for read system call statistics
 *
 * Usage: sprobevue list.e <-s|-d>
 *
 *	Pass -s for summary and -d for detailed information
 */

int read(int fd, void *buf, int n);

@@BEGIN
{
	String s[10];
	int detail;
	times = list();		/* declare and create a list */

	/* Check for parameters */
	s = $1;
	if (s == "-d") 
		detail = 1;
	else if (s == "-s")
		detail = 0;
	else {
		printf("Usage: sprobevue list.e <-s|-d>\n");
		exit();
	}
}

@@syscall:*:read:entry
{
	/*
	 * Save entry time in a thread-local to ensure that 
	 * in the read:exit probe point we can access our thread's value for 
	 * entry timestamp. If we use a global, then the variable can be
	 * overlaid by the next thread to enter read and this can give
	 * wrong values when we try to find the difference at read:exit
	 * time since we use this later value instead of the original value.
	 */

	__thread probev_timestamp_t t1;
	t1 = timestamp();
}

@@syscall:*:read:exit
	when (thread:t1 != 0)
{
	__auto t2;
	__auto long difft;

	/* Get exit time */
	t2 = timestamp();
	difft = diff_time(t1, t2, MICROSECONDS);

	/* Append read time to list */
	append(times, difft);

	/* print detail data if "-d" was passed to script */
	if (detail)
		printf("%s (%ld) read time = %d micros\n", __pname, __pid, difft);
}

@@interval:*:clock:10000
{
	/* Print statistics every 10 seconds */
	printf("Read calls so far = %d, total time = %d, max time = %d, " +
	       "min = %d, avg = %d\n",
			count(times),
			sum(times),
			max(times),
			min(times),
			avg(times));
}

Parameter

The list function does not take any parameters.

lquantize

Purpose

Quantizes associative array values logarithmically and prints the key-value pairs in a graphical format .

Syntax:

void lquantize( aso-name ,int num-of-entries, int flags)

Description:

This function displays the entries of an associative array in a graphical format based on the logarithmic value of the values of an associative array. It sorts key/value in the order specified by the user and prints the first ‘n’ number of key-value pairs. The num-of-entires and flags parameters are optional. If no options are provided the default print options will be used for displaying the associative array.

Parameters:

aso-name

The name of the associative array to be quantized

num-of-entries

Specifies to display the first 'n' key/value pairs. If 0, all the entries will be displayed. This parameter is optional.

flags

Specifies the sort-type, sort-by and list-value flags. This parameter is optional. Flags sort-type, sort-by and list-value are described under the ‘Associative Array Type’ section.

max

Purpose:

Returns the maximum of all the elements in a list.

Syntax:

long long max ( List listvar );

Description:

The max function returns the maximum of all the elements that have been appended to the list variable specified by the listvar parameter.

The preceding listvar section has an example script that uses the max function.

Parameter

min

Purpose

Returns the minimum of all the elements in a list.

Syntax

long long min ( List listvar );

Description

The min function returns the minimum of all the elements that have been appended to the list variable specified by the listvar parameter.

The preceding listvar section has an example script that uses the min function.

Parameter

listvar: Specifies a variable of type list.

print_args

Purpose

Prints current function and its argument values.

Syntax

void print_args(); 

Description

The print_args function prints the function name followed by comma separated function arguments enclosed in round brackets. The argument values are printed based on the argument type information available in the traceback table of the function. This routine is allowed in entry probes of uft/uftxlc++ and syscall/syscallx probes. This is useful in probes where the probe location is specified as a regular expression.

Parameter

The print_args function does not take any parameters.

print

Purpose

Prints the key-value pairs in an associative array

Syntax

void print ( aso-name , int num-of-entires , flagsint );

Description

This will print out all the key-value pairs in the associative array aso-name. It sorts the key/value in the order specified by the user and prints the first ’n’ number of the key-value pairs. num-of-entires and ’flag’ parameters are optional. If not provided the default print options are used for printing the associative array.

Parameter

aso-name

The name of the associative array variable to be printed.

num-of-entires

Specifies to print the first 'n' key/value pairs. If 0, all the entries will be displayed. This parameter is optional.

flags

Specifies the sort-type, sort-by and the list-value flags. This parameter is optional. Flags sort-type, sort-by and list-value are described under the ‘Associative Array Type’ section.

printf

Purpose

Formats and copies data to the trace buffer.

Syntax

void printf ( String format[ , data, ... ]);

Description

The printf function converts, formats, and copies the data parameter values to the trace buffer under the control of the format parameter. As indicated by the syntax, a varying list of arguments can be passed as data parameters to the printf function. Vue supports all the conversion specifiers supported by the printf subroutine provided by the C library except for the %p conversion specifier.

Apart from the C library's printf() specifiers, Vue language supports two more specifiers: %A and %W.

%A – prints the probev_timestamp_t 't' in the default date format. This format can be changed by using the set_date_format() function.

%W – prints the probev_timestamp_t 't', in seconds and microseconds, relative to the start of the probevue session.

%p – prints the string corresponding to the absolute file path of the specified path_t value.

%M – prints the MAC address of the specified mac_addr_t value.

%I – prints the IP address in dotted decimal format for ipv4 address and dotted hex format for IPV6 address of the specified ip_addr_t value

%H – prints the host name in string or dotted decimal or hex format of the specified ip_addr_t value.

The printf function cannot be used to print variables of type list. However, a variable of type string can be printed by using the %s conversion specifier. A variable of type probev_timestamp_t type is printed in numerical form by using the %lld or %16llx specifier. probev_timestamp_t is printed in the date format by using the %A or %W specifier.

The following script demonstrates some examples of using the printf function:

@@BEGIN
{
	String s[128];
	int i;
	float f;
	f = 2.3;

	s = "Test: %d, float = %f\n";
	i = 44;

	printf(s, i, f);

	s = "Note:";
	printf("%s Value of i (left justified) = %-12d and right-justified = %12d\n",
				s, i, i);

	printf("With a long format string that may span multiple lines, you " +
			"can use the '+' operator to concatenate the strings " +
			"in multiple lines into a single string: 0x%08x\n", i); 

	exit();
}

Parameter

format

A string that contains plain characters that are directly copied to the trace buffer without any change and one or more conversion specifiers that provide indication on how to format the data parameters. For more information about conversion specifiers, see the AIX® printf subroutine in Technical Reference: Base Operating System and Extensions, Volume 1.

data

Specifies zero or more arguments that correspond to the conversion specifiers in the format parameter.

ptree

Purpose

To print the process tree for the probed process.

Syntax

void ptree ( int depth );

Description

The ptree function prints the process tree for the probed process. This functions prints both the parent and child hierarchy. The depth passed as a parameter can help in controlling the depth of child processes that need to be printed. This function cannot be used in BEGIN or END or systrace probes. Also, this function can be used in the interval probes only if the PID is specified.

Sample output

PID              CMD

1                init
                   |
                   V
 3342460         srcmstr
                   |
                   V
 3539052         inetd
                   |
                   V
 7667750         telnetd
                   |
                   V
 6881336          ksh
                   |
                   V
 5112038          probevue
                   |
                   V
 7930038             tree    <=======
 6553782                |\--tree
 4849828                |\--tree
 6422756                    |\--tree
 3408074                        |\--tree
 5963846                        |\--tree
 7864392                      |\--tree
 7799006                         |\--tree

Parameter

quantize

Purpose:

Quantizes associative array values linearly and prints the key-value pairs in a graphical format

Syntax:

void quantize ( aso-name, int num-of-entries, int flags)

Description:

This function displays the entries of an associative array in a graphical format based on the linear value of the values of the associative array. It sorts key/value in the order that is specified by the user and prints the first ‘n’ number of key-value pairs. If no options are provided the default print option is used for displaying the associative array.

Parameters:

aso-name

The name of the associative array to be quantized.

num-of-entries

Specifies to display the first 'n' key/value pairs. If 0, all the entries will be displayed. This parameter is optional.

flags

Specifies the sort-type, sort-by and list-value flags. This parameter is optional. Flags sort-type, sort-by and list-value are described under the ‘Associative Array Type’ section.

qrange

This routine gets the slot number for ranges and adds the range data type as value type for an associative array.

Syntax:

void qrange(aso[key], range_t range_data, int value);
void qrange(aso[key], range_t range_data, String value);

Description:

The qrange routine can find the slot number for both integral and String range types. If the range type is Integral type, then the third argument type should be an integer otherwise for the String range data type, the third argument should be a String type. The qrange routine will find the slot number where the passed value falls. The count for that slot number will be increased for the range type stored in an associative array as a value.

Parameters:

aso[key]

An associative array with specified key.

range_data

A range_t data type.

value

value can be either integer or can be of String type.

round_trip_time

Purpose

Returns the smoothed round-trip time for TCP connection for a specific socket descriptor.

Syntax

int round_trip_time(int sock_fd);

Description

The round_trip_time function gets the smoothed round-trip time (srtt) for a specific socket descriptor. It provides the valid round-trip value for stream socket descriptor and returns -1 as a smooth round-trip time value for invalid or non-stream sock descriptor. This function is available only in uft and syscall probe managers.

Parameters

set_aso_print_options

Purpose

Changes the default print options for associative arrays.

Syntax

void set_aso_print_options( int num-of-entries, int flags);

Description

The set_aso_print_options() function changes the default print options for associative arrays. The print options that can be provided by the user and their initial values are listed under the ‘Associative Array type’ section. This function is allowed only in BEGIN probe.

Parameter

num-of-entries

Specifies to print the first 'n' key or value pairs. If it is 0, all the entries are displayed.

flags

Specifies the sort-type, sort-by and the list-value flags. This parameter is optional. Flags sort-type, sort-by, and list-value are described under the ‘Associative Array Type’ section.

set_range

Purpose:

Initializes the linear and power range type data.

Syntax:

void set_range(range_t range_data, LINEAR, int min, int max, int step);
void set_range(range_t range_data, POWER, 2);

Description:

There are two different variants of set_range. To initialize a range data as a linear range the flag LINEAR with min, max and step will be passed as arguments. For initialize a Power range the flag POWER with two will be passed as arguments. This routine will initialize the range type either as Linear or as Power based on arguments passed. The linear range type data will be initialized with the min, max and step value passed, while power range type data will be initialized the power value as 2.

Parameters (for Linear range type):

range_data

A range_t data type.

LINEAR

An integer consistent flag indicating that distribution of range_data is linear.

min

Indicates the lower bound of range_data.

max

Indicates the upper bound of range_data.

step

Indicates the size of the specified range of the value for each row of range_data. The type of min, max & step can be only integral (int, short, long, long, long). No other types will be allowed.

Parameters (for Power® range type):

range_data

A range_t data type.

POWER®

A integer constant flag indicating that the distribution of values is a  POWER distribution.

A constant indicating the value of power. As of now only power of two is supported.

set_date_format

Purpose

Updates the date format that is used for printing the probev_timestamp_t data type.

Syntax

void set_date_format(String s);

Description

Updates the date format.

This function supports all the conversion specifiers that are supported by the C library's s strftime() for the date format. Any specifier, which is not supported by strftime(), is invalid and default format is used.

Default format

MM:DD:YYYY hh:mm:ss TZ

MM

Month of the year as a decimal number (01 to 12).

DD

Day of the month as a decimal number (01 to 31).

YYYY

Year as a decimal number (for example, 1989).

hh

24-hour clock hour as a decimal number (00 to 23).

mm

Minutes of the hour as a decimal number (00 to 59).

ss

Seconds of the minute as a decimal number (00 to 59).

TZ

Time-zone name if one can be determined (for example, CDT).

Parameters

S – string that holds the date format.

sockfd_netinfo

Purpose

Gets the local and remote ports and IP addresses information for a specific socket descriptor.

Syntax

void sockfd_netinfo(int sock_fd,  net_info_t ninfo);

Description

The sockfd_netinfo function gets the local IP address, remote IP address, local port number, and remote port number information for input socket descriptor. This function gets the valid local and remote port numbers and IP addresses information for valid socket descriptor. It gets 0 for invalid descriptor or if the descriptor is a not of socket type.

Parameters

start_tentative, end_tentative

Purpose

Indicates the start and the end of a tentative tracing section.

Syntax

void start_tentative( String bufID );
void end_tentative( String bufID );

Description

These functions indicate the start and end of a tentative tracing section within a Vue clause. Trace data generated by trace output functions enclosed within the tentative tracing section is saved on a tentative basis until a commit_tentative or a discard_tentative function is called to commit or discard this data. The end_tentative function is optional and if it is not specified, the end of the Vue clause is implicitly assumed to indicate the end of the tentative tracing section.

The generated tentative trace data is identified by the bufID parameter, which needs to be a string constant or literal and not a variable. Tentative trace data can be collected under different IDs simultaneously which can then each be committed or discarded as a separate block . ProbeVue supports up to 16 tentative trace buffers in the same dynamic tracing session, so up to 16 different trace IDs can be used in a Vue script. A single Vue clause can contain more than one tentative tracing section with different IDs.

Parameter

stktrace

Purpose

Generates and prints a runtime stack trace.

Syntax

void stktrace ( int flags, int levels );

Description

The stktrace function prints the stack trace at the current probe point. By default, the stack trace is generated in compact form with only call chain addresses for only up to two levels. You can use the flags and the levels parameters to modify the format and contents of the stack trace. ProbeVue cannot read paged out data, so the stack trace is truncated if a page fault is encountered when accessing the stack.

The stktrace function does not return any values.

Parameter

strstr

Purpose

Return a string inside another string.

Syntax

String strstr( String s1, String s2 ); 

Description

The strstr function finds the first occurrence of the string specified by the s2 parameter in the string specified by the s1 parameter and returns a new string that contains the characters in the s1 parameter starting from this location. Neither the s1 parameter nor the s2 parameter are modified by this operation. If the sequence of characters specified by the s2 parameter does not appear even once in the s1 parameter, then this function returns an empty string.

Parameter

sum

Purpose

Returns the sum of all the elements in a list.

Syntax

long long sum ( List listvar );

Description

The sum function returns the sum of all the elements that have been appended to the list variable specified by the listvar parameter.

Parameter

timestamp

Purpose

Returns the current timestamp.

Syntax

probev_timestamp_t timestamp( );

Description

The timestamp function returns the current timestamp in the probev_timestamp_t abstract data type. Although abstract, the value has the following properties:

• It returns an equal or close value when called simultaneously from different CPUs.
• If the timestamp function is invoked twice and the second call can be architecturally guaranteed to have happened later in time, the value returned for the second call is greater than or equal to the value returned by the first call (provided the system has not been rebooted in between the calls).

There is no relationship between the values returned by the timestamp function on two different systems. Although the compiler will let you treat the returned value as a 64-bit integer, doing so can introduce compatibility problems.

typedef long long time_t;
	__kernel time_t lbolt;   	/* number of ticks since last boot     */
	__kernel time_t time;    	/* memory mapped time in secs since epoch  */

Parameter

The timestamp function does not take any parameters.

trace

Purpose

Copies raw data to the trace buffer in hexadecimal format.

Syntax

void trace ( data );

Description

The trace function takes a single parameter which must be a variable. The trace function does not accept expressions.

The trace function copies the value of the passed-in argument to the trace buffer. The argument can be of any data type and the size of the data copied to the trace buffer is based on its innate size. Thus, four bytes are copied for an integer argument, four or eight bytes for pointers (depending upon whether the execution is in 32-bit or 64-bit mode) and the size of the structure for arguments of type struct. For a variable of type String, the number of bytes copied over is the declared string length (which is not the same as the length of the string contained in the variable). A variable of type probev_timestamp_t is at least 8 bytes long.

The trace reporter displays the hexadecimal data written by the trace function in groups of four characters without any additional formatting.

Parameter