iplvm, waitvm

Purpose

     Starts a virtual machine or waits for one to terminate.

Syntax

     int iplvm (iodn, waitflag)                int waitvm (iodn)
     unsigned short iodn;                      unsigned short iodn;
     int waitflag;
     Description

     The iplvm system call starts (IPLs) a new virtual machine
     that  is independent  of  the AIX  virtual machine.   The
     virtual machine  is loaded  from the device  specified by
     the input/output  device number (IODN) given  in the iodn
     parameter.

     If iodn  is 0,  then the virtual  machine of  the calling
     process is restarted (re-IPLed).  This is accomplished by
     sending a SIGQUIT signal to the process 1.  (Process 1 is
     also  called the  init process.   See "Creation  and Exe-
     cution" for more information about this special process.)
     Note that, unlike the  reboot system call, iplvm performs
     a sync  operation and writes  all pending output  to disk
     before restarting the virtual machine.

     If the  waitflag parameter is  a nonzero value,  then the
     iplvm system call waits until the new virtual machine has
     started before  returning to  the calling  process.  This
     allows you to determine whether the virtual machine IPLed
     successfully.  waitflag is ignored  if the iodn parameter
     is 0.

     The waitvm system call waits for the virtual machine that
     was IPLed from the device  specified by iodn to perform a
     virtual machine halt.

     The calling  process must  have an  effective user  ID of
     superuser to perform either system call.

     Return Value

     Upon successful  completion, the iplvm and  waitvm system
     calls return  a value  of 0.  If  iplvm or  waitvm fails,
     then a value of -1 is  returned and errno is set to indi-
     cate the error.

     Diagnostics

     The iplvm and waitvm system calls  fail if one or more of
     the following is true:

     EPERM      The effective  user ID of the  calling process
                is not superuser.

     EIO        The VRM  detected one  of the  following error
                conditions:

                o   Insufficient resources are available.
                o   The IPL diskette needs to be mounted.
                o   The IPL header is not valid.
                o   Error   encountered   while  reading   IPL
                    record.
                o   Duplicate virtual machine ID.
                o   IPL key sequence error.

     ENXIO      The  device specified  by  the iodn  parameter
                does not exist.

     EINVAL     The iodn parameter is not valid.

     EAGAIN     The  maximum number  of  virtual machines  are
                already running.

     Related Information

     In  this  book:   "Creation  and  Execution,"  "reboot,"
     "signal," and  "sync."

     The init command in  AIX Operating System Commands Refer-
     ence.