pxfexecv

Date:: 10-20-2011

NAME

PXFEXECV, PXFEXECVE, PXFEXECVP - Executes a new process image file

SYNOPSIS

INTEGER lenpath, lenargv(0:iargc-1), iargc, ierror
CHARACTER*n path, argv(0:iargc-1)
CALL PXFEXECV (path, lenpath, argv, lenargv, iargc, ierror)

INTEGER lenpath, lenargv(0:iargc-1), iargc, lenargv, ienvc, ierror
CHARACTER*n path, argv(0:iargc-1) env(ienvc)
CALL PXFEXECVE (path, lenpath, argv, lenargv, iargc, env, lenenv, ienvc, ierror)

INTEGER lenfile, lenargv(0:iargc-1), iargc, ierror
CHARACTER*n file, argv(0:iargc-1)
CALL PXFEXECVP (file, lenfile, argv, lenargv, iargc, ierror)

DESCRIPTION

The PXFEXECV routine uses the execv(2) system call to replace the current process image with a new process image.

The PXFEXECVE routine uses the execve(2) system call to replace the current process image with a new process image. The environment variables are not inherited from the calling process image. The environment variables for the new process image are specified by the env argument.

The PXFEXECVP routine uses the execvp(2) system call to replace the current process image with a new process image.

All arguments must be of default kind unless documented otherwise. Default kind is KIND=4 for integer, real, complex, and logical arguments.

The following is a list of arguments for these routines:

path: An input character variable or array element containing the path name of the new process image file.
lenpath: An input integer variable for the length of path. If lenpath is zero, trailing blanks are removed.
file: An input character variable or array element containing the file of the new process image file. If file contains a slash character, file will be used as the pathname for the new process image file. Otherwise, the directories listed in the PATH environment variable are searched using each directory in path as a pathname prefix for file.
lenfile: An input integer variable for the length of file. If lenfile is zero, trailing blanks are removed.
argv: An input array of character strings. argv contains the arguments to be passed to the new process image.
lenargv: An input array of integers. Each element in lenargv contains the length of the corresponding character string in argv. If an element in lenargv is zero, the corresponding element in argv has all trailing blanks stripped.
iargc: An input integer variable. iargc contains the number of arguments to pass to the new process image.
env: An input array of character strings. env contains the environment variables for the new process image.
lenenv: An input array of integers. Each element in lenenv contains the length of the corresponding character string in env. If an element in lenenv is zero, the corresponding element in env will have all trailing blanks stripped.
ienvc: An input integer variable. ienvc contains the number of environment variables for the new process image.
ierror: An output integer variable that contains zero if the routine was successful or nonzero if the routine was not successful.

The following values may be returned:

EACCES: If the new process file is not a regular file, the new process image file mode denies execution permission, or search permission is denied for a directory listed in the new process image file’s path prefix.
ENOENT: If one or more components of the new process image file’s path name do not exist.
ENOEXEC: If the new process image file has the appropriate access permission but an invalid magic number in its header.
ENOMEM: If the memory needed to create structures used by the routine could not be allocated.
EINVAL: If lenpath < 0 or lenpath > LEN(path)or any element of lenargv is less than zero or greater than the length of the corresponding element in argv.

EXAMPLES

PXFEXECV example:

In this example, the program forks and the child calls PXFEXECV to execute the /bin/grep process image file. The parent process waits for the child to finish executing and then forks again. The child from the second fork also calls PXFEXECV to execute the /bin/grep process image file. The parent then waits for the child to finish executing.

program test
integer ipid, ierror, lenpath, lenargv(3), iargc, iretpid
integer istat
character*30 path, argv(3)
path = '/bin/grep'
lenpath = 0
iargc = 3
argv(1) = 'grep'
lenargv(1) = 0
argv(2) = 'root'
lenargv(2) = 0
argv(3) = '/etc/passwd'
lenargv(3) = 0

CALL PXFFORK(ipid,ierror)
if (ierror .ne. 0) then
   print *,'FAILED: PXFFORK call with error = ',ierror
else
   if (ipid .eq. 0) then
      print *,'CHILD1: execing grep'
      CALL PXFEXECV(path, lenpath, argv, lenargv, iargc, ierror)
      print *,'FAILED: PXFEXEC call with error = ',ierror
      stop
   else
      print *,'PARENT: waiting for CHILD1'
      CALL PXFWAIT(istat,iretpid,ierror)
      print *,'PARENT: CHILD1 finished. Forking off CHILD2'
      CALL PXFFORK(ipid, ierror)
      if (ipid .eq. 0) then
          print *,'CHILD2: execing grep'
          CALL PXFEXECV(path, lenpath, argv, lenargv, iargc, ierror)
          print *,'FAILED PXFEXEC call with error = ',ierror
          stop
      else
          print *,'PARENT: waiting for CHILD2'
          CALL PXFWAIT(istat,iretpid,ierror)
          print *,'PARENT: CHILD2 finished.'
          print *,'PASSED: PXFEXECV normal test'
      endif
   endif
endif
end

PXFEXECVE example:

In this example, the program forks and the child calls PXFEXECVE to execute the /bin/grep process image file. The parent process waits for the child to finish executing and then forks again. The child from the second fork also calls PXFEXECVE to execute the /bin/grep process image file. The parent then waits for the child to finish executing.

integer ipid, ierror, lenpath, lenargv(3), iargc, iretpid
integer istat, errorcondition, lenenv(3), ienvc
character*30 path, argv(3)
character*30 env(3)

path = '/bin/grep'
lenpath = 0
iargc = 3
argv(1) = 'grep'
lenargv(1) = 0
argv(2) = 'root'
lenargv(2) = 0
argv(3) = '/etc/passwd'
lenargv(3) = 0
ienvc = 3
env(1) = 'TERM=vt100'
lenenv(1) = 0
env(2) = 'SHELL=/bin/csh'
lenenv(2) = 0
env(3) = 'DISPLAY=:0.0'
lenenv(3) = 0

CALL PXFFORK(ipid,ierror)
if (ierror .ne. 0) then
   print *,'FAILED: PXFFORK call with error = ',ierror
else
   if (ipid .eq. 0) then
      print *,'CHILD1: execing grep'
      CALL PXFEXECV(path, lenpath, argv, lenargv, iargc, ierror)
      print *,'FAILED: PXFEXEC call with error = ',ierror
      stop
   else
      print *,'PARENT: waiting for CHILD1'
      CALL PXFWAIT(istat,iretpid,ierror)
      print *,'PARENT: CHILD1 finished. Forking off CHILD2'
      CALL PXFFORK(ipid, ierror)
      if (ipid .eq. 0) then
         print *,'CHILD2: execing grep'
         CALL PXFEXECV(path, lenpath, argv, lenargv, iargc, ierror)
         print *,'FAILED PXFEXEC call with error = ',ierror
         stop
      else
         print *,'PARENT: waiting for CHILD2'
         CALL PXFWAIT(istat,iretpid,ierror)
         print *,'PARENT: CHILD2 finished.'
         print *,'PASSED: PXFEXECVP normal test'
      endif
   endif
endif
end

PXFEXECVP example:

In this example, the program forks and the child calls PXFEXECVP to execute the grep process image file. The parent process waits for the child to finish executing and then forks again. The child from the second fork also calls PXFEXECVP to execute the grep process image file. The parent then waits for the child to finish executing.

program test
integer ipid, ierror, lenfile, lenargv(3), iargc, iretpid
integer istat
character*30 file, argv(3)

file = 'grep'
lenfile = 0
iargc = 3
argv(1) = 'grep'
lenargv(1) = 0
argv(2) = 'root'
lenargv(2) = 0
argv(3) = '/etc/passwd'
lenargv(3) = 0

CALL PXFFORK(ipid,ierror)
if (ierror .ne. 0) then
   print *,'FAILED: PXFFORK call with error = ',ierror
else
   if (ipid .eq. 0) then
      print *,'CHILD1: execing grep'
      CALL PXFEXECVP(file, lenfile, argv, lenargv, iargc, ierror)
      print *,'FAILED: PXFEXEC call with error = ',ierror
      stop
   else
      print *,'PARENT: waiting for CHILD1'
      CALL PXFWAIT(istat,iretpid,ierror)
      print *,'PARENT: CHILD1 finished. Forking off CHILD2'
      CALL PXFFORK(ipid, ierror)
      if (ipid .eq. 0) then
         print *,'CHILD2: execing grep'
         CALL PXFEXECVP(file, lenfile, argv, lenargv, iargc, ierror)
         print *,'FAILED PXFEXEC call with error = ',ierror
         stop
      else
         print *,'PARENT: waiting for CHILD2'
         CALL PXFWAIT(istat,iretpid,ierror)
         print *,'PARENT: CHILD2 finished.'
         print *,'PASSED: PXFEXECVP normal test'
      endif
   endif
endif
end