'\" te
.\"  Copyright (c) 1998 Sun Microsystems, Inc.  All Rights Reserved
.TH td_ta_new 3C_DB "20 Oct 1998" "SunOS 5.11" "Threads Debugging Library Functions"
.SH NAME
td_ta_new, td_ta_delete, td_ta_get_ph \- allocate and deallocate process handles for libc_db
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR... ] \fIfile\fR... -lc_db [ \fIlibrary\fR... ]
#include <proc_service.h>
#include <thread_db.h>

\fBtd_err_e\fR \fBtd_ta_new\fR(\fBconst struct ps_prochandle *\fR\fIph_p\fR, \fBtd_thragent_t **\fR\fIta_pp\fR);
.fi

.LP
.nf
\fBtd_err_e\fR \fBtd_ta_delete\fR(\fBconst td_thragent_t *\fR\fIta_p\fR);
.fi

.LP
.nf
\fBtd_err_e\fR \fBtd_ta_get_ph\fR(\fBconst td_thragent_t *\fR\fIta_p\fR, \fBstruct ps_prochandle **\fR\fIph_pp\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBtd_ta_new()\fR function registers a target process with \fBlibc_db\fR(3LIB) and allocates an internal process handle of type \fBtd_thragent_t\fR for this target process.  Subsequent calls to \fBlibc_db\fR can use this handle to refer to this target process.
.sp
.LP
There are actually two process handles,  an internal process handle assigned by \fBlibc_db\fR and an external process handle assigned by the \fBlibc_db\fR client. There is a one-to-one correspondence between the two handles.  When the client calls a \fBlibc_db\fR function, it uses the internal process handle.  When \fBlibc_db\fR calls one of the client-provided routines listed in \fBproc_service\fR(3PROC), it uses the external process handle.
.sp
.LP
The \fIph\fR argument is the external process handle that \fBlibc_db\fR should use to identify this target process to the controlling process when it calls routines in the imported interface.
.sp
.LP
If this call is successful, the value of the newly allocated \fBtd_thragent_t\fR handle is returned in  *\fIta_pp\fR. The \fBtd_ta_delete()\fR function deregisters a target process with \fBlibc_db\fR, which deallocates its internal process handle and frees any other resources \fBlibc_db\fR has acquired with respect to the target process. The \fIta_p\fR argument specifies the target process to be deregistered.
.sp
.LP
The \fBtd_ta_get_ph()\fR function returns in *\fIph_pp\fR the external process handle that corresponds to the internal process handle \fIta_p\fR. This is useful for checking internal consistency.
.SH RETURN VALUES
.sp
.ne 2
.mk
.na
\fB\fBTD_OK\fR\fR
.ad
.RS 18n
.rt  
The call completed successfully.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTD_BADPH\fR\fR
.ad
.RS 18n
.rt  
A \fINULL\fR external process handle was passed to \fBtd_ta_new()\fR. 
.RE

.sp
.ne 2
.mk
.na
\fB\fBTD_ERR\fR\fR
.ad
.RS 18n
.rt  
The \fIta_pp\fR argument is \fINULL\fR or an internal error occurred.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTD_DBERR\fR\fR
.ad
.RS 18n
.rt  
A call to one of the imported interface routines failed.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTD_MALLOC\fR\fR
.ad
.RS 18n
.rt  
Memory allocation failure.
.RE

.sp
.ne 2
.mk
.na
\fB\fBTD_NOLIBTHREAD\fR\fR
.ad
.RS 18n
.rt  
The target process does not appear to be multithreaded.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for description of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
MT-LevelSafe
.TE

.SH SEE ALSO
.sp
.LP
\fBlibc_db\fR(3LIB), \fBproc_service\fR(3PROC), \fBattributes\fR(5)