clone

Clone current process (create new thread)

Declaration

Source position: linux.pp line 217

Description

Clone creates a child process which is a copy of the parent process, just like FpFork does. In difference with Fork, however, the child process shares some parts of it's execution context with its parent, so it is suitable for the implementation of threads: many instances of a program that share the same memory.

When the child process is created, it starts executing the function Func, and passes it Args. The return value of Func is either the explicit return value of the function, or the exit code of the child process.

The sp pointer points to the memory reserved as stack space for the child process. This address should be the top of the memory block to be used as stack.

The Flags determine the behaviour of the Clone call. The low byte of the Flags contains the number of the signal that will be sent to the parent when the child dies. This may be bitwise OR'ed with the following constants:

CLONE_VM

Parent and child share the same memory space, including memory (un)mapped with subsequent mmap calls.

CLONE_FS

Parent and child have the same view of the filesystem; the chroot, chdir and umask calls affect both processes.

CLONE_FILES

the file descriptor table of parent and child is shared.

CLONE_SIGHAND

the parent and child share the same table of signal handlers. The signal masks are different, though.

CLONE_PID

PArent and child have the same process ID.

Clone returns the process ID in the parent process, and -1 if an error occurred.

Errors

On error, -1 is returned to the parent, and no child is created.

sys_eagain

Too many processes are running.

sys_enomem

Not enough memory to create child process.

See also

Example

program TestC{lone};

{$ifdef Linux}
// close is very Linux specific. 1.9.x threading is done via pthreads.

uses
  Linux, Errors, crt;

const
  Ready : Boolean = false;
  aChar : Char    = 'a';

function CloneProc( Arg: Pointer ): LongInt; Cdecl;
begin
  WriteLn('Hello from the clone ',PChar(Arg));
  repeat
    Write(aChar);
    Select(0,0,0,0,600);
  until Ready;
  WriteLn( 'Clone finished.');
  CloneProc := 1;
end;

var
  PID : LongInt;

procedure MainProc;
begin
  WriteLn('cloned process PID: ', PID );
  WriteLn('Press <ESC> to kill ... ' );
  repeat
    Write('.');
    Select(0,0,0,0,300);
    if KeyPressed then
      case ReadKey of
        #27: Ready := true;
        'a': aChar := 'A';
        'A': aChar := 'a';
        'b': aChar := 'b';
        'B': aChar := 'B';
      end;
  until Ready;
  WriteLn('Ready.');
end;

const
  StackSze = 16384;
  theFlags = CLONE_VM+CLONE_FS+CLONE_FILES+CLONE_SIGHAND;
  aMsg     : PChar = 'Oops !';

var
  theStack : Pointer;
  ExitStat : LongInt;

begin
  GetMem(theStack,StackSze);
  PID := Clone(@CloneProc,
               Pointer( LongInt(theStack)+StackSze),
               theFlags,
               aMsg);
  if PID < 0 then
    WriteLn('Error : ', LinuxError, ' when cloning.')
  else
    begin
    MainProc;
    case WaitPID(0,@ExitStat,Wait_Untraced or wait_clone) of
      -1: WriteLn('error:',LinuxError,'; ',StrError(LinuxError));
       0: WriteLn('error:',LinuxError,'; ',StrError(LinuxError));
    else
      WriteLn('Clone exited with: ',ExitStat shr 8);
    end;
    end;
  FreeMem( theStack, StackSze );
{$else}
begin
{$endif}
end.