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