Go to main content

man pages section 3: Extended Library Functions, Volume 2

Exit Print View

Updated: Thursday, June 13, 2019
 
 

dtrace_program_header (3DTRACE)

Name

dtrace_program_link, dtrace_program_header - DTrace USDT probe support

Synopsis

     cc [ flag... ] file... -ldtrace [ library... ]
     #include <dtrace.h>

     int dtrace_program_header(dtrace_hdl_t *dtp, FILE *out,
	const char *fname)

     int dtrace_program_link(dtrace_hdl_t *dtp, dtrace_prog_t *pgp,
	uint_t dflags, const char *file, int objc, char *const objv[])

Description

The dtrace_program_header() and dtrace_program_link() functions support the creation of user-defined providers (USDT providers) for applications.

dtrace_program_header()

The dtrace_program_header() function performs the following actions:

  1. The dtrace_program_header() function generates a C header file with the name, fname, containing the macro definitions for a USDT provider. This header file is written to the out argument.

  2. The dtrace_program_header() function writes the header file to the out argument.

  3. The dtrace_program_header() function calls the dtrace_program_strcompile(3DTRACE) or dtrace_program_fcompile(3DTRACE) function to compile the D language provider definition.

  4. The information about the USDT provider is stored in the DTrace handle, dtp

dtrace_program_link()

The dtrace_program_link() function performs the following actions:

  1. Given a compiled USDT provider definition in the pgp argument, the function processes the object files specified in the objv argument to create the probe points for that provider. The count of the files is maintained in the objc argument.

  2. The function then creates an ELF object file containing the provider definition as an encapsulated DTrace Object Format (DOF) object. The name of the file is contained in the file argument.


Note -  If pgp is NULL, the function will run the linker on the object files specified in objv, and then unlink(2) those object files. In this case, file is the name of the output file.

Return Values

Upon successful completion, these functions return 0. Otherwise the functions return -1 and set the DTrace error number to indicate the reason for the failure. See the dtrace_errno(3DTRACE) man page for more information.

Errors

The dtrace_program_header() function will fail if:

EINVAL

The dtp or out parameter is NULL.

The dtrace_program_link() function will fail if:

EINVAL

Either the dtp or file parameter is NULL, or the objv parameter is NULL even though the objc parameter is greater than 0.

EDT_COMPILER

The linker encountered an error.

Examples

Example 1 Using the dtrace_program_header() Function

Given the following USDT provider file, probes.d:

      provider foo {
		probe bar(int);
		probe baz(int);
	};
	
	#pragma D attributes Evolving/Evolving/Common provider foo provider
	#pragma D attributes Private/Private/Common provider foo module
	#pragma D attributes Private/Private/Common provider foo function
	#pragma D attributes Evolving/Evolving/Common provider foo name
	#pragma D attributes Evolving/Evolving/Common provider foo args

The following program would generate the header file, probes.h:

      #include <dtrace.h>
      #include <stdio.h>
      #include <stdlib.h>
	
	static dtrace_hdl_t *g_dtp;
	
	static void
	fatal(const char *fmt, ...)
	{
		va_list ap;
	
		va_start(ap, fmt);
		(void) vfprintf(stderr, fmt, ap);
	
		if (fmt[strlen(fmt) - 1] != '\n')
			(void) fprintf(stderr, ": %s\n",
			    dtrace_errmsg(g_dtp, dtrace_errno(g_dtp)));
	
		exit(EXIT_FAILURE);
	}
	
	int
	main()
	{
		dtrace_prog_t *prog;
		int err;
		FILE *fp, *ofp;
		char *provider_desc = "probes.d";
		char *header = "probes.h";
	
		if ((fp = fopen(provider_desc, "r")) == NULL)
			fatal("cannot open %s", provider_desc);
	
		if ((ofp = fopen(header, "w")) == NULL)
			fatal("cannot open %s", header);
	
		if ((g_dtp = dtrace_open(DTRACE_VERSION, DTRACE_O_NODEV,
		    &err)) == NULL)
			fatal("cannot open dtrace library: %s\n",
			    dtrace_errmsg(NULL, err));
	
		if ((prog = dtrace_program_fcompile(g_dtp, fp,
		    DTRACE_C_ZDEFS, 0, NULL)) == NULL)
			fatal("invalid program");
	
		if (dtrace_program_header(g_dtp, ofp, header) < 0)
			fatal("dtrace_program_header()");
	
		dtrace_close(g_dtp);
		fclose(fp);
		fclose(ofp);
	
		return (0);
	}
Example 2 Using the dtrace_program_link() Function

Given the following program as foo.c, compiled into object file foo.o ("cc -c -m64 foo.c"):

      #include "probes.h"
	
	void *
	func(int size)
	{
		if (FOO_BAR_ENABLED()) {
			if (size == 5) {
				FOO_BAR(size);
			}
		}
		if (FOO_BAZ_ENABLED()) {
			if (size != 5) {
				FOO_BAZ(size);
			}
		}
	
		return (NULL);
	}

The following program would create the probe points in the object file, foo.o and generate the DOF object file, probes.o from the USDT provider file, probes.d:

      #include <dtrace.h>
      #include <stdio.h>
      #include <stdlib.h>
	
	static dtrace_hdl_t *g_dtp;
	
	static void
	fatal(const char *fmt, ...)
	{
		va_list ap;
	
		va_start(ap, fmt);
		(void) vfprintf(stderr, fmt, ap);
	
		if (fmt[strlen(fmt) - 1] != '\n')
			(void) fprintf(stderr, ": %s\n",
			    dtrace_errmsg(g_dtp, dtrace_errno(g_dtp)));
	
		exit(EXIT_FAILURE);
	}
	
	int
	main(int argc, char **argv)
	{
		dtrace_prog_t *prog;
		int err;
		FILE *fp;
		char *provider_desc = "probes.d";
		char *provider_obj = "probes.o";
		char *objv[] = {"foo.o"};
	
		if ((fp = fopen(provider_desc, "r")) == NULL)
			fatal("cannot open %s", provider_desc);
	
		if ((g_dtp = dtrace_open(DTRACE_VERSION,
		    DTRACE_O_NODEV | DTRACE_O_LP64, &err)) == NULL)
			fatal("cannot open dtrace library: %s\n",
			    dtrace_errmsg(NULL, err));
	
		if ((prog = dtrace_program_fcompile(g_dtp, fp,
		    DTRACE_C_ZDEFS, 0, NULL)) == NULL)
			fatal("invalid program");
	
		if (dtrace_program_link(g_dtp, prog, 0, provider_obj, 1,
		    objv) < 0)
			fatal("dtrace_program_link()");
	
		dtrace_close(g_dtp);
		fclose(fp);
	
		return (0);
	}

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Architecture
All
Availability
system/dtrace
Interface Stability
Committed
MT-Level
Safe

See Also

libdtrace(3LIB), dtrace_errno(3DTRACE), dtrace_program_fcompile(3DTRACE)