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