<refmeta>
  <refentrytitle>utracer_open</refentrytitle>
  <manvolnum>2</manvolnum>
</refmeta>

<refnamediv>
  <refname>utracer_open</refname>
  <refpurpose>establish a connection to the utracer kernel module</refpurpose>
</refnamediv>

<refsynopsisdiv>
  <funcsynopsis>
    <funcsynopsisinfo>
      #include &lt;utracer.h&gt;
    </funcsynopsisinfo>
    <funcprototype>
      <funcdef>long <function>utracer_open</function></funcdef>
      <paramdef></paramdef>
    </funcprototype>
  </funcsynopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
  <para>
    <function>utracer_open</function>() is used to establish a connection to
    the utracer kernel module.  This, if successful, will result in the
    creation of necessary control structures within the module and necessary
    entries under the directory <filename
    class='directory'>/proc/utrace</filename>.  The <filename
    class='directory'>/proc/utrace</filename> entries look to the user like
    ordinary files and could be used directly to control the actions of the
    utracer module with respect to the calling process, but this is not
    recommended.
  </para>
</refsect1>

<refsect1>
  <title>Return Value</title>
  <para>
    If successful, <function>utracer_open</function>() returns the PID of the
    calling process (i.e., the value returned by
    <function>getpid</function>()), but that value serves only as a unique
    identifier of the opened interface to the utracer kernel module and, since
    it might in the future be created in some other way, should not be assumed
    to be a valid PID.
  </para>
  <para>
    If the call is not successful, it will return a -1 and set
    <varname>errno</varname>.  The value of <varname>errno</varname> will be
    either of those appropriate to the <function>open</function>() system call
    (q.v.) or one of the following (some of which are unique to the utracer
    module).
  </para>
</refsect1>

<refsect1>
  <title>Errors</title>
  <variablelist>
      
    <varlistentry>
      <term><constant>ENOMEM</constant></term>
      <listitem>
	<para>
	  Insufficient memory was available to allocate necessary control
	  structures within the module.
	</para>
      </listitem>
    </varlistentry>
      
    <varlistentry>
      <term><constant>ESRCH</constant></term>
      <listitem>
	<para>
	  The calling process no longer exists.
	</para>
      </listitem>
    </varlistentry>
      
    <varlistentry>
      <term><constant>EALREADY</constant></term>
      <listitem>
	<para>
	  An internsl utrace error.
	</para>
      </listitem>
    </varlistentry>
      
    <varlistentry>
      <term><constant>UTRACER_ETRACING</constant></term>
      <listitem>
	<para>
	  The calling process has already opened a connection to the utracer
	  kernel module.
	</para>
      </listitem>
    </varlistentry>
      
    <varlistentry>
      <term><constant>UTRACER_EENGINE</constant></term>
      <listitem>
	<para>
	  An attempt to attach to the calling process via utrace failed.  (The
	  calling process is attached primarily to detect its unexpected death
	  so any resources allocated by the utracer module can be cleaned up.)
	</para>
      </listitem>
    </varlistentry>
  </variablelist>
</refsect1>

&xref;

