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. 34For more information on the agent LWP, see 35.Xr proc 4 . 36.Pp 37The agent LWP cannot be created for process handles corresponding to 38core files, zombie processes, processes that have yet to run, and ELF 39objects. 40.Pp 41The 42.Fn Pcreate_agent 43function is reentrant. 44It may be entered recursively. 45The act of creating the agent LWP will cause the process to be stopped. 46For every call to the 47.Fn Pcreate_agent 48function, a corresponding call to 49.Xr Pdestroy_agent 3PROC 50is required. 51.Sh RETURN VALUES 52Upon successful completion, the 53.Fn Pcreate_agent 54function returns 55.Sy 0 56and creates the agent LWP. 57Otherwise, 58.Sy -1 59is returned, 60.Sy errno 61is set to indicate the error, and the agent LWP is not created. 62.Sh ERRORS 63The 64.Fn Pcreate_agent 65function will fail if: 66.Bl -tag -width Er 67.It Er ENOENT 68The process referred to by 69.Fa P 70is a core file, zombie, ELF object, or has not begun execution. 71.El 72.Pp 73Note, it is possible for other error numbers to be returned. 74If they are, they represent unanticipated failure. 75.Sh INTERFACE STABILITY 76.Sy Uncommitted 77.Sh MT-LEVEL 78See 79.Sy LOCKING 80in 81.Xr libproc 3LIB . 82.Sh SEE ALSO 83.Xr libproc 3LIB , 84.Xr Pdestroy_agent 3PROC , 85.Xr proc 4 86