1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2015 Joyent, Inc. 13.\" 14.Dd May 11, 2016 15.Dt PCREATE_AGENT 3PROC 16.Os 17.Sh NAME 18.Nm Pcreate_agent 19.Nd create the agent LWP 20.Sh SYNOPSIS 21.Lb libproc 22.In libproc.h 23.Ft int 24.Fo Pcreate_agent 25.Fa "struct ps_prochandle *P" 26.Fc 27.Sh DESCRIPTION 28The 29.Fn Pcreate_agent 30function creates the agent LWP in the process represented by the handle 31.Fa P . 32The agent LWP is used as a means to force system calls to be invoked on 33the controlled process. For more information on the agent LWP, see 34.Xr proc 4 . 35.Pp 36The agent LWP cannot be created for process handles corresponding to 37core files, zombie processes, processes that have yet to run, and ELF 38objects. 39.Pp 40The 41.Fn Pcreate_agent 42function is reentrant. It may be entered recursively. The act of 43creating the agent LWP will cause the process to be stopped. 44For every call to the 45.Fn Pcreate_agent 46function, a corresponding call to 47.Xr Pdestroy_agent 3PROC 48is required. 49.Sh RETURN VALUES 50Upon successful completion, the 51.Fn Pcreate_agent 52function returns 53.Sy 0 54and creates the agent LWP. Otherwise, 55.Sy -1 56is returned, 57.Sy errno 58is set to indicate the error, and the agent LWP is not created. 59.Sh ERRORS 60The 61.Fn Pcreate_agent 62function will fail if: 63.Bl -tag -width Er 64.It Er ENOENT 65The process referred to by 66.Fa P 67is a core file, zombie, ELF object, or has not begun execution. 68.El 69.Pp 70Note, it is possible for other error numbers to be returned. If they 71are, they represent unanticipated failure. 72.Sh INTERFACE STABILITY 73.Sy Uncommitted 74.Sh MT-LEVEL 75See 76.Sy LOCKING 77in 78.Xr libproc 3LIB . 79.Sh SEE ALSO 80.Xr libproc 3LIB , 81.Xr Pdestroy_agent 3PROC , 82.Xr proc 4 83