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 PCTFLD 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Pctlfd
  19 .Nd obtain the process control file descriptor
  20 .Sh LIBRARY
  21 .Lb libproc
  22 .Sh SYNOPSIS
  23 .In libproc.h
  24 .Ft int
  25 .Fo Pctlfd
  26 .Fa "struct ps_prochandle *P"
  27 .Fc
  28 .Sh DESCRIPTION
  29 The
  30 .Fn Pctlfd
  31 function returns a file descriptor to the underlying /proc file system
  32 .Sy ctl
  33 file for the process identified by the handle
  34 .Fa P .
  35 This may be used for injecting control operations manually;
  36 however, many interfaces for using it are provided by
  37 .Xr libproc 3LIB
  38 itself.
  39 .Pp
  40 Only live processes have a control file descriptor.
  41 Process handles that correspond to files and cores, created through
  42 .Xr Pgrab_file 3PROC
  43 and
  44 .Xr Pgrab_core 3PROC ,
  45 do not have a corresponding file descriptor.
  46 .Pp
  47 The file descriptor is invalidated when the process handle is released
  48 through
  49 .Xr Prelease 3PROC
  50 or if control is lost and the handle is reopened.
  51 .Sh RETURN VALUES
  52 Upon successful completion, the
  53 .Fn Pctlfd
  54 function returns a valid file descriptor.
  55 Otherwise, if none exists, then
  56 .Sy -1
  57 is returned.
  58 .Sh INTERFACE STABILITY
  59 .Sy Uncommitted
  60 .Sh MT-LEVEL
  61 See
  62 .Sy LOCKING
  63 in
  64 .Xr libproc 3LIB .
  65 .Sh SEE ALSO
  66 .Xr libproc 3LIB ,
  67 .Xr Pcreate 3PROC ,
  68 .Xr Pgrab 3PROC ,
  69 .Xr Pgrab_core 3PROC ,
  70 .Xr Pgrab_file 3PROC ,
  71 .Xr Prelease 3PROC ,
  72 .Xr Preopen 3PROC ,
  73 .Xr proc 4