<refmeta>
  <refentrytitle>utracer_set_syscall</refentrytitle>
  <manvolnum>2</manvolnum>
</refmeta>

<refnamediv>
  <refname>utracer_set_syscall</refname>
  <refpurpose>specify which syscalls to report</refpurpose> 
</refnamediv>

<refsynopsisdiv>
  <funcsynopsis>
    <funcsynopsisinfo>
      #include &lt;utracer.h&gt;
    </funcsynopsisinfo>
    <funcprototype>
      <funcdef>int <function>utracer_set_syscall</function></funcdef>
      <paramdef>long <parameter>client_pid</parameter></paramdef>
      <paramdef>short <parameter>which</parameter></paramdef>
      <paramdef>short <parameter>cmd</parameter></paramdef>
      <paramdef>long <parameter>traced_pid</parameter></paramdef>
      <paramdef>long <parameter>syscall</parameter></paramdef>
    </funcprototype>
  </funcsynopsis>
</refsynopsisdiv>

<refsect1>
  <title>Description</title>
  <para>
    <function>utracer_set_syscall</function>() is used to specify which
    syscalls should be reported to the calling process.  The parameter
    <parameter>client_pid</parameter> must be the value returned by a
    successful <function>utracer_open</function>() call and serves to identify
    the calling process to the module.  The <parameter>traced_pid</parameter>
    parameter specifies the attached process to which this operation applies,
    that process having been previously attached by a
    <function>utracer_attach</function>() call, q.v. (Utracer supports
    concurrent tracing of multiple attached processes by multiple clients.)
    The <parameter>which</parameter> parameter specifies whether the syscall
    should be reported on entry or exit and should be either of the enum
    constants <constant>SYSCALL_CMD_ENTRY</constant> or
    <constant>SYSCALL_CMD_EXIT</constant>.
  </para>
  <para>
    The <parameter>cmd</parameter>
    parameter specifies whether reporting of the specified syscall should be
    one of the following enum constants:
    <variablelist>

      <varlistentry>
	<term><constant>SYSCALL_CMD_ENABLE</constant></term>
	<listitem>
	  <para>
	    This operation globally enables reporting of either syscall entries
	    or syscall exits as specified by the <parameter>which</parameter>
	    parameter.  Unless this operation is issued, no syscall reports
	    will be generated regardless of any other calls to
	    <function>utracer_set_syscall</function>().  The
	    <parameter>syscall</parameter> parameter is ignored.
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term><constant>SYSCALL_CMD_DISABLE</constant></term>
	<listitem>
	  <para>
	    This operation is the reverse of
	    <constant>SYSCALL_CMD_ENABLE</constant> and may be used to
	    permanently or temporarily disable reporting of previously
	    specified syscalls--this operation may be reversed by a
	    <constant>SYSCALL_CMD_ENABLE</constant> without affecting the set
	    of syscalls to be reported (see
	    <constant>SYSCALL_CMD_ADD</constant> below).  Note that this
	    operation is specific to either the set of syscall entries or
	    syscall exits, as specified by the <parameter>which</parameter>.
	    The <parameter>syscall</parameter> parameter is ignored.
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term><constant>SYSCALL_CMD_ADD</constant></term>
	<listitem>
	  <para>
	    This operation specifies, with the <parameter>syscall</parameter>
	    parameter, which syscall is to be reported.  Whether the the report
	    is generated on entry to or exit from the syscall is specified by
	    the <parameter>which</parameter> parameter.  This operation is
	    cumulative--reports for multiple syscall types may be
	    simultaneously enabled by repeated calls to
	    <function>utracer_set_syscall</function>() with
	    <constant>SYSCALL_CMD_ADD</constant> arguments and different values
	    of the <parameter>syscall</parameter> parameter.  Reporting of any
	    given syscall may be repeatedly enabled without error, but has no
	    effect.  If the value of the <parameter>syscall</parameter>
	    parameter equals <constant>SYSCALL_ALL</constant>, reports will be
	    generated for all architecturally valid syscalls.
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term><constant>SYSCALL_CMD_REMOVE</constant></term>
	<listitem>
	  <para>
	    This operation disables reporting of syscalls as specified by the
	    <parameter>syscall</parameter> and <parameter>which</parameter>
	    parameters.  Reporting of any given syscall may be repeatedly
	    disabled without error, but has no effect.  If the value of the
	    <parameter>syscall</parameter> parameter equals
	    <constant>SYSCALL_ALL</constant>, reports will be supressed for all
	    architecturally valid syscalls.
	  </para>
	</listitem>
      </varlistentry>
      
    </variablelist>
  </para>

  <para>
    The effects of <function>utracer_set_syscall</function>() are cumulative,
    i.e., through a sequence of calls to it reports may be requested for any
    number of syscall types and on any combination of entry and/or exit.  For
    example,
    <example>
      <title></title>
      <programlisting>
	utracer_set_syscall (clientpid, SYSCALL_CMD_ENTRY,
	    SYSCALL_CMD_ENABLE, traced_pid, SYS_open);
	utracer_set_syscall (clientpid, SYSCALL_CMD_EXIT,
	    SYSCALL_CMD_ENABLE, traced_pid, SYS_close);
      </programlisting>
    </example>
    would result in reports on the entry into an <quote>open</quote> syscall
    and the exit from a <quote>close</quote> syscall.  Initially, no reports
    are enabled.
  </para>

  <para>
    Once syscall reporting is enabled, the occurrence of any of the specified
    syscalls will result in a report being returned to the response application
    thread via the <function>utracer_read</function>() function.  ( See
    <citerefentry><refentrytitle>utracer_read</refentrytitle>
    <manvolnum>2</manvolnum></citerefentry>.)
    <function>utracer_read</function>() returns (by passed pointers) a union of
    structs describing the event being reported upon and, optionally, ancillary
    data.  The first element of that union is always of type long and is used
    to determine which of the structs that constitute the union should be
    used.  In the case of syscall, the value of that long will be either
    <constant>IF_RESP_SYSCALL_ENTRY_DATA</constant> or
    <constant>IF_RESP_SYSCALL_EXIT_DATA</constant>, and the applicable struct
    is:
      <programlisting>
	<![CDATA[
typedef struct {
  long type;
  long utraced_pid;
  long data_length;
} syscall_resp_s;
      
]]>
</programlisting>
    of which only the <structfield>utraced_pid</structfield> field, indicating
    the PID for which the syscall occurred, is of interest.
  </para>

  <para>
    The ancillary data returned for a syscall is a copy of the kernel
    <structname>pt_regs</structname> struct.  The elements of this struct are
    architecture-dependent and utracer makes no attempt to do so, leaving that
    to the application. As after every invocation of
    <function>utracer_read</function>(), if the <parameter>extra</parameter>
    parameter pointing to the ancillary data is non-null, it points to memory
    allocated by <function>malloc</function>() and should be freed using the
    <function>free</function>() function.
  </para>
</refsect1>

<refsect1>
  <title>Return Value</title>
  <para>
    If successful, <function>utracer_set_syscall</function>() returns a zero;
    otherwise a -1 is returned and <varname>errno</varname> is set.
  </para>
</refsect1>

<refsect1>
  <title>Errors</title>
  <variablelist>
      
    <varlistentry>
      <term><constant>UTRACER_ETRACING</constant></term>
      <listitem>
	<para>
	  The process specified by the <parameter>client_pid</parameter>
	  parameter either doesn't exist or isn't registered as a utracer
	  client. 
	</para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><constant>ESRCH</constant></term>
      <listitem>
	<para>
	  The process specified by the <parameter>traced_pid</parameter>
	  parameter does not exist.
	</para>
      </listitem>
    </varlistentry>
      
    <varlistentry>
      <term><constant>UTRACER_ETRACED</constant></term>
      <listitem>
	<para>
	  The process specified by the <parameter>traced_pid</parameter>
	  parameter has not been registered (via
	  <function>utracer_attach</function>()) with utracer.
	</para>
      </listitem>
    </varlistentry>
      
    <varlistentry>
      <term>UTRACER_EENGINE</term>
      <listitem>
	<para>
	  The process specified by the <parameter>traced_pid</parameter>
	  parameter is not utrace-attached.
	</para>
      </listitem>
    </varlistentry>
      
    <varlistentry>
      <term>UTRACER_ESYSRANGE</term>
      <listitem>
	<para>
	  The syscall number specified by the <parameter>syscall</parameter>
	  parameter is not equal to <constant>SYSCALL_ALL</constant> and is out
	  of the range of valid syscall range of the current architecture.
	</para>
      </listitem>
    </varlistentry>
  </variablelist>

  <para>
    In addition to the foregoing, errors associated with
    <function>ioctl</function>() may be reported.
  </para>
</refsect1>

&xref;
