Go to main content

man pages section 3: Extended Library Functions, Volume 3

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

Lstop (3PROC)

Name

Lgrab, Lgrab_error, Lprochandle, Lfree, Lstate, Lpsinfo, Lstatus, Lsync, Lstop, Ldstop, Lwait, Lrefresh, Lclearsig, Lclearfault, Lsetrun, Lxecbkpt, Lxecwapt - victim lwps within a victim process

Synopsis

#include <libproc.h>
ps_lwphandle_t *Lgrab(ps_prochandle_t *Pr, lwpid_t lwpid, int *perr);
const char *Lgrab_error(int error);
ps_prochandle_t *Lprochandle(ps_lwphandle_t *Lwp);
void Lfree(ps_lwphandle_t *Lwp);
int Lstate(ps_lwphandle_t *Lwp);
const lwpsinfo_t *Lpsinfo(ps_lwphandle_t *Lwp);
const lwpstatus_t *Lstatus(ps_lwphandle_t *Lwp);
void Lsync(ps_lwphandle_t *Lwp);
int Lstop(ps_lwphandle_t *Lwp, uint_t msec);
int Ldstop(ps_lwphandle_t *Lwp);
int Lwait(ps_lwphandle_t *Lwp, uint_t msec);
int Lrefresh(ps_lwphandle_t *Lwp);
int Lclearsig(ps_lwphandle_t *Lwp);
int Lclearfault(ps_lwphandle_t *Lwp);
int Lsetrun(ps_lwphandle_t *Lwp, int sig, int flags);
int Lxecbkpt(ps_lwphandle_t *Lwp, ulong_t saved);
int Lxecwapt(ps_lwphandle_t *Lwp, const prwatch_t *wp);

Description

The functions in this group are useful primarily if the controlling process wants to operate in asynchronous-stop mode. Asynchronous-stop mode is set in the victim process by calling:

Psetflags(Pr, PR_ASYNC);

Asynchronous-stop mode is useful if both the controlling process and the victim process are multi-threaded. The controlling process can create threads in itself to exercise control over individual light weight processes (lwps) of the victim process in a one-to-one manner. A stop on an event of interest by one lwp in the victim process does not cause any other lwp in the victim process to stop, as is the case when asynchronous-stop mode is not in effect. For more information, see the proc(5) man page.

The Lgrab() function establishes control over one lwp in a victim process. The Pr argument identifies a victim process attached to the controlling process by the create and grab interfaces and the lwpid argument identifies an individual lwp (thread) within the victim process. For more information, see the Pcreate(3PROC) and Pgrab(3PROC) man pages.

On successful completion, the Lgrab() function returns a pointer to an opaque ps_lwphandle_t structure, allocated by the library, which must be used by almost all of the remaining functions described here to effect inspection and control of the individual victim lwp of the victim process. Only one instance of Lgrab() can be in effect at any one time for any one Lwp. On failure, the Lgrab() function returns a NULL pointer and sets the integer pointed to by the perr argument to an error code:

G_NOPROC         No such lwp
G_BUSY           Another Lgrab() is in effect
G_STRANGE        Unanticipated error, errno is meaningful

The Lgrab_error() function maps the error from an Lgrab() failure to an error message string and returns a pointer to that string.

The Lprochandle() function returns a pointer to the ps_prochandle_t instance that was used to grab this lwp.

The Lfree() function closes all of the /proc file descriptors, and frees all of the memory allocated for the instance of ps_lwphandle_t pointed to by the lwp argument. This does nothing to the victim, lwp; if it has not terminated, it can be grabbed again.

The Lstate() function returns the state of the victim, lwp. One of the following values are returned:

PS_RUN

lwp is running

PS_STOP

lwp is stopped

PS_UNDEAD

lwp is terminated (become a zombie)

PS_DEAD

no lwp has been run (examining a core file)

The Lpsinfo() and Lstatus() functions return pointers to the lwpsinfo_t structure and the lwpstatus_t structure for the victim lwp, respectively.

The Lsync(), Lstop(), Ldstop(), Lwait(), Lrefresh(), Lclearsig(), Lclearfault(), and Lsetrun() functions behave, for the victim lwp, the same as the Psync(), Pstop(), Pdstop(), Pwait(), Prefresh(), Pclearsig(), Pclearfault(), and Psetrun() functions do for the victim process, but without affecting any other lwps in the process.

The Lxecbkpt() and Lxecwapt() functions behave in the same way for the victim lwp, as the Pxecbkpt(), and Pxecwapt() functions do for the victim process. The P*() functions operate on the representative lwp, whereas the L*() functions are lwp-specific.

Return Values

On successful completion, the Lgrab() function returns a pointer to a ps_lwphandle_t structure. On failure, the Lgrab() function returns a NULL pointer.

The Lprochandle() function returns a pointer to the ps_prochandle_t instance that was used to grab this lwp.

The remainder of the functions described here return 0 on success. They return -1 on failure and set errno to indicate the error.

Errors

These are the possible values returned in the integer pointed to by the perr argument if an Lgrab() failure occurs:

G_NOPROC

No such lwp

G_BUSY

Another Lgrab() is in effect

G_STRANGE

Unanticipated error, errno is meaningful

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Unsafe

See Also

libproc(3LIB), libproc.h(3HEAD), Pcreate(3PROC), Prelease(3PROC)