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 PREOPEN 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Preopen
  19 .Nd reopen a process
  20 .Sh SYNOPSIS
  21 .Lb libproc
  22 .In libproc.h
  23 .Ft int
  24 .Fo Preopen
  25 .Fa "struct ps_prochandle *P"
  26 .Fc
  27 .Sh DESCRIPTION
  28 The
  29 .Fn Preopen
  30 function is used to regain control of the process represented by the
  31 handle
  32 .Fa P .
  33 A loss of control is indicated by the
  34 .Xr Pstatus 3PROC
  35 function returning the value
  36 .Dv PS_LOST .
  37 This may occur when the controlled process performs an
  38 .Xr exec 2
  39 of a setuid or setgid binary or one where the controlling process cannot
  40 read the object file.
  41 For more information on this, see the
  42 .Sy PROGRAMMING NOTES
  43 section of
  44 .Xr proc 4 .
  45 .Pp
  46 If successful, the controlling process will obtain control of the
  47 process specified by
  48 .Fa P .
  49 If it fails, the controlling process should release the handle with
  50 .Xr Prelease 3PROC .
  51 Note there are occasions where due to permissions it may not be possible
  52 to obtain control again.
  53 .Sh RETURN VALUES
  54 Upon successful completion, the
  55 .Fn Preopen
  56 function returns
  57 .Sy 0.
  58 Otherwise,
  59 .Sy -1
  60 is returned.
  61 .Sh INTERFACE STABILITY
  62 .Sy Uncommitted
  63 .Sh MT-LEVEL
  64 See
  65 .Sy LOCKING
  66 in
  67 .Xr libproc 3LIB .
  68 .Sh SEE ALSO
  69 .Xr exec 2 ,
  70 .Xr libproc 3LIB ,
  71 .Xr Prelease 3PROC ,
  72 .Xr Pstatus 3PROC ,
  73 .Xr proc 4