NXVmSpawn

Spawns an application in a new virtual machine (VM).

Library:LibC
Classification:NKS
Service:NKS Virtual Machine

Syntax

  #include <nks/vm.h>
  
  int NXVmSpawn (
     NXNameSpec_t     *name,
     NXExecEnvSpec_t  *envSpec,
     unsigned long     flags,
     NXVmId_t         *newVm);

Parameters

name

(IN) Specifies the location of the application binary file which runs in the new virtual machine. See NXNameSpec_t.

envSpec

(IN) Specifies the environment of the new VM. See NXExecEnvSpec_t.

flags

(IN) Specifies one or more of the following flags that modify the spawn behavior:

Flag

Value

Description

NX_VM_DETACHED

0x00000001

Creates the VM as detached from the spawner, which prevents it from joining the spawner and prevents the spawner from terminating it with NXVmDestroy.

NX_VM_INHERIT_ENV

0x00000002

Allows the new VM to inherit the spawning application's environment variables. If this flag is set, the envSpec parameter is ignored.

NX_VM_SAME_ADDRSPACE

0x00000004

Spawns the VM in the same address space as a child of the calling VM. This accommodates the Java Virtual Machine and other NLM applications with special needs.
newVm

(OUT) Points to the identifying value of the new virtual machine. If the NX_VM_DETACHED flag is set, it is set to NX_VM_INVALID_ID.

Return Values

If successful, returns zero; otherwise returns a nonzero error code:

Decimal

Hex

Constant

Description

5

0x05

NX_NOMEM

Insufficient memory to spawn the VM.

9

0x09

NX_EINVAL

One or more of the parameters is invalid or incomplete.

Remarks

NXVmSpawn creates a new VM and sets an application to run in it.

  • This spawn interface creates a functional imitation of UNIX-style exec. The start-up (or prelude) code does the I/O redirection wiring, as well as passing argc, argv, and env.

  • The caller must satisfy all memory needs surrounding the elements communicated through the first two arguments (string pointers in argv, env, and the NXStreamSpec_t fields). After the call completes, this memory is no longer accessed and need not remain valid.

WARNING:The NLM spawned by NXVmSpawn must be a LibC based NLM. You cannot spawn a CLib based NLM with NXVmSpawn.

By default, the spawned VM is not detached and is joinable. A valid identity is returned in newVm. If the new virtual machine is set to be detached, a NULL identity is returned in newVm, and it is impossible for the caller to terminate it.

NKS creates an application thread inside the newly spawned virtual machine which calls into the main routine of the application in the VM. This main thread is not bound to its context and is a joinable thread. The main() thread is special in that if this thread “falls off the bottom” of the main routine, VM exit is initiated even if there are other application threads in the VM. If any other thread “falls off the bottom” of the routine specified at the time of creation of the context hosted by the thread, VM exit is not initiated. If the main thread were to call NXThreadExit, only that thread exits. VM tear down is not initiated in this case except if it is the last application thread in the VM, in which case VM tear down will be initiated. In other words, if the main thread calls NXThreadExit and other applications threads exist in the VM, then the VM is not torn down.The main thread is joinable. When it exits using NXThreadExit, another thread in the VM can perform a join operation on it. When the VM exits and no thread has performed a join operation on the main thread, NKS implicitly performs a join operation on it.

By default the new machine is set to run preemptively.

See Also