8158 Want named threads API
9857 proc manpages should have LIBRARY section

          --- old/usr/src/man/man3proc/Pcreate.3proc.man.txt
          +++ new/usr/src/man/man3proc/Pcreate.3proc.man.txt
   1    1  PCREATE(3PROC)         Process Control Library Functions        PCREATE(3PROC)
   2    2  
   3    3  NAME
   4    4       Pcreate, Pxcreate, Pcreate_callback - create and control a process
   5    5  
   6      -SYNOPSIS
        6 +LIBRARY
   7    7       Process Control Library (libproc, -lproc)
        8 +
        9 +SYNOPSIS
   8   10       #include <libproc.h>
   9   11  
  10   12       struct ps_prochandle *
  11   13       Pcreate(const char *file, char *const *argv, int *perr, char *path,
  12   14           size_t len);
  13   15  
  14   16       struct ps_prochandle *
  15   17       Pxcreate(const char *file, char *const *argv, char *const *envp,
  16   18           int *perr, char *path, size_t len);
  17   19  

  18   20       void
  19   21       Pcreate_callback(struct ps_prochandle *P);
  20   22  
  21   23  DESCRIPTION
  22   24       The Pcreate() function creates a process controlled by the libproc
  23   25       library.  The Pxcreate() function does the same while also allowing the
  24   26       replacement of the environment via envp.
  25   27  
  26   28       Both functions cause the caller to fork(2).  Followed by the child
  27   29       calling exec(2) to load the new process image specified by file.  The
  28   30       PATH is searched for file if it is not an absolute path, similar to
  29   31       execvp(2).
  30   32  
  31   33       The process image will be invoked with the arguments specified by argv,
  32   34       which should be a NULL-terminated array of character strings.  Each entry
  33   35       in the array is an individual argument.  The environment of the process
  34   36       image will be inherited from the running process if the Pcreate()
  35   37       function is called or if the Pxcreate() function is called and the value
  36   38       of envp is NULL.  Otherwise, envp should be a NULL-terminated array of
  37   39       character strings whose entries are in the form of key=value.  For more
  38   40       on the process environment, see environ(5).
  39   41  
  40   42       The Pcreate_callback() function allows a way for callers to inject a
  41   43       callback into the child process before the call to exec(2).  The symbol
  42   44       Pcreate_callback is a symbol that may be interposed on by consumers.  It
  43   45       allows the chance for the modification of signal dispositions or any
  44   46       other changes that a caller may wish to make.
  45   47  
  46   48       If the caller's real user or group ID is not their effective user or
  47   49       group ID, then the child process's user and group IDs will all be reset
  48   50       to the real user and group id.
  49   51  
  50   52       The perr argument must be a non-NULL pointer.  If the Pcreate() or
  51   53       Pxcreate() functions fail, the value pointed to will be filled in with a
  52   54       more detailed error code listed in ERRORS.  A human-readable error
  53   55       message is obtained with Pcreate_error(3PROC).
  54   56  
  55   57       Multiple executables named file may exist on the PATH.  To determine the
  56   58       full path of the executable pass a non-NULL path pointer.  Upon
  57   59       successful completion of Pcreate() or Pxcreate() the path pointer will
  58   60       contain the full path up to len bytes, including the NUL character.
  59   61  
  60   62       Upon successful completion of the Pcreate() or Pxcreate() function, a
  61   63       handle to the process is returned.  This handle is usable with other
  62   64       libproc routines and will persist until either Pfree(3PROC) or
  63   65       Prelease(3PROC) is called on the resulting handle.  The process created
  64   66       is stopped just after return from the exec(2) family of system calls.
  65   67       The process will not run, unless the caller sets it running or releases
  66   68       its handle to the process.
  67   69  
  68   70       A 32-bit process cannot use this interface to launch or control a 64-bit
  69   71       process.  However, a 64-bit process can create and control both 32-bit
  70   72       and 64-bit processes.
  71   73  
  72   74  RETURN VALUES
  73   75       Upon successful completion, both the Pcreate() and Pxcreate() functions
  74   76       create a new process and return a libproc handle to it.  Otherwise, NULL
  75   77       is returned and perr is filled in with the corresponding error.
  76   78  
  77   79  ERRORS
  78   80       The Pcreate() and Pxcreate() functions will fail if:
  79   81  
  80   82       C_FORK             The call to fork(2) failed.
  81   83  
  82   84       C_INTR             The operation was interrupted by a signal.
  83   85  
  84   86       C_LP64             The calling process is 32-bit, but it attempted to
  85   87                          control a 64-bit process.
  86   88  
  87   89       C_NOEXEC           The specified file or the one found by searching PATH
  88   90                          cannot be executed.
  89   91  
  90   92       C_NOENT            The specified file does not exist or it could not be
  91   93                          found by searching PATH.
  92   94  
  93   95       C_PERM             The specified file or the one found by searching PATH
  94   96                          is set-id or unreadable.
  95   97  
  96   98       C_STRANGE          An unanticipated system error occurred while trying to
  97   99                          create the process and its handle.  When this occurs,
  98  100                          then the value of errno is meaningful.  See errno(3C)
  99  101                          for more information and Intro(2) for the list of
 100  102                          possible errors.
 101  103  
 102  104  INTERFACE STABILITY
 103  105       Uncommitted
 104  106  
 105  107  MT-LEVEL
 106  108       MT-Safe
 107  109  
 108  110  SEE ALSO
 109  111       exec(2), execvp(2), fork(2), Intro(2), errno(3C), libproc(3LIB),
 110  112       Pcreate_error(3PROC), Pfree(3PROC), Prelease(3PROC)
 111  113  
 112  114  illumos                          May 11, 2016                          illumos

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX