ruby-dtrace 0.0.2 → 0.0.3

data/ext/dtrace_aggdata.c

@@ -15,7 +15,8 @@ VALUE dtraceaggdata_init(VALUE self)
   return self;
 }
 
-
+/* Returns the value of this aggregate, be it the aggregation value,
+   or a member of an aggregation key tuple. */
 VALUE dtraceaggdata_value(VALUE self)
 {
   dtrace_bufdata_t *bufdata;
@@ -118,6 +119,8 @@ VALUE dtraceaggdata_value(VALUE self)
   return v;
 }
 
+/* Return the type of this DtraceAggData: tuple, value or last. Used
+   to form tuples and values into DtraceAggregate objects. */
 VALUE dtraceaggdata_aggtype(VALUE self)
 {
   dtrace_bufdata_t *bufdata;

data/ext/dtrace_api.c

@@ -12,6 +12,7 @@ VALUE cDtraceAggData;
 VALUE cDtraceRecDesc;
 VALUE cDtraceProbeData;
 VALUE cDtraceBufData;
+VALUE cDtraceProcess;
 
 VALUE eDtraceException;
 
@@ -24,17 +25,19 @@ void Init_dtrace_api() {
   rb_define_method(cDtrace, "stop",            dtrace_hdl_stop,            0); // in dtrace_hdl.c
   rb_define_method(cDtrace, "status",          dtrace_hdl_status,          0); // in dtrace_hdl.c
   rb_define_method(cDtrace, "go",              dtrace_hdl_go,              0); // in dtrace_hdl.c
-  rb_define_method(cDtrace, "each_aggregate",  dtrace_hdl_each_aggregate,  0); // in dtrace_hdl.c
-  rb_define_method(cDtrace, "aggregate_print", dtrace_hdl_aggregate_print, 0); // in dtrace_hdl.c
-  rb_define_method(cDtrace, "aggregate_snap",  dtrace_hdl_aggregate_snap,  0); // in dtrace_hdl.c
-  rb_define_method(cDtrace, "aggregate_clear", dtrace_hdl_aggregate_clear, 0); // in dtrace_hdl.c
   rb_define_method(cDtrace, "error",           dtrace_hdl_error,           0); // in dtrace_hdl.c
   rb_define_method(cDtrace, "setopt",          dtrace_hdl_setopt,          2); // in dtrace_hdl.c
   rb_define_method(cDtrace, "sleep",           dtrace_hdl_sleep,           0); // in dtrace_hdl.c
-  rb_define_method(cDtrace, "work",            dtrace_hdl_work,            2); // in dtrace_hdl.c
+  rb_define_method(cDtrace, "work",            dtrace_hdl_work,           -1); // in dtrace_hdl.c
   rb_define_method(cDtrace, "buf_consumer",    dtrace_hdl_buf_consumer,    1); // in dtrace_hdl.c
+  rb_define_method(cDtrace, "createprocess",   dtrace_hdl_createprocess,   1); // in dtrace_hdl.c
+  rb_define_method(cDtrace, "grabprocess",     dtrace_hdl_grabprocess,     1); // in dtrace_hdl.c
   rb_define_alloc_func(cDtrace, dtrace_hdl_alloc);
 
+  cDtraceProcess = rb_define_class("DtraceProcess", rb_cObject);
+  rb_define_method(cDtraceProcess, "initialize",    dtrace_process_init,     0); // in dtrace_process.c
+  rb_define_method(cDtraceProcess, "continue",      dtrace_process_continue, 0); // in dtrace_process.c
+
   cDtraceProbe = rb_define_class("DtraceProbe", rb_cObject);
   rb_define_method(cDtraceProbe, "initialize", dtraceprobe_init,     0); // in dtrace_probe.c
   rb_define_method(cDtraceProbe, "probe_id",   dtraceprobe_probe_id, 0); // in dtrace_probe.c
@@ -45,11 +48,18 @@ void Init_dtrace_api() {
 
   cDtraceProbeData = rb_define_class("DtraceProbeData", rb_cObject);
   rb_define_method(cDtraceProbeData, "initialize",  dtraceprobedata_init,        0); // in dtrace_probedata.c
-  rb_define_method(cDtraceProbeData, "probedesc",   dtraceprobedata_probedesc,   0); // in dtrace_probedata.c
+  rb_define_method(cDtraceProbeData, "epid",        dtraceprobedata_epid,        0); // in dtrace_probedata.c
+  rb_define_method(cDtraceProbeData, "probe",       dtraceprobedata_probe,       0); // in dtrace_probedata.c
+  rb_define_method(cDtraceProbeData, "cpu",         dtraceprobedata_cpu,         0); // in dtrace_probedata.c
+  rb_define_method(cDtraceProbeData, "indent",      dtraceprobedata_indent,      0); // in dtrace_probedata.c
+  rb_define_method(cDtraceProbeData, "prefix",      dtraceprobedata_prefix,      0); // in dtrace_probedata.c
+  rb_define_method(cDtraceProbeData, "flow",        dtraceprobedata_flow,        0); // in dtrace_probedata.c
   rb_define_method(cDtraceProbeData, "each_record", dtraceprobedata_each_record, 0); // in dtrace_probedata.c
 
   cDtraceBufData = rb_define_class("DtraceBufData", rb_cObject);
   rb_define_method(cDtraceBufData, "initialize",  dtracebufdata_init,   0); // in dtrace_bufdata.c
+  rb_define_method(cDtraceBufData, "epid",        dtracebufdata_epid,   0); // in dtrace_bufdata.c
+  rb_define_method(cDtraceBufData, "probe",       dtracebufdata_probe,  0); // in dtrace_bufdata.c
   rb_define_method(cDtraceBufData, "record",      dtracebufdata_record, 0); // in dtrace_bufdata.c
 
   cDtraceProgram = rb_define_class("DtraceProgram", rb_cObject);
@@ -70,7 +80,8 @@ void Init_dtrace_api() {
   rb_define_method(cDtraceAggData, "aggtype",            dtraceaggdata_aggtype, 0); // in dtrace_aggdata.c
 
   cDtraceRecDesc = rb_define_class("DtraceRecDesc", rb_cObject);
-  rb_define_method(cDtraceRecDesc, "initialize",         dtracerecdesc_init, 0); // in dtrace_recdesc.c 
+  rb_define_method(cDtraceRecDesc, "initialize",         dtracerecdesc_init,   0); // in dtrace_recdesc.c 
+  rb_define_method(cDtraceRecDesc, "action",             dtracerecdesc_action, 0); // in dtrace_recdesc.c 
 
   eDtraceException = rb_define_class("DtraceException", rb_eStandardError);
 }

data/ext/dtrace_api.h

@@ -8,31 +8,62 @@
 #include "/usr/include/dtrace.h"
 #include "ruby.h"
 
+/* Used to pass three Ruby VALUEs as the void *arg of dtrace_work() to
+   its callbacks: the dtrace handle, a Proc for the probe callback,
+   and a Proc for the recdesc callback. */
+typedef struct dtrace_work_handlers {
+  VALUE handle;
+  VALUE probe;
+  VALUE rec;
+} dtrace_work_handlers_t;
+
+/* Used to keep a reference to a struct ps_prochandle and a reference
+   to the DTrace handle in a DtraceProcess object: we need to be able 
+   to call dtrace_proc_release() when the DtraceProcess goes away, and
+   that requires the DTrace handle. */
+typedef struct dtrace_process {
+  dtrace_hdl_t *handle;
+  struct ps_prochandle *proc;
+} dtrace_process_t;
+
+/* Handle missing RARRAY_LEN etc */
+#ifdef RARRAY_LEN
+static inline long   rb_str_len(VALUE s) {return RSTRING_LEN(s);}
+static inline char  *rb_str_ptr(VALUE s) {return RSTRING_PTR(s);}
+static inline long   rb_ary_len(VALUE s) {return  RARRAY_LEN(s);}
+static inline VALUE *rb_ary_ptr(VALUE s) {return  RARRAY_PTR(s);}
+#else
+static inline long   rb_str_len(VALUE s) {return RSTRING(s)->len;}
+static inline char  *rb_str_ptr(VALUE s) {return RSTRING(s)->ptr;}
+static inline long   rb_ary_len(VALUE s) {return  RARRAY(s)->len;}
+static inline VALUE *rb_ary_ptr(VALUE s) {return  RARRAY(s)->ptr;}
+#endif // RARRAY_LEN
+
 VALUE handle_bytedata(caddr_t addr, uint32_t nbytes);
 
+VALUE dtrace_process_init(VALUE self);
+void dtrace_process_release(dtrace_process_t *process);
+VALUE dtrace_process_continue(VALUE self);
+
 VALUE dtraceaggdata_init(VALUE self);
 VALUE dtraceaggdata_value(VALUE self);
 VALUE dtraceaggdata_aggtype(VALUE self);
 
 void  dtrace_hdl_free (void *handle);
-VALUE dtrace_hdl_alloc(VALUE klass);
 VALUE dtrace_init(VALUE self);
+VALUE dtrace_hdl_alloc(VALUE klass);
 VALUE dtrace_each_probe(VALUE self);
 VALUE dtrace_strcompile(int argc, VALUE *argv, VALUE self);
 VALUE dtrace_hdl_go(VALUE self);
 VALUE dtrace_hdl_status(VALUE self);
 VALUE dtrace_hdl_setopt(VALUE self, VALUE key, VALUE value);
 VALUE dtrace_hdl_stop(VALUE self);
-VALUE dtrace_hdl_each_aggregate(VALUE self);
-VALUE dtrace_hdl_aggregate_print(VALUE self);
-VALUE dtrace_hdl_aggregate_snap(VALUE self);
-VALUE dtrace_hdl_aggregate_clear(VALUE self);
 VALUE dtrace_hdl_error(VALUE self);
 VALUE dtrace_hdl_sleep(VALUE self);
-VALUE dtrace_hdl_work(VALUE self, 
-		      VALUE probe_consumer_proc, 
-		      VALUE rec_consumer_proc);
+VALUE dtrace_hdl_work(int argc, VALUE *argv, VALUE self);
 VALUE dtrace_hdl_buf_consumer(VALUE self, VALUE buf_consumer_proc);
+VALUE dtrace_hdl_createprocess(VALUE self, VALUE argv);
+VALUE dtrace_hdl_grabprocess(VALUE self, VALUE pid);
 
 VALUE dtraceprobe_init(VALUE self);
 VALUE dtraceprobe_probe_id(VALUE self);
@@ -42,10 +73,17 @@ VALUE dtraceprobe_func(VALUE self);
 VALUE dtraceprobe_name(VALUE self);
 
 VALUE dtraceprobedata_init(VALUE self);
-VALUE dtraceprobedata_probedesc(VALUE self);
+VALUE dtraceprobedata_epid(VALUE self);
+VALUE dtraceprobedata_probe(VALUE self);
+VALUE dtraceprobedata_cpu(VALUE self);
+VALUE dtraceprobedata_indent(VALUE self);
+VALUE dtraceprobedata_prefix(VALUE self);
+VALUE dtraceprobedata_flow(VALUE self);
 VALUE dtraceprobedata_each_record(VALUE self);
 
 VALUE dtracebufdata_init(VALUE self);
+VALUE dtracebufdata_epid(VALUE self);
+VALUE dtracebufdata_probe(VALUE self);
 VALUE dtracebufdata_record(VALUE self);
 
 VALUE dtraceprogram_init(VALUE self);
@@ -59,3 +97,4 @@ VALUE dtraceprograminfo_matches_count(VALUE self);
 VALUE dtraceprograminfo_speculations_count(VALUE self);
 
 VALUE dtracerecdesc_init(VALUE self);
+VALUE dtracerecdesc_action(VALUE self);

data/ext/dtrace_bufdata.c

@@ -7,6 +7,7 @@
 RUBY_EXTERN VALUE eDtraceException;
 RUBY_EXTERN VALUE cDtraceAggData;
 RUBY_EXTERN VALUE cDtraceRecDesc;
+RUBY_EXTERN VALUE cDtraceProbe;
 
 /* :nodoc: */
 VALUE dtracebufdata_init(VALUE self)
@@ -17,6 +18,46 @@ VALUE dtracebufdata_init(VALUE self)
   return self;
 }
 
+/*
+ * Returns the enabled probe id which generated this data
+ */
+VALUE dtracebufdata_epid(VALUE self)
+{
+  dtrace_bufdata_t *bufdata;
+
+  Data_Get_Struct(self, dtrace_bufdata_t, bufdata);
+  
+  if (bufdata->dtbda_probe) {
+    return INT2FIX(bufdata->dtbda_probe->dtpda_edesc->dtepd_epid);
+  }
+
+  return Qnil;
+}
+
+
+/* 
+ * Returns the DtraceProbe for the probe which generated this data 
+ */
+VALUE dtracebufdata_probe(VALUE self)
+{
+  dtrace_bufdata_t *bufdata;
+  VALUE dtraceprobe;
+
+  Data_Get_Struct(self, dtrace_bufdata_t, bufdata);
+  
+  if (bufdata->dtbda_probe) {
+    dtraceprobe = Data_Wrap_Struct(cDtraceProbe, 0, NULL, (dtrace_probedesc_t *)bufdata->dtbda_probe->dtpda_pdesc);
+    return dtraceprobe;
+  }
+
+  return Qnil;
+}
+
+/* 
+ * Returns the record in this DtraceBufdata. Records are returned as
+ * either DtraceRecords or DtraceStackRecords as appropriate for the
+ * type of action.
+ */
 VALUE dtracebufdata_record(VALUE self)
 {
   dtrace_bufdata_t *bufdata;
@@ -50,17 +91,22 @@ VALUE dtracebufdata_record(VALUE self)
     /* trace() action */
     break;
   case DTRACEACT_PRINTF:
-    /*
-     * Only the formatted string was not available to dtj_chewrec(),
-     * so we attach that now.
-     */
+    /* printf action, not available in probedata */
     v = rb_str_new2(s);
+    dtracerecord = rb_class_new_instance(0, NULL, rb_path2class("DtracePrintfRecord"));
+    rb_iv_set(dtracerecord, "@from", rb_str_new2("bufdata"));
+    rb_iv_set(dtracerecord, "@value", v);
+    return (dtracerecord);
     break;
   case DTRACEACT_STACK:
   case DTRACEACT_USTACK:
   case DTRACEACT_JSTACK:
     /* stand-alone stack(), ustack(), or jstack() action */
     v = rb_str_new2(s);
+    dtracerecord = rb_class_new_instance(0, NULL, rb_path2class("DtraceStackRecord"));
+    rb_iv_set(dtracerecord, "@from", rb_str_new2("bufdata"));
+    rb_funcall(dtracerecord, rb_intern("parse"), 1, v);
+    return (dtracerecord);
     break;
   case DTRACEACT_USYM:
   case DTRACEACT_UADDR:
@@ -83,6 +129,8 @@ VALUE dtracebufdata_record(VALUE self)
   if (!NIL_P(v)) {
     dtracerecord = rb_class_new_instance(0, NULL, rb_path2class("DtraceRecord"));
     rb_iv_set(dtracerecord, "@value", v);
+    rb_iv_set(dtracerecord, "@action", INT2FIX(act));
+    rb_iv_set(dtracerecord, "@from", rb_str_new2("bufdata"));
     return (dtracerecord);
   }
   else {

data/ext/dtrace_hdl.c

@@ -5,16 +5,19 @@
 #include "dtrace_api.h"
 
 RUBY_EXTERN VALUE eDtraceException;
+
+RUBY_EXTERN VALUE cDtrace;
 RUBY_EXTERN VALUE cDtraceProbe;
 RUBY_EXTERN VALUE cDtraceProgram;
-RUBY_EXTERN VALUE cDtraceAggData;
 RUBY_EXTERN VALUE cDtraceRecDesc;
 RUBY_EXTERN VALUE cDtraceProbeData;
 RUBY_EXTERN VALUE cDtraceBufData;
+RUBY_EXTERN VALUE cDtraceProcess;
 
 void dtrace_hdl_free (void *handle)
 {
-  dtrace_close(handle);
+  if (handle)
+    dtrace_close(handle);
 }
 
 VALUE dtrace_hdl_alloc(VALUE klass)
@@ -26,6 +29,17 @@ VALUE dtrace_hdl_alloc(VALUE klass)
   handle = dtrace_open(DTRACE_VERSION, 0, &err);
   
   if (handle) {
+    /*
+     * Leopard's DTrace requires symbol resolution to be 
+     * switched on explicitly 
+     */ 
+#ifdef __APPLE__
+    (void) dtrace_setopt(handle, "stacksymbols", "enabled");
+#endif
+
+    /* always request flowindent information */
+    (void) dtrace_setopt(handle, "flowindent", 0);
+
     obj = Data_Wrap_Struct(klass, 0, dtrace_hdl_free, handle);
     return obj;
   }
@@ -96,7 +110,7 @@ VALUE dtrace_strcompile(int argc, VALUE *argv, VALUE self)
 
   rb_scan_args(argc, argv, "1*", &dtrace_text, &dtrace_argv_array);
 
-  dtrace_argc = FIX2INT(rb_funcall(dtrace_argv_array, rb_intern("length"), 0));
+  dtrace_argc = rb_ary_len(dtrace_argv_array);
   dtrace_argv = ALLOC_N(char *, dtrace_argc + 1);
   for (i = 0; i < dtrace_argc; i++) {
     dtrace_argv[i + 1] = STR2CSTR(rb_ary_entry(dtrace_argv_array, i));
@@ -202,72 +216,6 @@ VALUE dtrace_hdl_stop(VALUE self)
   return Qnil;
 }
 
-int _agg_walk_yield(const dtrace_aggdata_t *data, void *arg)
-{
-  VALUE aggdata;
-
-  aggdata = Data_Wrap_Struct(cDtraceAggData, 0, NULL, (dtrace_aggdata_t *)data);
-
-  rb_yield(aggdata);
-  return (DTRACE_AGGWALK_NEXT);
-}
-
-/*
- * Yields each aggregate in turn. 
- * 
- * Aggregates are represented by a DtraceAggregate object.
- */
-VALUE dtrace_hdl_each_aggregate(VALUE self)
-{
-  dtrace_hdl_t *handle;
-
-  Data_Get_Struct(self, dtrace_hdl_t, handle);
-  if (dtrace_aggregate_walk_keyvarsorted(handle, _agg_walk_yield, NULL) < 0)
-    rb_raise(eDtraceException, dtrace_errmsg(handle, dtrace_errno(handle)));
-    
-  return Qnil;    
-}
-
-/* 
- * Uses libdtrace to print a summary of aggregates to STDERR.
- */
-VALUE dtrace_hdl_aggregate_print(VALUE self)
-{
-  dtrace_hdl_t *handle;
-
-  Data_Get_Struct(self, dtrace_hdl_t, handle);
-  if (dtrace_aggregate_print(handle, stderr, NULL) < 0)
-    rb_raise(eDtraceException, dtrace_errmsg(handle, dtrace_errno(handle)));
-    
-  return Qnil;
-}
-
-/*
- * Take a snapshot of the current aggregate values.
- */
-VALUE dtrace_hdl_aggregate_snap(VALUE self)
-{
-  dtrace_hdl_t *handle;
-
-  Data_Get_Struct(self, dtrace_hdl_t, handle);
-  if (dtrace_aggregate_snap(handle) < 0) 
-    rb_raise(eDtraceException, dtrace_errmsg(handle, dtrace_errno(handle)));
-    
-  return Qnil;
-}
-
-/*
- * Clear the current aggregate snapshot.
- */
-VALUE dtrace_hdl_aggregate_clear(VALUE self)
-{
-  dtrace_hdl_t *handle;
-
-  Data_Get_Struct(self, dtrace_hdl_t, handle);
-  dtrace_aggregate_clear(handle);
-  return Qnil;
-}
-
 /* 
  * Return the most recent DTrace error.
  */
@@ -294,11 +242,6 @@ VALUE dtrace_hdl_sleep(VALUE self)
   return Qnil;
 }
 
-typedef struct dtrace_work_handlers {
-  VALUE probe;
-  VALUE rec;
-} dtrace_work_handlers_t;
-
 static int _probe_consumer(const dtrace_probedata_t *data, void *arg)
 {
   VALUE proc;
@@ -308,9 +251,12 @@ static int _probe_consumer(const dtrace_probedata_t *data, void *arg)
   handlers = *(dtrace_work_handlers_t *) arg;
   proc = handlers.probe;
 
-  probedata = Data_Wrap_Struct(cDtraceProbeData, 0, NULL, (dtrace_probedata_t *)data);
-  rb_funcall(proc, rb_intern("call"), 1, probedata);
-  
+  if (!NIL_P(proc)) {
+    probedata = Data_Wrap_Struct(cDtraceProbeData, 0, NULL, (dtrace_probedata_t *)data);
+    rb_iv_set(probedata, "@handle", handlers.handle);
+    rb_funcall(proc, rb_intern("call"), 1, probedata);
+  }
+
   return (DTRACE_CONSUME_THIS);
 }
 
@@ -319,12 +265,29 @@ static int _rec_consumer(const dtrace_probedata_t *data, const dtrace_recdesc_t
   VALUE proc;
   dtrace_work_handlers_t handlers;
   VALUE recdesc;
+  VALUE probedata;
+
+  dtrace_actkind_t act;
 
   handlers = *(dtrace_work_handlers_t *) arg;
   proc = handlers.rec;
+  if (!NIL_P(proc)) {
+    if (rec) {
+      recdesc = Data_Wrap_Struct(cDtraceRecDesc, 0, NULL, (dtrace_recdesc_t *)rec);
+      rb_iv_set(recdesc, "@handle", handlers.handle);
+      rb_funcall(proc, rb_intern("call"), 1, recdesc);
+    }
+    else {
+      rb_funcall(proc, rb_intern("call"), 1, Qnil);
+      return (DTRACE_CONSUME_NEXT);
+    }
+  }
 
-  recdesc = Data_Wrap_Struct(cDtraceRecDesc, 0, NULL, (dtrace_recdesc_t *)rec);
-  rb_funcall(proc, rb_intern("call"), 1, recdesc);
+  if (rec) {
+    act = rec->dtrd_action;
+    if (act == DTRACEACT_EXIT)
+      return (DTRACE_CONSUME_NEXT);
+  }
 
   return (DTRACE_CONSUME_THIS);
 }
@@ -336,30 +299,44 @@ static int _buf_consumer(const dtrace_bufdata_t *bufdata, void *arg)
 
   proc = (VALUE)arg;
 
-  dtracebufdata = Data_Wrap_Struct(cDtraceBufData, 0, NULL, (dtrace_bufdata_t *)bufdata);
-  rb_funcall(proc, rb_intern("call"), 1, dtracebufdata);
+  if (!NIL_P(proc)) {
+    dtracebufdata = Data_Wrap_Struct(cDtraceBufData, 0, NULL, (dtrace_bufdata_t *)bufdata);
+    rb_funcall(proc, rb_intern("call"), 1, dtracebufdata);
+  }
 
   return (DTRACE_HANDLE_OK);
 }
 
 /*
  * Process any data waiting from the D program.
+ * 
+ * Takes a Proc to which DtraceProbeData objects will be yielded, and
+ * an optional second Proc to which DtraceRecDesc objects will be
+ * yielded.
+ *
  */
-VALUE dtrace_hdl_work(VALUE self, 
-		      VALUE probe_consumer_proc, 
-		      VALUE rec_consumer_proc)
+VALUE dtrace_hdl_work(int argc, VALUE *argv, VALUE self)
 {
   dtrace_hdl_t *handle;
   dtrace_workstatus_t status;
   dtrace_work_handlers_t handlers;
+  VALUE probe_consumer_proc;
+  VALUE rec_consumer_proc;
   
   Data_Get_Struct(self, dtrace_hdl_t, handle);
 
+  /* handle args - probe_consumer_proc is mandatory, rec_consumer_proc
+     is optional */
+  rb_scan_args(argc, argv, "11", &probe_consumer_proc, &rec_consumer_proc);
+
   /* fill out the handlers struct */
-  handlers.probe = probe_consumer_proc;
-  handlers.rec   = rec_consumer_proc;
+  handlers.probe  = probe_consumer_proc;
+  handlers.rec    = rec_consumer_proc;
+  handlers.handle = self;
 
   status = dtrace_work(handle, NULL, _probe_consumer, _rec_consumer, &handlers);
+  if (status < 0)
+    rb_raise(eDtraceException, (dtrace_errmsg(handle, dtrace_errno(handle))));
 
   return INT2FIX(status);
 }  
@@ -379,3 +356,77 @@ VALUE dtrace_hdl_buf_consumer(VALUE self, VALUE buf_consumer)
 
   return Qnil;
 }
+
+/* 
+ * Start a process which will be traced. The pid of the started
+ * process will be available in D as $target.
+ * 
+ * Pass an array, where the first element is the full path to the
+ * program to start, and subsequent elements are its arguments.
+ * 
+ * Returns a DtraceProcess object which is used to start the process
+ * once tracing is set up.
+ */
+VALUE dtrace_hdl_createprocess(VALUE self, VALUE rb_argv)
+{
+  dtrace_hdl_t *handle;
+  struct ps_prochandle *P;
+  char **argv;
+  long len;
+  int i;
+  VALUE dtraceprocess;
+  dtrace_process_t *process;
+
+  Data_Get_Struct(self, dtrace_hdl_t, handle);
+
+  len = rb_ary_len(rb_argv);
+  argv = ALLOC_N(char *, len + 1);
+
+  for (i = 0; i < len; i++) {
+    argv[i] = STR2CSTR(rb_ary_entry(rb_argv, i));
+  }
+  argv[len] = NULL;
+
+  P = dtrace_proc_create(handle, argv[0], argv);
+  free(argv);
+  
+  if (P == NULL) {
+    rb_raise(eDtraceException, dtrace_errmsg(handle, dtrace_errno(handle)));
+  }
+  
+  process = ALLOC(dtrace_process_t);
+  process->handle = handle;
+  process->proc   = P;
+
+  dtraceprocess = Data_Wrap_Struct(cDtraceProcess, 0, dtrace_process_release, (dtrace_process_t *)process);
+  return dtraceprocess;
+}
+
+/* 
+ * Grab a currently-running process by pid. 
+ *
+ * Returns a DtraceProcess object which is used to start the process
+ * once tracing is set up.
+ */
+VALUE dtrace_hdl_grabprocess(VALUE self, VALUE pid)
+{
+  dtrace_hdl_t *handle;
+  struct ps_prochandle *P;
+  dtrace_process_t *process;
+  VALUE dtraceprocess;
+
+  Data_Get_Struct(self, dtrace_hdl_t, handle);
+
+  P = dtrace_proc_grab(handle, FIX2INT(pid), 0);
+  
+  if (P == NULL) {
+    rb_raise(eDtraceException, dtrace_errmsg(handle, dtrace_errno(handle)));
+  }
+  
+  process = ALLOC(dtrace_process_t);
+  process->handle = handle;
+  process->proc   = P;
+
+  dtraceprocess = Data_Wrap_Struct(cDtraceProcess, 0, dtrace_process_release, (dtrace_process_t *)process);
+  return dtraceprocess;
+}