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