%
%   $Id$
%   This file is part of the FPC documentation.
%   Copyright (C) 1997, by Michael Van Canneyt
%
%   The FPC documentation is free text; you can redistribute it and/or
%   modify it under the terms of the GNU Library General Public License as
%   published by the Free Software Foundation; either version 2 of the
%   License, or (at your option) any later version.
%
%   The FPC Documentation is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
%   Library General Public License for more details.
%
%   You should have received a copy of the GNU Library General Public
%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
%   Boston, MA 02111-1307, USA. 
%
\chapter{The LINUX unit.}
This chapter describes the LINUX unit for Free Pascal. The unit was written
by Micha\"el van Canneyt. It works only on the Linux operating system.

This chapter is divided in 2 sections:
\begin{itemize}
\item The first section lists all constants, types and variables, as listed
in the interface section of the LINUX unit.
\item The second section describes all procedures and functions in the LINUX
unit.
\end{itemize}

\section{Type, Variable and Constant declarations}

\subsection{Types}
\label{sec:types}
PGlob and TGlob are 2 types used in the \seef{Glob} function:
\begin{verbatim}
PGlob = ^TGlob;
TGlob = record
  Name : PChar;
  Next : PGlob;
  end;
\end{verbatim}
The following types are used in the signal-processing procedures.
\begin{verbatim}
{$Packrecords 1}
SignalHandler   = Procedure ( Sig : Integer);
PSignalHandler  = ^SignalHandler;
SignalRestorer  = Procedure;
PSignalrestorer = ^SignalRestorer;

SigActionRec = Record
  Sa_Handler  : PSignalhandler;
  Sa_Mask     : Longint;
  Sa_flags    : Integer;
  Sa_Restorer : PSignalRestorer;
end;
PSigActionRec = ^SigActionRec;
\end{verbatim}
Stat is used to store information about a file. It is defined in the
syscalls unit.

\begin{verbatim}
  stat = record
     dev    : word;
     pad1   : word;
     ino    : longint;
     mode   : word;
     nlink  : word;
     uid    : word;
     gid    : word;
     rdev   : word;
     pad2   : word;
     size   : longint;
     blksze : Longint;
     blocks : Longint;
     atime  : Longint;
     unused1 : longint;
     mtime   : Longint;
     unused2 : longint;
     ctime   : Longint;
     unused3 : longint;
     unused4 : longint;
     unused5 : longint;
     end;
 \end{verbatim}

Statfs is used to store information about a filesystem. It is defined in
the syscalls unit.
\begin{verbatim}

   statfs = record
     fstype   : longint;
     bsize    : longint;
     blocks   : longint;
     bfree    : longint;
     bavail   : longint;
     files    : longint;
     ffree    : longint;
     fsid     : longint;
     namelen  : longint; 
     spare    : array [0..6] of longint;
     end
\end{verbatim}
\var{Dir and PDir} are used in the \seef{OpenDir} and \seef{ReadDir}
functions. 
\begin{verbatim}
  TDir =record
    fd     : integer;
    loc    : longint;
    size   : integer;
    buf    : pdirent;
    nextoff: longint;
    dd_max : integer; 
    lock   : pointer;
  end;
  PDir =^TDir;
\end{verbatim}
\var{Dirent, PDirent} are used in the \seef{ReadDir} function to return files in a directory.
\begin{verbatim}
 PDirent = ^Dirent;
 Dirent = Record  
   ino,
   off    : longint;
   reclen : word;
   name   : string[255]
 end; 
\end{verbatim}
Termio and Termios are used with iotcl() calls for terminal handling.
\begin{verbatim}
Const  NCCS = 19;
       NCC = 8;
         
Type termio = record
	c_iflag,		{ input mode flags }
	c_oflag,		{ output mode flags }
	c_cflag,		{ control mode flags }
	c_lflag : Word;		{ local mode flags }
	c_line : Word;		{ line discipline - careful, only High byte in use}
	c_cc : array [0..NCC-1] of char;	{ control characters }
end;

termios = record
  c_iflag,              { input mode flags }
  c_oflag,              { output mode flags }
  c_cflag,              { control mode flags }
  c_lflag : Cardinal;	{ local mode flags }
  c_line : char;          { line discipline }
  c_cc : array [0..NCCS-1] of char;      { control characters }
end;
\end{verbatim}
\var{Utimbuf} is used in the \seef{Utime} call to set access and modificaton time
of a file.
\begin{verbatim}
utimbuf = record
  actime,modtime : Longint;
  end;
\end{verbatim}
For the \seef{Select} call, the following 4 types are needed:
\begin{verbatim}
FDSet = Array [0..31] of longint;
PFDSet = ^FDSet;

TimeVal = Record
   sec,usec : Longint;
end;
PTimeVal = ^TimeVal;
\end{verbatim}
The \seep{Uname} function uses the \var{utsname} to return information about
the current kernel :
\begin{verbatim}
utsname =record
  sysname,nodename,release,
  version,machine,domainname : Array[0..64] of char;
end;
\end{verbatim}
Its elements are null-terminated C style strings, you cannot access them
directly !

\subsection{Variables}
\var{Linuxerror} is the variable in which the procedures in the linux unit
report errors.
\begin{verbatim}
LinuxError : Longint;
\end{verbatim}
\var{StdErr} Is a \var{Text} variable, corresponding to Standard Error or
diagnostic output. It is connected to file descriptor 2. It can be freely
used, and will be closed on exit.
\begin{verbatim}
StdErr : Text;
\end{verbatim}

\subsection{Constants}
Constants for setting/getting process priorities :
\begin{verbatim}
      Prio_Process = 0;
      Prio_PGrp    = 1;
      Prio_User    = 2;
\end{verbatim}
For testing  access rights:
\begin{verbatim}
      R_OK = 4; 
      W_OK = 2;
      X_OK = 1;
      F_OK = 0;
\end{verbatim}
For signal handling functions :
\begin{verbatim}
      SA_NOCLDSTOP = 1;
      SA_SHIRQ	   = $04000000;
      SA_STACK	   = $08000000;      
      SA_RESTART   = $10000000;
      SA_INTERRUPT = $20000000;
      SA_NOMASK	   = $40000000;
      SA_ONESHOT   = $80000000;
      
      SIG_BLOCK	  = 0;
      SIG_UNBLOCK = 1;
      SIG_SETMASK = 2;

      SIG_DFL = 0 ;
      SIG_IGN = 1 ;
      SIG_ERR = -1;
      
      SIGHUP		= 1;
      SIGINT		= 2;
      SIGQUIT		= 3;
      SIGILL		= 4;
      SIGTRAP		= 5;
      SIGABRT		= 6;
      SIGIOT		= 6;
      SIGBUS		= 7;
      SIGFPE		= 8;
      SIGKILL		= 9;
      SIGUSR1		= 10;
      SIGSEGV		= 11;
      SIGUSR2		= 12;
      SIGPIPE		= 13;
      SIGALRM		= 14;
      SIGTERM		= 15;
      SIGSTKFLT		= 16;
      SIGCHLD		= 17;
      SIGCONT		= 18;
      SIGSTOP		= 19;
      SIGTSTP		= 20;
      SIGTTIN		= 21;
      SIGTTOU		= 22;
      SIGURG		= 23;
      SIGXCPU		= 24;
      SIGXFSZ		= 25;
      SIGVTALRM		= 26;
      SIGPROF		= 27;
      SIGWINCH		= 28;
      SIGIO		= 29;
      SIGPOLL		= SIGIO;
      SIGPWR		= 30;
      SIGUNUSED		= 31;
\end{verbatim}
For file control mechanism :
\begin{verbatim}
      F_GetFd  = 1;
      F_SetFd  = 2;
      F_GetFl  = 3;
      F_SetFl  = 4;
      F_GetLk  = 5;
      F_SetLk  = 6;
      F_SetLkW = 7;
      F_GetOwn = 8;
      F_SetOwn = 9;
\end{verbatim}
For Terminal handling :
\begin{verbatim}
   TCGETS	= $5401 ;
   TCSETS	= $5402 ;
   TCSETSW	= $5403 ;
   TCSETSF	= $5404 ;
   TCGETA	= $5405 ;
   TCSETA	= $5406 ;
   TCSETAW	= $5407 ;
   TCSETAF	= $5408 ;
   TCSBRK	= $5409 ;
   TCXONC	= $540A ;
   TCFLSH	= $540B ;
   TIOCEXCL	= $540C ;
   TIOCNXCL	= $540D ;
   TIOCSCTTY	= $540E ;
   TIOCGPGRP	= $540F ;
   TIOCSPGRP	= $5410 ;
   TIOCOUTQ	= $5411 ;
   TIOCSTI	= $5412 ;
   TIOCGWINSZ	= $5413 ;
   TIOCSWINSZ	= $5414 ;
   TIOCMGET	= $5415 ;
   TIOCMBIS	= $5416 ;
   TIOCMBIC	= $5417 ;
   TIOCMSET	= $5418 ;
   TIOCGSOFTCAR	= $5419 ;
   TIOCSSOFTCAR	= $541A ;
   FIONREAD	= $541B ;
   TIOCINQ	= FIONREAD;
   TIOCLINUX	= $541C ;
   TIOCCONS	= $541D ;
   TIOCGSERIAL	= $541E ;
   TIOCSSERIAL	= $541F ;
   TIOCPKT	= $5420 ;
   FIONBIO	= $5421 ;
   TIOCNOTTY	= $5422 ;
   TIOCSETD	= $5423 ;
   TIOCGETD	= $5424 ;
   TCSBRKP		= $5425	 ;
   TIOCTTYGSTRUCT	= $5426  ;
   FIONCLEX	= $5450  ;
   FIOCLEX		= $5451 ;
   FIOASYNC	= $5452 ;
   TIOCSERCONFIG	= $5453 ;
   TIOCSERGWILD	= $5454 ;
   TIOCSERSWILD	= $5455 ;
   TIOCGLCKTRMIOS	= $5456 ;
   TIOCSLCKTRMIOS	= $5457 ;
   TIOCSERGSTRUCT	= $5458  ;
   TIOCSERGETLSR   = $5459  ;
   TIOCSERGETMULTI = $545A  ;
   TIOCSERSETMULTI = $545B  ;

   TIOCMIWAIT	= $545C	;
   TIOCGICOUNT	= $545D	;

   TIOCPKT_DATA		= 0;
   TIOCPKT_FLUSHREAD	= 1;
   TIOCPKT_FLUSHWRITE	= 2;
   TIOCPKT_STOP		= 4;
   TIOCPKT_START	= 8;
   TIOCPKT_NOSTOP	= 16;
   TIOCPKT_DOSTOP	= 32;
\end{verbatim}
Other than that, all constants for setting the speed and control flags of a
terminal line, as described in the \seem{termios}{2} man
page, are defined in the linux unit. It would take too much place to list
them here. 

To check the \var{mode} field of a \var{stat} record, you ca use the
following constants :
\begin{verbatim}
  { Constants to check stat.mode }
  STAT_IFMT   = $f000; {00170000}
  STAT_IFSOCK = $c000; {0140000}
  STAT_IFLNK  = $a000; {0120000}
  STAT_IFREG  = $8000; {0100000}
  STAT_IFBLK  = $6000; {0060000}
  STAT_IFDIR  = $4000; {0040000}
  STAT_IFCHR  = $2000; {0020000}
  STAT_IFIFO  = $1000; {0010000}
  STAT_ISUID  = $0800; {0004000}
  STAT_ISGID  = $0400; {0002000}
  STAT_ISVTX  = $0200; {0001000}
  { Constants to check permissions }
  STAT_IRWXO = $7;
  STAT_IROTH = $4;
  STAT_IWOTH = $2;
  STAT_IXOTH = $1;

  STAT_IRWXG = STAT_IRWXO shl 3;
  STAT_IRGRP = STAT_IROTH shl 3;
  STAT_IWGRP = STAT_IWOTH shl 3;
  STAT_IXGRP = STAT_IXOTH shl 3;

  STAT_IRWXU = STAT_IRWXO shl 6;
  STAT_IRUSR = STAT_IROTH shl 6;
  STAT_IWUSR = STAT_IWOTH shl 6;
  STAT_IXUSR = STAT_IXOTH shl 6;
\end{verbatim}
You can test the type of a filesystem returned by a \seef{FSStat} call with
the following constants:
\begin{verbatim}
  fs_old_ext2 = $ef51;
  fs_ext2     = $ef53;
  fs_ext      = $137d;
  fs_iso      = $9660;
  fs_minix    = $137f;
  fs_minix_30 = $138f;
  fs_minux_V2 = $2468;
  fs_msdos    = $4d44;
  fs_nfs      = $6969;
  fs_proc     = $9fa0;
  fs_xia      = $012FD16D;
\end{verbatim}


\section{Functions and procedures}

%\function{Name}{arguments}{return type}{explain}{errors}{refs}
%\procedure{Name}{arguments}{explain}{errors}{refs}
%\function{}{()}{}{}{}{}{}
%\procedure{}{}{}{}{}{}
\function{GetEpochTime}{}{longint}
{
returns the number of seconds since 00:00:00 gmt, january 1, 1970.
it is adjusted to the local time zone, but not to DST.
}
{no errors}
{\seep{EpochToLocal}, \seep{GetTime}, \seem{time}{2}}

\input{linuxex/ex1.tex}

\procedure
{EpochToLocal}
{(Epoch : Longint; var Year,Month,Day,Hour,Minute,Second : Word)}
{
Converts the epoch time (=Number of seconds since 00:00:00 , January 1,
1970, corrected for your time zone ) to local date and time.
}
{None}
{\seef{GetEpochTime}, \seef{LocalToEpoch}, \seep{GetTime},\seep{GetDate} }

\input{linuxex/ex3.tex}

\function{LocalToEpoch}{(Year,Month,Day,Hour,Minute,Second : Word)}{longint}
{
Converts the Local time to epoch time (=Number of seconds since 00:00:00 , January 1,
1970 ).
}
{None}
{\seef{GetEpochTime}, \seep{EpochToLocal}, \seep{GetTime},\seep{GetDate} }

\input{linuxex/ex4.tex}

\procedure{GetTime}
{ (Var Hour,Minute, Second : Word) }
{
Returns the current time of the day.
}
{None}
{\seef{GetEpochTime}, \seep{GetDate}, \seep{EpochToLocal} }

\input{linuxex/ex5.tex}

\procedure{GetDate}
{ (Var Year, Month, Day : Word) }
{
Returns the current day.
}
{None}
{\seef{GetEpochTime}, \seep{GetTime}, \seep{EpochToLocal} }

\input{linuxex/ex6.tex}

\procedure{Execve}
{(Path : pathstr; args,ep : ppchar)}
{
Replaces the currently running program with the program, specified in
\var{path}.
It gives the program the options in \var{args}, and the environment in
\var{ep}. They are pointers to an array of pointers to null-terminated
strings. The last pointer in this array should be nil.

On success, \var{execve} does not return.
}
{Errors are reported in \var{LinuxError}:
\begin{description}
\item[eacces] File is not a regular file, or has no execute permission.
A compononent of the path has no search permission.
\item[sys\_ eperm] The file system is mounted \textit{noexec}.
\item[sys\_ e2big] Argument list too big.
\item[sys\_ enoexec] The magic number in the file is incorrect.
\item[sys\_ enoent] The file does not exist.
\item[sys\_ enomem] Not enough memory for kernel.
\item[sys\_ enotdir] A component of the path is not a directory.
\item[sys\_ eloop] The path contains a circular reference (via symlinks).
\end{description}}
{\seep{Execve}, \seep{Execv}, \seep{Execvp} \seep{Execle},
\seep{Execl}, \seep{Execlp}, \seef {Fork}, \seem{execve}{2} }

\input{linuxex/ex7.tex}

\procedure{Execv}
{(Path : pathstr; args : ppchar)}
{
Replaces the currently running program with the program, specified in
\var{path}.
It gives the program the options in \var{args}.
This is a pointer to an array of pointers to null-terminated
strings. The last pointer in this array should be nil.
The current environment is passed to the program.

On success, \var{execv} does not return.
}
{Errors are reported in \var{LinuxError}:
\begin{description}
\item[sys\_eacces] File is not a regular file, or has no execute permission.
A compononent of the path has no search permission.
\item[sys\_eperm] The file system is mounted \textit{noexec}.
\item[sys\_e2big] Argument list too big.
\item[sys\_enoexec] The magic number in the file is incorrect.
\item[sys\_enoent] The file does not exist.
\item[sys\_enomem] Not enough memory for kernel.
\item[sys\_enotdir] A component of the path is not a directory.
\item[sys\_eloop] The path contains a circular reference (via symlinks).
\end{description}}
{\seep{Execve}, \seep{Execvp}, \seep{Execle},
\seep{Execl}, \seep{Execlp}, \seef {Fork}, \seem{execv}{3} }

\input{linuxex/ex8.tex}

\procedure{Execvp}
{(Path : pathstr; args : ppchar)}
{
Replaces the currently running program with the program, specified in
\var{path}. The executable in \var{path} is searched in the path, if it isn't
an absolute filename.
It gives the program the options in \var{args}. This is a pointer to an array of pointers to null-terminated
strings. The last pointer in this array should be nil.
The current environment is passed to the program.

On success, \var{execvp} does not return.
}
{Errors are reported in \var{LinuxError}:
\begin{description}
\item[sys\_eacces] File is not a regular file, or has no execute permission.
A compononent of the path has no search permission.
\item[sys\_eperm] The file system is mounted \textit{noexec}.
\item[sys\_e2big] Argument list too big.
\item[sys\_enoexec] The magic number in the file is incorrect.
\item[sys\_enoent] The file does not exist.
\item[sys\_enomem] Not enough memory for kernel.
\item[sys\_enotdir] A component of the path is not a directory.
\item[sys\_eloop] The path contains a circular reference (via symlinks).
\end{description}}
{\seep{Execve}, \seep{Execv}, \seep{Execle},
\seep{Execl}, \seep{Execlp}, \seef {Fork}, \seem{execvp}{3} }

\input{linuxex/ex9.tex}

\procedure{Execl}
{(Path : pathstr)}
{
Replaces the currently running program with the program, specified in
\var{path}. Path is split into a command and it's options.
The executable in \var{path} is NOT searched in the path.
The current environment is passed to the program.

On success, \var{execl} does not return.
}
{Errors are reported in \var{LinuxError}:
\begin{description}
\item[sys\_eacces] File is not a regular file, or has no execute permission.
A compononent of the path has no search permission.
\item[sys\_eperm] The file system is mounted \textit{noexec}.
\item[sys\_e2big] Argument list too big.
\item[sys\_enoexec] The magic number in the file is incorrect.
\item[sys\_enoent] The file does not exist.
\item[sys\_enomem] Not enough memory for kernel, or to split command line.
\item[sys\_enotdir] A component of the path is not a directory.
\item[sys\_eloop] The path contains a circular reference (via symlinks).
\end{description}}
{\seep{Execve}, \seep{Execv}, \seep{Execvp}, \seep{Execle},
 \seep{Execlp}, \seef {Fork}, \seem{execvp}{3} }

\input{linuxex/ex10.tex}

\procedure{Execle}
{(Path : pathstr, Ep : ppchar)}
{
Replaces the currently running program with the program, specified in
\var{path}. Path is split into a command and it's options.
The executable in \var{path} is searched in the path, if it isn't
an absolute filename.
The environment in \var{ep} is passed to the program.

On success, \var{execle} does not return.
}
{Errors are reported in \var{LinuxError}:
\begin{description}
\item[sys\_eacces] File is not a regular file, or has no execute permission.
A compononent of the path has no search permission.
\item[sys\_eperm] The file system is mounted \textit{noexec}.
\item[sys\_e2big] Argument list too big.
\item[sys\_enoexec] The magic number in the file is incorrect.
\item[sys\_enoent] The file does not exist.
\item[sys\_enomem] Not enough memory for kernel, or to split command line.
\item[sys\_enotdir] A component of the path is not a directory.
\item[sys\_eloop] The path contains a circular reference (via symlinks).
\end{description}}
{\seep{Execve}, \seep{Execv}, \seep{Execvp},
\seep{Execl}, \seep{Execlp}, \seef {Fork}, \seem{execvp}{3} }

\input{linuxex/ex11.tex}

\procedure{Execlp}
{(Path : pathstr)}
{
Replaces the currently running program with the program, specified in
\var{path}. Path is split into a command and it's options.
The executable in \var{path} is searched in the path, if it isn't
an absolute filename.
The current environment is passed to the program.

On success, \var{execlp} does not return.
}
{Errors are reported in \var{LinuxError}:
\begin{description}
\item[sys\_eacces] File is not a regular file, or has no execute permission.
A compononent of the path has no search permission.
\item[sys\_eperm] The file system is mounted \textit{noexec}.
\item[sys\_e2big] Argument list too big.
\item[sys\_enoexec] The magic number in the file is incorrect.
\item[sys\_enoent] The file does not exist.
\item[sys\_enomem] Not enough memory for kernel, or to split command line.
\item[sys\_enotdir] A component of the path is not a directory.
\item[sys\_eloop] The path contains a circular reference (via symlinks).
\end{description}}
{\seep{Execve}, \seep{Execv}, \seep{Execvp}, \seep{Execle},
\seep{Execl}, \seef {Fork}, \seem{execvp}{3} }

\input{linuxex/ex12.tex}

\function{Fork}{}{Longint}
{
Fork creates a child process which is a copy of the parent process.

Fork returns the process ID in the parent process, and zero in the child's
process. (you can get the parent's PID with \seef{GetPPid}).
}
{On error, -1 is returned to the parent, and no child is created.
\begin{description}
\item [sys\_eagain] Not enough memory to create child process.
\end{description}
}
{\seep{Execve}, \seem{fork}{2}}

\input{linuxex/ex14.tex}

\procedure{Nice}{( N : Integer)}
{Nice adds \var{-N} to the priority of the running process. The lower the
priority numerically, the less the process is favored.

Only the superuser can specify a negative \var{N}, i.e. increase the rate at
which the process is run.
}
{ Errors are returned in \var{LinuxError}
\begin{description}
\item [sys\_eperm] A non-superuser tried to specify a negative \var{N}, i.e.
do a priority increase.
\end{description}
}{\seef{GetPriority}, \seef{SetPriority}, \seem{Nice}{2}}

\input{linuxex/ex15.tex}

\function{GetPriority}{(Which,Who : Integer)}{Integer}
{
GetPriority returns the priority with which a process is running.
Which process(es) is determined by the \var{Which} and \var{Who} variables.
\var{Which} can be one of the pre-defined \var{Prio\_Process, Prio\_PGrp,
Prio\_User}, in which case \var{Who} is the process ID, Process group ID or
User ID, respectively.
}
{
 Error checking must be done on LinuxError, since a priority can be negative.
 \begin{description}
 \item[sys\_esrch] No process found using \var{which} and \var{who}.
 \item[sys\_einval] \var{Which} was not one of \var{Prio\_Process, Prio\_Grp
or Prio\_User}.
 \end{description}
 }
{\seef{SetPriority}, \seep{Nice}, \seem{Getpriority}{2}}

For an example, see \seep{Nice}.

\function{SetPriority}{(Which,Who,Prio : Integer)}{Integer}
{
SetPriority sets the priority with which a process is running.
Which process(es) is determined by the \var{Which} and \var{Who} variables.
\var{Which} can be one of the pre-defined \var{Prio\_Process, Prio\_PGrp,
Prio\_User}, in which case \var{Who} is the process ID, Process group ID or
User ID, respectively.

\var{Prio} is a value in the range -20 to 20.
}
{
 Error checking must be done on LinuxError, since a priority can be negative.
 \begin{description}
 \item[sys\_esrch] No process found using \var{which} and \var{who}.
 \item[sys\_einval] \var{Which} was not one of \var{Prio\_Process, Prio\_Grp
or Prio\_User}.
 \item[sys\_eperm] A process was found, but neither its effective or real
 user ID match the effective user ID of the caller.
 \item [sys\_eacces] A non-superuser tried to a priority increase.
 \end{description}
 }
{\seef{GetPriority}, \seep{Nice}, \seem{Setpriority}{2}}

For an example, see \seep{Nice}.

\function{GetPid}{}{Longint}
{ Get the Process ID of the currently running process.}
{None.}
{\seef{GetPPid}, \seem{getpid}{2}}

\input{linuxex/ex16.tex}


\function{GetPPid}{}{Longint}
{ Get the Process ID of the parent process.}
{None.}
{\seef{GetPid}, \seem{getppid}{2}}

\input{linuxex/ex16.tex}

\function{GetUid}{}{Longint}
{ Get the real user ID of the currently running process.}
{None.}
{\seef{GetEUid}, \seem{getuid}{2} }

\input{linuxex/ex17.tex}

\function{GetEUid}{}{Longint}
{ Get the effective user ID of the currently running process.}
{None.}
{\seef{GetEUid}, \seem{geteuid}{2} }

\input{linuxex/ex17.tex}

\function{GetGid}{}{Longint}
{ Get the real group ID of the currently running process.}
{None.}
{\seef{GetEGid}, \seem{getgid}{2} }

\input{linuxex/ex18.tex}

\function{GetEGid}{}{Longint}
{ Get the effective group ID of the currently running process.}
{None.}
{\seef{GetGid}, \seem{getegid}{2} }

\input{linuxex/ex18.tex}

\function{Link}{(OldPath,NewPath : pathstr)}{Boolean}
{\var{Link} makes \var{NewPath} point to the same file als \var{OldPath}. The two files
then have the same inode number. This is known as a 'hard' link.

The function returns \var{True} if the call was succesfull, \var{False} if the call
failed.
}
{ Errors are returned in \var{LinuxError}.
\begin{description}
\item[sys\_exdev] \var {OldPath} and \var {NewPath} are not on the same
filesystem.
\item[sys\_eperm] The filesystem containing oldpath and newpath doesn't
support linking files.
\item[sys\_eaccess] Write access for the directory containing \var{Newpath}
is disallowed, or one of the directories in \var{OldPath} or {NewPath} has no
search (=execute) permission.
\item[sys\_enoent] A directory entry in \var{OldPath} or \var{NewPath} does
not exist or is a symbolic link pointing to a non-existent directory.
\item[sys\_enotdir] A directory entry in \var{OldPath} or \var{NewPath} is
nor a directory.
\item[sys\_enomem] Insufficient kernel memory.
\item[sys\_erofs] The files are on a read-only filesystem.
\item[sys\_eexist] \var{NewPath} already exists.
\item[sys\_emlink] \var{OldPath} has reached maximal link count.
\item[sys\_eloop] \var{OldPath} or \var{NewPath} has a reference to a circular
symbolic link, i.e. a symbolic link, whose expansion points to itself.
\item[sys\_enospc] The device containing \var{NewPath} has no room for anothe
entry.
\item[sys\_eperm] \var{OldPath} points to . or .. of a directory.
\end{description}
}
{\seef{SymLink}, \seef{UnLink}, \seem{Link}{2} }

\input{linuxex/ex21.tex}

\function{SymLink}{(OldPath,NewPath : pathstr)}{Boolean}
{\var{SymLink} makes \var{Newpath} point to the file in \var{OldPath}, which doesn't
necessarily exist. The two files DO NOT have the same inode number.
This is known as a 'soft' link.
The permissions of the link are irrelevant, as they are not used when
following the link. Ownership of the file is only checked in case of removal
or renaming of the link.

The function returns \var{True} if the call was succesfull, \var{False} if the call
failed.
}
{ Errors are returned in \var{LinuxError}.
\begin{description}
\item[sys\_eperm] The filesystem containing oldpath and newpath doesn't
support linking files.
\item[sys\_eaccess] Write access for the directory containing \var{Newpath}
is disallowed, or one of the directories in \var{OldPath} or {NewPath} has no
search (=execute) permission.
\item[sys\_enoent] A directory entry in \var{OldPath} or \var{NewPath} does
not exist or is a symbolic link pointing to a non-existent directory.
\item[sys\_enotdir] A directory entry in \var{OldPath} or \var{NewPath} is
nor a directory.
\item[sys\_enomem] Insufficient kernel memory.
\item[sys\_erofs] The files are on a read-only filesystem.
\item[sys\_eexist] \var{NewPath} already exists.
\item[sys\_eloop] \var{OldPath} or \var{NewPath} has a reference to a circular
symbolic link, i.e. a symbolic link, whose expansion points to itself.
\item[sys\_enospc] The device containing \var{NewPath} has no room for anothe
entry.
\end{description}
}
{\seef{Link}, \seef{UnLink}, \seem{Symlink}{2} }

\input{linuxex/ex22.tex}

\function{UnLink}{(Path : pathstr)}{Boolean}
{
\var{UnLink} decreases the link count on file \var{Path}. If the link count is zero, the
file is removed from the disk.

The function returns \var{True} if the call was succesfull, \var{False} if the call
failed.
}
{ Errors are returned in \var{LinuxError}.
\begin{description}
\item[sys\_eaccess] You have no write access right in the directory
containing \var{Path}, or you have no search permission in one of the
directory components of \var{Path}.
\item[sys\_eperm] The  directory containing pathname has the sticky-bit 
set and the process's effective  uid is neither the uid of the 
file to be deleted nor that of the directory containing it.
\item[sys\_enoent] A component of the path doesn't exist.
\item[sys\_enotdir] A directory component of the path is not a directory.
\item[sys\_eisdir] \var{Path} refers to a directory.
\item[sys\_enomem] Insufficient kernel memory.
\item[sys\_erofs] \var{Path} is on a read-only filesystem. 
\end{description}
}
{\seef{Link}, \seef{SymLink}, \seem{Unlink}{2} }

For an example, see \seef{Link}.

\function{Chown}{(Path : Pathstr;NewUid,NewGid : Longint)}{Boolean}
{ \var{Chown} sets the User ID and Group ID of the file in \var{Path} to \var{NewUid,
NewGid}.

The function returns \var{True} if the call was succesfull, \var{False} if the call
failed.
}
{
Errors are returned in \var{LinuxError}.
\begin{description}
\item[sys\_eperm] The effective UID doesn't match the ownership of the file,
and is not zero. Owner or group were not specified correctly.
\item[sys\_eaccess] One of the directories in \var{Path} has no
search (=execute) permission.
\item[sys\_enoent] A directory entry in \var{Path} does
not exist or is a symbolic link pointing to a non-existent directory.
\item[sys\_enotdir] A directory entry in \var{OldPath} or \var{NewPath} is
nor a directory.
\item[sys\_enomem] Insufficient kernel memory.
\item[sys\_erofs] The file is on a read-only filesystem.
\item[sys\_eloop] \var{Path} has a reference to a circular
symbolic link, i.e. a symbolic link, whose expansion points to itself.
\end{description}
}
{\seef{Chmod}, \seef{Access}, \seem{Chown}(2)}

\input{linuxex/ex24.tex}

\function{Chmod}{(Path : Pathstr;NewMode : Longint)}{Boolean}
{ \var{Chmod}
Sets the Mode bits of the file in \var{Path} to \var{NewMode}. Newmode can be
specified by 'or'-ing the following:
\begin{description}
\item[S\_ISUID] Set user ID on execution.
\item[S\_ISGID] Set Group ID on execution.
\item[S\_ISVTX] Set sticky bit.
\item[S\_IRUSR] Read by owner.
\item[S\_IWUSR] Write by owner.
\item[S\_IXUSR] Execute by owner.
\item[S\_IRGRP] Read by group.
\item[S\_IWGRP] Write by group.
\item[S\_IXGRP] Execute by group.
\item[S\_IROTH] Read by others.
\item[S\_IWOTH] Write by others.
\item[S\_IXOTH] Execute by others.
\item[S\_IRWXO] Read, write, execute by others.
\item[S\_IRWXG] Read, write, execute by groups.
\item[S\_IRWXU] Read, write, execute by user.
\end{description}
}
{
Errors are returned in \var{LinuxError}.
\begin{description}
\item[sys\_eperm] The effective UID doesn't match the ownership of the file,
and is not zero. Owner or group were not specified correctly.
\item[sys\_eaccess] One of the directories in \var{Path} has no
search (=execute) permission.
\item[sys\_enoent] A directory entry in \var{Path} does
not exist or is a symbolic link pointing to a non-existent directory.
\item[sys\_enotdir] A directory entry in \var{OldPath} or \var{NewPath} is
nor a directory.
\item[sys\_enomem] Insufficient kernel memory.
\item[sys\_erofs] The file is on a read-only filesystem.
\item[sys\_eloop] \var{Path} has a reference to a circular
symbolic link, i.e. a symbolic link, whose expansion points to itself.
\end{description}
}
{\seef{Chown}, \seef{Access}, \seem{Chmod}(2)}

\input{linuxex/ex23.tex}

\function{Utime}{(path : pathstr; utim : utimbuf)}{Boolean}
{
\var{Utime} sets the access and modification times of a file.
the \var{utimbuf} record contains 2 fields, \var{actime}, and \var{modtime},
both of type Longint. They should be filled with an epoch-like time,
specifying, respectively, the last access time, and the last modification
time. 

For some filesystem (most notably, FAT), these times are the same. 
}
{Errors are returned in \var{LinuxError}.
\begin{description}
\item[sys\_eaccess] One of the directories in \var{Path} has no
search (=execute) permission.
\item[sys\_enoent] A directory entry in \var{Path} does
not exist or is a symbolic link pointing to a non-existent directory.
\end{description}
Other errors may occur, but aren't documented.
}
{\seef{GetEpochTime}, \seef{Chown}, \seef{Access}, \seem{utime}(2)}

\input{linuxex/ex25.tex}

\function{Umask}{(Mask : Integer)}{Integer}
{
Change the file creation mask for the current user to \var{Mask}. The
current mask is returned.
}
{None}
{\seef{Chmod}, \seem{Umask}{2}}

\input{linuxex/ex27.tex}

\function{Access}{(Path : Pathstr; Mode : integer)}{Boolean}
{
Tests user's access rights on the specified file. Mode is a mask existing of
one or more of
\begin{description}
\item[R\_OK] User has read rights.
\item[W\_OK] User has write rights.
\item[X\_OK] User has execute rights.
\item[F\_OK] User has search rights in the directory where the file is.
\end{description}
The test is done with the real user ID, instead of the effective user ID.

If access is denied, or an error occurred, false is returned.
}
{ \var{LinuxError} is used to report errors:
\begin{description}
\item[sys\_eaccess] The requested access is denied, either to the file or one
of the directories in its path.
\item[sys\_einval] \var{Mode} was incorrect.
\item[sys\_enoent] A directory component in \var{Path} doesn't exist or is a
dangling symbolic link.
\item[sys\_enotdir] A directory component in \var{Path} is not a directory.
\item[sys\_enomem] Insufficient kernel memory.
\item[sys\_eloop] \var{Path} has a circular symbolic link.
\end{description}
}
{\seef{Chown}, \seef{Chmod}, \seem{Access}{2} }

\input{linuxex/ex26.tex}

\function{FStat}{(Path : Pathstr; Var Info : stat)}{Boolean}
{
\var{FStat} gets information about the file specified in \var{Path}, and stores it in 
\var{Info}, which is of type \var{stat}.

The function returns \var{True} if the call was succesfull, \var{False} if the call
failed.
}
{ \var{LinuxError} is used to report errors.
\begin{description}
\item[sys\_enoent] \var{Path} does not exist.
\end{description}
}
{\seef{FSStat}, \seef{LStat}, \seem{stat}{2}}

\input{linuxex/ex28.tex}

\function{LStat}{(Path : Pathstr; Var Info : stat)}{Boolean}
{
\var{LStat} gets information about the link specified in \var{Path}, and stores it in 
\var{Info}, which is of type \var{stat}. Contrary to \var{FStat}, it stores
information about the link, not about the file the link points to.

The function returns \var{True} if the call was succesfull, \var{False} if the call
failed.
}
{ \var{LinuxError} is used to report errors.
\begin{description}
\item[sys\_enoent] \var{Path} does not exist.
\end{description}
}
{\seef{FStat}, \seef{FSStat}, \seem{stat}{2}}

\input{linuxex/ex29.tex}

\function{FSStat}{(Path : Pathstr; Var Info : statfs)}{Boolean}
{ Return in \var{Info} information about the filesystem on which the file
\var{Path} resides. Info is of type \var{statfs}.

The function returns \var{True} if the call was succesfull, \var{False} if the call
failed.
}
{ \var{LinuxError} is used to report errors.
\begin{description}
\item[sys\_enotdir] A component of \var{Path} is not a directory.
\item[sys\_einval] Invalid character in \var{Path}.
\item[sys\_enoent] \var{Path} does not exist.
\item[sys\_eaccess] Search permission is denied for  component in
\var{Path}.
\item[sys\_eloop] A circular symbolic link was encountered in \var{Path}.
\item[sys\_eio] An error occurred while reading from the filesystem.
\end{description}
}
{\seef{FStat}, \seef{LStat}, \seem{statfs}{2}}

\input{linuxex/ex30.tex}

\procedure{IOCtl}{(Handle,Ndx: Longint; Data: Pointer)}
{
This is a general interface to the Unix/ \linux ioctl call.
It performs various operations on the filedescriptor \var{Handle}.
\var{Ndx} describes the operation to perform.
\var{Data} points to data needed for the \var{Ndx} function. 
The structure of this data is function-dependent, so we don't elaborate on
this here. 

For more information on this, see various manual pages under linux.
}
{
Errors are reported in LinuxError. They are very dependent on the used
function, that's why we don't list them here
}
{\seem{ioctl}{2}}

\input{linuxex/ex54.tex}

\function{IsATTY}{(var f)}{Boolean};
{
Check if the filehandle described by \var{f} is a terminal.
f can be of type
\begin{enumerate}
\item \var{longint} for file handles;
\item \var{Text} for \var{text} variables such as \var{input} etc.
\end{enumerate}

Returns \var{True} if \var{f} is a terminal, \var{False} otherwise.
}
{No errors are reported}
{\seep{IOCtl},\seef{TTYName}}

\function{TTYName}{(var f)}{String}
{
Returns the name of the terminal pointed to by \var{f}. \var{f}
must be a terminal. \var{f} can be of type:
\begin{enumerate}
\item \var{longint} for file handles;
\item \var{Text} for \var{text} variables such as \var{input} etc.
\end{enumerate}
}
{ Returns an empty string in case of an error. \var{Linuxerror} may be set
 to indicate what error occurred, but this is uncertain.}
{\seef{IsATTY},\seep{IOCtl}}

\function{FExpand}{(Const Path: Pathstr)}{pathstr}
{ Expands \var {Path} to a full path, starting from root,
eliminating directory references such as . and .. from the result.
}
{None}
{\seef{BaseName},\seef{DirName} }

\input{linuxex/ex45.tex}

\function{FSearch}{(Path : pathstr;DirList : string)}{Pathstr}
{ Searches in \var{DirList}, a colon separated list of directories,
for a file named \var{Path}. It then returns a path to the found file.}
{An empty string if no such file was found.}
{\seef{BaseName}, \seef{DirName}, \seef{FExpand} }

\input{linuxex/ex46.tex}

\function{BaseName}{(Const Path;Suf : Pathstr)}{Pathstr}
{Returns the filename part of \var{Path}, stripping off \var{Suf} if it
exists.

The filename part is the whole name if \var{Path} contains no slash,
or the part of \var{Path} after the last slash.

The last character of the result is not a slash, unless the directory is the
root directory.
}
{None.}
{\seef{DirName}, \seef{FExpand}, \seem{Basename}{1}}

\input{linuxex/ex48.tex}

\function{DirName}{(Const Path : Pathstr)}{Pathstr}
{Returns the directory part of \var{Path}.

The directory is the part of \var{Path} before the last slash,
or empty if there is no slash.

The last character of the result is not a slash, unless the directory is the
root directory.
}
{None.}
{\seef{BaseName}, \seef{FExpand}, \seem{Dirname}{1}}

\input{linuxex/ex47.tex}

\function{Glob}{(Const Path : Pathstr)}{PGlob}
{
Glob returns a pointer to a glob structure which contains all filenames which
exist and match the pattern in \var{Path}.

The pattern can contain wildcard characters, which have their
usual meaning.

The pglob structure is defined as :
Some more text.
}
{ Returns nil on error, and \var{LinuxError} is set.
\begin{description}
\item[sys\_enomem] No memory on heap for glob structure.
\item[others] As returned by the opendir call, and sys\_readdir.
\end{description}
}
{\seep{GlobFree}, \seem{Glob}{3} }

\input{linuxex/ex49.tex}

 \procedure{GlobFree}{(Var P : Pglob)}
 {Releases the memory, occupied by a pglob structure. \var{P} is set to nil.}{None}
 { \seef{Glob} }

For an example, see \seef{Glob}.

\procedure{AssignPipe}{(Pipe\_in, Pipe\_out : Text)}
{\var{AssignePipe} creates a pipe, i.e. two file objects, one for input, one for output.
What is written to \var{Pipe\_out}, can be read from \var{Pipe\_in}.
Reading and writing happens through the usual \var{Readln(Pipe\_in,...)} and
\var{Writeln (Pipe\_out,...)} procedures.
}
{ \var{LinuxError} is used to report errors:
\begin{description}
\item[sys\_emfile] Too many file descriptors for this process.
\item[sys\_enfile] The system file table is full.
\end{description}
}
{\seep{POpen}, \seef{MkFifo}, \seem{pipe}{2}}

\input{linuxex/ex36.tex}

\function{MkFifo}{(PathName: String; Mode : Longint)}{Boolean}
{\var{MkFifo} creates named a named pipe in the filesystem, with name
\var{PathName} and mode {Mode}. 
}
{ \var{LinuxError} is used to report errors:
\begin{description}
\item[sys\_emfile] Too many file descriptors for this process.
\item[sys\_enfile] The system file table is full.
\end{description}
}
{\seep{POpen}, \seef{MkFifo}, \seem{mkfifo}{4}}


\procedure{AssignStream}{(StreamIn,StreamOut : Text; Const prog : String)}
{\var{AssignStream} creates a 2 pipes, i.e. two file objects, one for input, one for
output, the other ends of these pipes are connected to standard input and and
output of \var{Prog}. \var{Prog} is the name of a program (including path)
with options, which will be executed.
What is written to \var{StreamOut}, will go to the standard input of
\var{Prog}. Whatever is written by \var{Prog} to it's standard output be read from
\var{StreamIn}.
Reading and writing happens through the usual \var{Readln(StreamIn,...)} and
\var{Writeln (StreamOut,...)} procedures.
}
{ \var{LinuxError} is used to report errors:
\begin{description}
\item[sys\_emfile] Too many file descriptors for this process.
\item[sys\_enfile] The system file table is full.
\end{description}
Other errors include the ones by the fork and exec programs
}
{\seep{AssignPipe}, \seep{POpen},\seem{pipe}{2}}

\input{linuxex/ex38.tex}

\procedure {POpen}{(F : Text; Cmd : pathstr; rw : char)}
{ Popen runs the command specified in \var{Cmd},
 and redirects the standard in or output of the
command to the other end of the pipe \var{F}. The parameter \var{rw}
indicates the direction of the pipe. If it is set to \var{'W'}, then F can
be used to write data, which will then be read by the command from stdinput.
If it is set to \var{'R'}, then the standard output of the command can be 
read from \var{F}. \var{F} should be reset or rewritten.
.}
{Errors are reported in \var{LinuxError} and are essentially those of the
Execve, Dup and AssignPipe commands.
}
{\seep{AssignPipe}, \seem{popen}{3}}

\input{linuxex/ex37.tex}

\function{Fcntl}{(Fd :  text, Cmd : Integer)}{Integer}
{
Read a file's attributes. \var{Fd} is an assigned file.
\var{Cmd} speciefies what to do, and is one of the following:
\begin{description}
\item[F\_GetFd] Read the close\_on\_exec flag. If the low-order bit is 0, then
the file will remain open across execve calls.
\item[F\_GetFl] Read the descriptor's flags.
\item[F\_GetOwn] Get the Process ID of the owner of a socket.
\end{description}
}
{
\var{LinuxError} is used to report errors.
\begin{description}
\item[sys\_ebadf] \var{Fd} has a bad file descriptor.
\end{description}
}
{\seep{Fcntl}, \seem{Fcntl}{2} }

\procedure{Fcntl}{(Fd :  text, Cmd : Integer; Arg : longint)}
{
Read or Set a file's attributes. \var{Fd} is an assigned file.
\var{Cmd} speciefies what to do, and is one of the following:
\begin{description}
\item[F\_SetFd] Set the close\_on\_exec flag of \var{Fd}. (only the least
siginificant bit is used).
\item[F\_GetLk] Return the \var{flock} record that prevents this process from
obtaining the lock, or set the \var{l\_type} field of the lock of there is no
obstruction. Arg is a pointer to a flock record.
\item[F\_SetLk] Set the lock or clear it (depending on \var{l\_type} in the
\var{flock} structure). if the lock is held by another process, an error
occurs.
\item[F\_GetLkw] Same as for \textbf{F\_Setlk}, but wait until the lock is
released.
\item[F\_SetOwn] Set the Process or process group that owns a socket.
\end{description}
}
{
\var{LinuxError} is used to report errors.
\begin{description}
\item[sys\_ebadf] \var{Fd} has a bad file descriptor.
\item[sys\_eagain or sys\_eaccess] For \textbf{F\_SetLk}, if the lock is
held by another process.
\end{description}
}
{\seef{Fcntl}, \seem{Fcntl}{2} }

\procedure{Dup}{(Var OldFile, NewFile : Text)}
{
Makes \var{NewFile} an exact copy of \var{OldFile}, after having flushed the
buffer of \var{OldFile}. Due to the buffering mechanism of Pascal, this has not
the same functionality as the \seem{dup}{2} call in C. The internal Pascal
buffers are not the same after this call, but when the buffers are flushed
(e.g. after output), the output is sent to the same file.
Doing an lseek will, however, work as in C, i.e. doing a lseek will change the
fileposition in both files.
}
{ \var{Linuxerror} is used to report errors.
\begin{description}
\item[sys\_ebadf] \var{OldFile} hasn't been assigned.
\item[sys\_emfile] Maximum number of open files for the process is reached.
\end{description}
}
{\seep{Dup2}, \seem{Dup}{2} }

\input{linuxex/ex31.tex}

\procedure{Dup2}{(Var OldFile, NewFile : Text)}
{
Makes \var{NewFile} an exact copy of \var{OldFile}, after having flushed the
buffer of \var{OldFile}. \var{NewFile} can be an assigned file.
If \var{newfile} was open, it is closed first.
Due to the buffering mechanism of Pascal, this has not
the same functionality as the \seem{dup2}{2} call in C. The internal Pascal
buffers are not the same after this call, but when the buffers are flushed
(e.g. after output), the output is sent to the same file.
Doing an lseek will, however, work as in C, i.e. doing a lseek will change the
fileposition in both files.
}
{ \var{Linuxerror} is used to report errors.
\begin{description}
\item[sys\_ebadf] \var{OldFile} hasn't been assigned.
\item[sys\_emfile] Maximum number of open files for the process is reached.
\end{description}
}
{ \seep{Dup}, \seem{Dup2}{2} }

\input{linuxex/ex32.tex}

\procedure{SigAction}{(Signum : Integer; Var Act,OldAct : PSigActionRec)}
{ Changes the action to take upon receipt of a signal. \var{Act} and
\var{Oldact} are pointers to a \var{SigActionRec} record.

\var{SigNum} specifies the signal, and can be any signal except
\textbf{SIGKILL} or \textbf{SIGSTOP}.

If \var{Act} is non-nil, then the new action for signal \var{SigNum} is taken
from it. If \var{OldAct} is non-nil, the old action is stored there.

\var{Sa\_Handler} may be \var{SIG\_DFL} for the default action or
\var{SIG\_IGN} to ignore the signal.

\var{Sa\_Mask} Specifies which signals should be ignord during the execution
of the signal handler.

\var{Sa\_Flags} Speciefies a series of flags which modify the behaviour of
the signal handler. You can 'or' none or more of the following :
\begin{description}
\item[SA\_NOCLDSTOP] If signum is \textbf{SIGCHLD} do not receive
notification when child processes stop.
\item[SA\_ONESHOT or SA\_RESETHAND] Restore the signal action to the default
state once the signal handler has been called.
\item[SA\_RESTART] For compatibility with BSD signals.
\item[SA\_NOMASK or SA\_NODEFER] Do not prevent the signal from being received
from within its own signal handler.
\end{description}
}
{\var{LinuxError} is used to report errors.
\begin{description}
\item[sys\_einval] an invalid signal was specified, or it was
\textbf{SIGKILL} or \textbf{SIGSTOP}.
\item[sys\_efault] \var{Act,OldAct} point outside this process address space
\item[sys\_eintr] System call was interrupted.
\end{description}
}
{
\seep{SigProcMask}, \seef{SigPending}, \seep{SigSuspend}, \seef{Kill},
\seem{Sigaction}{2}
}

\procedure {SigProcMask}{(How : Integer; SSet,OldSSet : PSigSet)}
{
Changes the list of currently blocked signals. The behaviour of the call
depends on \var{How} :
\begin{description}
\item[SIG\_BLOCK] The set of blocked signals is the union of the current set
and the \var{SSet} argument.
\item[SIG\_UNBLOCK] The signals in \var{SSet} are removed from the set of
currently blocked signals.
\item[SIG\_SETMASK] The list of blocked signals is set so \var{SSet}.
\end{description}
If \var{OldSSet} is non-nil, then the old set is stored in it.
}
{\var{LinuxError} is used to report errors.
\begin{description}
\item[sys\_efault] \var{SSet} or \var{OldSSet} point to an adress outside
the range of the process.
\item[sys\_eintr] System call was interrupted.
\end{description}
}
{\seep{SigAction}, \seef{SigPending}, \seep{SigSuspend}, \seef{Kill},
\seem{Sigprocmask}{2} }

\function{SigPending}{}{SigSet}
{
Sigpending allows the examination of pending signals (which have been raised
while blocked.) The signal mask of pending signals is returned.
}
{None}
{\seep{SigAction}, \seep{SigProcMask}, \seep{SigSuspend}, \seef{Signal},
\seef{Kill}, \seem{Sigpending}{2} }

\procedure{SigSuspend}{(Mask : SigSet)}
{SigSuspend temporarily replaces the signal mask for the process with the one
given in \var{Mask}, and then suspends the process until a signal is received.
}
{None}
{\seep{SigAction}, \seep{SigProcMask}, \seef{SigPending}, \seef{Signal},
\seef{Kill}, \seem{SigSuspend}{2} }

\function{Signal}{(SigNum : Integer; Handler : PSignalHandler)}{PSignalHandler}
{
Signal installs a new signal handler for signal \var{SigNum}. This call has
the same functionality as the \textbf{SigAction} call.

The return value for Signal is the old signal handler, or nil on error.
}
{\var {LinuxError} is used to report errors :
\begin{description}
\item[SIG\_ERR] An error occurred.
\end{description}
}
{\seep{SigAction},\seef{Kill}, \seem{Signal}{2} }

\function{Kill}{Pid : Longint; Sig : Integer)}{Integer}
{ Send a signal \var{Sig} to a process or process group. If \var{Pid}>0 then
the signal is sent to \var{Pid}, if it equals -1, then the signal is sent to
all processes except process 1. If \var{Pid}<-1 then the signal is sent to
process group -Pid.

The return value is zero, except in case three, where the return value is the
number of processes to which the signal was sent.
}
{\var{LinuxError} is used to report errors:
\begin{description}
\item[sys\_einval] An invalid signal is sent.
\item[sys\_esrch] The \var{Pid} or process group don't exist.
\item[sys\_eperm] The effective userid of the current process doesn't math
the one of process \var{Pid}.
\end{description}
}
{\seep{SigAction}, \seef{Signal}, \seem{Kill}{2} }

\function{GetHostName}{}{String}
{
Get the hostname of the machine on which the process is running.
An empty string is returned if hostname is not set.
}
{None.}
{ \seef{GetDomainName},seem{Gethostname}{2} }

\input{linuxex/ex40.tex}

\function{GetDomainName}{}{String}
{
Get the domain name of the machine on which the process is running.
An empty string is returned if the domain is not set.
}
{None.}
{ \seef{GetHostName},seem{Getdomainname}{2} }

\input{linuxex/ex39.tex}

\function{GetEnv}{(P : String)}{PChar}
{Returns the value of the environment variable in \var{P}. If the variable is
not defined, nil is returned. The value of the environment variable may be
the empty string.

A PChar is returned to accomodate for strings longer than 255 bytes,
\var{TERMCAP} and \var{LS\_COLORS}, for instance.
}
{None.}
{\seem{sh}{1}, \seem{csh}{1} }

\input{linuxex/ex41.tex}

\function{Select}{(N : Longint; \\ var readfds,writefds,exceptfds : PFDset;
Var Timeout)}{Longint}
{\var{Select} checks one of the file descriptors in the \var{FDSets} to see if its
status changed.

\var{readfds, writefds} and \var{exceptfds} are pointers to arrays of 256
bits. If you want a file descriptor to be checked, you set the
corresponding element in the array to 1. The other elements in the array
must be set to zero. Three arrays are passed : The entries in \var{readfds}
are checked to see if characters become available for reading. The entries
in \var{writefds} are checked to see if it is OK to write to them, while
entries in \var{exceptfds} are cheked to see if an exception occorred on
them.

You can use the functions \seepl{FD\_Clear}{FDClear}, \seepl{FD\_Clr}{FDClr}, 
\seepl{FD\_Set}{FDSet}, \seefl{FD\_IsSet}{FDIsSet} to manipulate the individual elements of a set.

The pointers can be nil.

\var{N} is the largest index of a nonzero entry plus 1. (= the largest
file-descriptor + 1).

\var{TimeOut} can be used to set a time limit. 
If \var{TimeOut} can be two types :
\begin{enumerate}
\item \var{TimeOut} is of type \var{PTime} and contains a
zero time, the call returns immediately. If \var{TimeOut} is \var{Nil}, the
kernel will wait forever, or until a status changed.    
\item \var{TimeOut} is of type \var{Longint}. If it is -1, this has the same
effect as a \var{Timeout} of type  \var{PTime} which is \var{Nil}.
Otherwise, \var{TimeOut} contains a time in milliseconds.
\end{enumerate}
 
When the TimeOut is reached, or one of the file descriptors has changed,
the \var{Select} call returns. On return, it will have modified the entries
in the array which have actually changed, and it returns the number of
entries that have been changed. If the timout was reached, and no decsriptor
changed, zero is returned; The arrays of indexes are undefined after that.
On error, -1 is returned.}
{On error, the function returns -1, and Errors are reported in LinuxError :
\begin{description}
\item[SYS\_EBADF\ ] An invalid descriptot was specified in one of the sets.
\item[SYS\_EINTR\ ] A non blocked signal was caught.
\item[SYS\_EINVAL\ ]  \var{N} is negative or too big.
\item[SYS\_ENOMEM\ ] \var{Select} was unable to allocate memory for its 
 internal tables.
\end{description}}
{\seef{SelectText}, \seef{GetFS}, 
\seepl{FD\_Clear}{FDClear},
\seepl{FD\_Clr}{FDClr},
\seepl{FD\_Set}{FDSet}, 
\seefl{FD\_IsSet}{FDIsSet}}

\input{linuxex/ex33.tex}

\function{SelectText}{( var T : Text; TimeOut :PTime)}{Longint}
{\var{SelectText} executes the \seef{Select} call on a file of type
\var{Text}. You can specify a timeout in \var{TimeOut}. The SelectText call
determines itself whether it should check for read or write, depending on
how the file was opened : With \var{Reset} it is checked for reading, with
\var{Rewrite} and \var{Append} it is checked for writing.}
{See \seef{Select}. \var{SYS\_EBADF} can also mean that the file wasn't
opened.}
{\seef{Select}, \seef{GetFS}}
\function{GetFS}{(Var F : Any File Type)}{Longint}
{\var{GetFS} returns the file selector that the kernel provided for your
file. In principle you don' need this file selector. Only for some calls
it is needed, such as the \seef{Select} call or so.}
{In case the file was not opened, then -1 is returned.}
{\seef{Select}}

\input{linuxex/ex34.tex}

\procedurel{FD\_Clear}{FDClear}{(var fds:fdSet)}
{\var{FD\_Clear} clears all the filedescriptors in the file descriptor 
set \var{fds}.}
{None.}
{\seef{Select}, 
\seef{SelectText}, 
\seef{GetFS}, 
\seepl{FD\_Clr}{FDClr},
\seepl{FD\_Set}{FDSet}, 
\seefl{FD\_IsSet}{FDIsSet}

}

For an example, see \seef{Select}.

\procedurel{FD\_Clr}{FDClr}{(fd:longint;var fds:fdSet)}
{ \var{FD\_Clr} clears file descriptor \var{fd} in filedescriptor s
  et \var{fds}.}
{None.}
{\seef{Select}, 
\seef{SelectText}, 
\seef{GetFS},
\seepl{FD\_Clear}{FDClear}, 
\seepl{FD\_Set}{FDSet}, 
\seefl{FD\_IsSet}{FDIsSet}}

For an example, see \seef{Select}.

\procedurel{FD\_Set}{FDSet}{(fd:longint;var fds:fdSet)}
{\var{FD\_Set} sets file descriptor \var{fd} in filedescriptor set \var{fds}.}
{None.}
{\seef{Select}, \seef{SelectText}, \seef{GetFS},\seepl{FD\_Clear}{FDClear}, 
\seepl{FD\_Clr}{FDClr}, \seefl{FD\_IsSet}{FDIsSet}}

For an example, see \seef{Select}.

\functionl{FD\_IsSet}{FDIsSet}{(fd:longint;var fds:fdSet)}{boolean}
{\var{FD\_Set} Checks whether file descriptor \var{fd} in filedescriptor set \var{fds}
is set.}
{None.}
{\seef{Select}, \seef{SelectText}, \seef{GetFS},
\seepl{FD\_Clear}{FDClear}, 
\seepl{FD\_Clr}{FDClr},
\seepl{FD\_Set}{FDSet}}

For an example, see \seef{Select}.

\function{fdOpen}{(pathname:string;flags:longint[; Mode: longint])}{longint}
{ \var{fdOpen} opens a file in \var{pathname} with flags \var{flags} a ORed combination of
  \var{Open\_Accmode, Open\_RdOnly, Open\_WrOnly, Open\_RdWr, Open\_Creat,
  Open\_Excl, Open\_NoCtty, Open\_Trunc, Open\_Append, Open\_NonBlock,
  Open\_NDelay, Open\_Sync}

  The optional \var{mode} argument specifies the permissions to set when opening
  the file. This is modified by the umask setting. The real permissions are
  \var{Mode and not umask}.

  The return value of the function is the filedescriptor, or a negative 
  value if there was an error.
}
{Errors are returned in LinuxError}
{\seef{fdClose}, \seef{fdRead}, \seef{fdWrite},\seef{fdTruncate}}

\input{linuxex/ex19.tex}

\function{fdClose}{(fd:longint)}{boolean}
{
\var{fdClose} closes a file with file descriptor \var{Fd}. The function
returns \var{True} if the file was closed successfully, \var{False}
otherwise. 
}
{Errors are returned in LinuxError}
{\seef{fdOpen}, \seef{fdRead}, \seef{fdWrite},\seef{fdTruncate}}

For an example, see \seef{fdOpen}.

\function{fdRead}{(fd:longint;var buf;size:longint}{longint}
{ \var{fdRead} reads at most \var{size} bytes from the file descriptor
\var{fd}, and stores them in \var{buf}. 

The function returns the number of bytes actually read, or -1 if
an error occurred.

No checking on the length of \var{buf} is done.
}
{Errors are returned in LinuxError.}
{\seef{fdOpen}, \seef{fdClose}, \seef{fdWrite},\seef{fdTruncate}}

\input{linuxex/ex20.tex}

\function{fdWrite}{(fd:longint;var buf;size:longint}{longint}  
{\var{fdWrite} writes at most \var{size} bytes from \var{buf} to
file descriptor \var{fd}.

The function returns the number of bytes actually written, or -1 if an error
occurred.
}
{Errors are returned in LinuxError.}
{\seef{fdOpen}, \seef{fdClose}, \seef{fdRead},\seef{fdTruncate}}

For an example, see \seef{fdOpen}.

\function{fdTruncate}{(fd,size:longint}{boolean}
{\var{fdTruncate} sets the length of a file in \var{fd} on \var{size}
bytes, where \var{size} must be less than or equal to the current length of
the file in \var{fd}.

The function returns \var{True} if the call was successful, \var{false} if
an error occurred.}
{Errors are returned in LinuxError.}
{\seef{fdOpen}, \seef{fdClose}, \seef{fdRead},\seef{fdWrite}}

For an example, see \seef{fdRead}.

\functionl{S\_ISLNK}{ISLNK}{(m:integer)}{boolean}
{ \var{S\_ISLNK} checks the file mode \var{m} to see whether the file is a
symbolic link. If so it returns \var{True}
}
{\seef{FStat},
 \seefl{S\_ISREG}{ISREG},
 \seefl{S\_ISDIR}{ISDIR},
 \seefl{S\_ISCHR}{ISCHR},
 \seefl{S\_ISBLK}{ISBLK},
 \seefl{S\_ISFIFO}{ISFIFO},
 \seefl{S\_ISSOCK}{ISSOCK}
}

\input{linuxex/ex53.tex}

\functionl{S\_ISREG}{ISREG}{(m:integer)}{boolean}
{ \var{S\_ISREG} checks the file mode \var{m} to see whether the file is a
regular file. If so it returns \var{True}
}
{\seef{FStat},
 \seefl{S\_ISLNK}{ISLNK}, 
 \seefl{S\_ISDIR}{ISDIR},
 \seefl{S\_ISCHR}{ISCHR},
 \seefl{S\_ISBLK}{ISBLK},
 \seefl{S\_ISFIFO}{ISFIFO},
 \seefl{S\_ISSOCK}{ISSOCK}
}

For an example, see \seef{ISLNK}.

\functionl{S\_ISDIR}{ISDIR}{(m:integer)}{boolean}	
{ \var{S\_ISDIR} checks the file mode \var{m} to see whether the file is a
directory. If so it returns \var{True}
}
{\seef{FStat},
 \seefl{S\_ISLNK}{ISLNK}, 
 \seefl{S\_ISREG}{ISREG},
 \seefl{S\_ISCHR}{ISCHR},
 \seefl{S\_ISBLK}{ISBLK},
 \seefl{S\_ISFIFO}{ISFIFO},
 \seefl{S\_ISSOCK}{ISSOCK}
}

For an example, see \seef{ISLNK}.

\functionl{S\_ISCHR}{ISCHR}{(m:integer)}{boolean}
{ \var{S\_ISCHR} checks the file mode \var{m} to see whether the file is a
character device file. If so it returns \var{True}.
}
{\seef{FStat},
 \seefl{S\_ISLNK}{ISLNK}, 
 \seefl{S\_ISREG}{ISREG},
 \seefl{S\_ISDIR}{ISDIR},
 \seefl{S\_ISBLK}{ISBLK},
 \seefl{S\_ISFIFO}{ISFIFO},
 \seefl{S\_ISSOCK}{ISSOCK}
}

For an example, see \seef{ISLNK}.

\functionl{S\_ISBLK}{ISBLK}{(m:integer)}{boolean}
{ \var{S\_ISBLK} checks the file mode \var{m} to see whether the file is a
block device file. If so it returns \var{True}.
}
{\seef{FStat},
 \seefl{S\_ISLNK}{ISLNK}, 
 \seefl{S\_ISREG}{ISREG},
 \seefl{S\_ISDIR}{ISDIR},
 \seefl{S\_ISCHR}{ISCHR},
 \seefl{S\_ISFIFO}{ISFIFO},
 \seefl{S\_ISSOCK}{ISSOCK}
}

For an example, see \seef{ISLNK}.

\functionl{S\_ISFIFO}{ISFIFO}{(m:integer)}{boolean}
{ \var{S\_ISFIFO} checks the file mode \var{m} to see whether the file is a
fifo (a named pipe). If so it returns \var{True}.
}
{\seef{FStat},
 \seefl{S\_ISLNK}{ISLNK}, 
 \seefl{S\_ISREG}{ISREG},
 \seefl{S\_ISDIR}{ISDIR},
 \seefl{S\_ISCHR}{ISCHR},
 \seefl{S\_ISBLK}{ISBLK},
 \seefl{S\_ISSOCK}{ISSOCK}
}

For an example, see \seef{ISLNK}.

\functionl{S\_ISSOCK}{ISSOCK}{(m:integer)}{boolean}
{ \var{S\_ISSOCK} checks the file mode \var{m} to see whether the file is a
socket. If so it returns \var{True}.
}
{\seef{FStat},
 \seefl{S\_ISLNK}{ISLNK}, 
 \seefl{S\_ISREG}{ISREG},
 \seefl{S\_ISDIR}{ISDIR},
 \seefl{S\_ISCHR}{ISCHR},
 \seefl{S\_ISBLK}{ISBLK},
 \seefl{S\_ISFIFO}{ISFIFO}
}


For an example, see \seef{ISLNK}.

\function{OpenDir}{(f:pchar)}{pdir}
{ \var{OpenDir} opens the directory  \var{f}, and returns a \var{pdir}
pointer to a \var{Dir} record, which can be used to read the directory 
structure. If the directory cannot be opened, \var{nil} is returned.}
{Errors are returned in LinuxError.}
{\seef{CloseDir}, \seef{ReadDir}, \seep{SeekDir}, \seef{TellDir},
\seem{opendir}{3}}

\input{linuxex/ex35.tex}

\function{CloseDir}{(p:pdir)}{integer}
{ \var{CloseDir} closes the directory pointed to by \var{p}.
It returns zero if the directory was closed succesfully, -1 otherwise.}
{Errors are returned in LinuxError.}
{\seef{OpenDir}, \seef{ReadDir}, \seep{SeekDir}, \seef{TellDir},
\seem{closedir}{3}}

For an example, see \seef{OpenDir}.

\function{ReadDir}{(p:pdir)}{pdirent}
{\var{ReadDir} reads the next entry in the directory pointed to by \var{p}.
It returns a \var{pdirent} pointer to a structure describing the entry.
If the next entry can't be read, \var{Nil} is returned.
}
{Errors are returned in LinuxError.}
{\seef{CloseDir}, \seef{OpenDir}, \seep{SeekDir}, \seef{TellDir},
\seem{readdir}{3}}

For an example, see \seef{OpenDir}.

\procedure {SeekDir}{(p:pdir;off:longint)}
{ \var{SeekDir} sets the directory pointer to the \var{off}-th entry in the
directory structure pointed to by \var{p}.}
{Errors are returned in LinuxError.}
{\seef{CloseDir}, \seef{ReadDir}, \seef{OpenDir}, \seef{TellDir},
\seem{seekdir}{3}}

For an example, see \seef{OpenDir}.

\function{TellDir}{(p:pdir)}{longint}
{ \var{TellDir} returns the current location in the directory structure
pointed to by \var{p}. It returns -1 on failure.}
{Errors are returned in LinuxError.}
{\seef{CloseDir}, \seef{ReadDir}, \seep{SeekDir}, \seef{OpenDir},
\seem{telldir}{3}}

For an example, see \seef{OpenDir}.

\procedure{Uname}{(var unamerec:utsname)}
{\var{Uname} gets the name and configuration of the current \linux kernel,
and returns it in \var{unamerec}.
}
{\var{LinuxError} is used to report errors.}
{\seef{GetHostName}, \seef{GetDomainName}, \seem{uname}{2}}

\function{WaitPid}{(Pid : longint; Status : pointer; Options : Integer)}{Longint}
{ \var{WaitPid} waits for a child process with process ID \var{Pid} to exit. The
value of \var{Pid} can be one of the following:
\begin{description}
\item[Pid < -1] Causes \var{WaitPid} to wait for  any  child  process  whose
              process group ID equals the absolute value of \var{pid}.

\item[Pid = -1] Causes \var{WaitPid} to wait for any child process.

\item[Pid = 0] Causes \var{WaitPid} to wait for  any  child  process  whose
              process  group  ID  equals the one of the calling
              process.

\item[Pid > 0] Causes \var{WaitPid} to wait for the child whose process  ID
equals the value of \var{Pid}.
\end{description}
The \var{Options} parameter can be used to specify further how \var{WaitPid}
behaves:
\begin{description}
\item [WNOHANG] Causes \var{Waitpid} to return immediately if no child  has
exited.
\item [WUNTRACED] Causes \var{WaitPid} to return also for children which are
stopped, but whose status has not yet been reported.
\end{description} 

Upon return, it returns the exit status of the process, or -1 in case of
failure. 
}
{Errors are returned in LinuxError.}
{\seef{Fork}, \seep{Execve}, \seem{waitpid}{2}}

for an example, see \seef{Fork}.

\function{TCGetAttr}{(fd:longint;var tios:TermIOS)}{Boolean}
{ \var{TCGetAttr}
  gets the terminal parameters from the terminal referred to by the file
  descriptor \var{fd} and returns them in a \var{TermIOS} structure \var{tios}. 

The function returns \var{True} if the call was succesfull, \var{False}
otherwise.
}
{Errors are reported in LinuxError}
{\seef{TCSetAttr}, \seem{termios}{2} }

\input{linuxex/ex55.tex}

\function{TCSetAttr}{(Fd:longint;OptAct:longint;var Tios:TermIOS)}{Boolean}
{ \var{TCSetAttr}
  Sets the terminal parameters you specify in a \var{TermIOS} structure
\var{Tios} for the terminal
  referred to by the file descriptor \var{Fd}. \var{OptAct} specifies an 
  optional action when the set need to be done,
  this could be one of the following pre-defined values:
 \begin{description}
\item [TCSANOW\ ] set immediately.
\item [TCSADRAIN\ ] wait for output.
\item [TCSAFLUSH\ ] wait for output and discard all input not yet read. 
\end{description}
The function Returns \var{True} if the call was succesfull, \var{False} 
otherwise.
}
{Errors are reported in LinuxError.}
{\seef{TCGetAttr}, \seem{termios}{2}}

For an example, see \seef{TCGetAttr}.

\procedure{CFSetISpeed}{(var Tios:TermIOS;Speed:Longint)}
{ \var{CFSetISpeed}
  Sets the input baudrate in the \var{TermIOS} structure \var{Tios} to 
  \var{Speed}.
}
{None.}
{\seep{CFSetOSpeed}, \seep{CFMakeRaw}, \seem{termios}{2}}

\procedure{CFSetOSpeed}{(var Tios:TermIOS;Speed:Longint)}
{ \var{CFSetOSpeed}
  Sets the output baudrate in the \var{Termios} structure \var{Tios} to
  \var{Speed}.
}
{None.}
{\seep{CFSetISpeed}, \seep{CFMakeRaw}, \seem{termios}{2}}

\procedure{CFMakeRaw}{(var Tios:TermIOS)}
{ \var{CFMakeRaw}
  Sets the flags in the \var{Termios} structure \var{Tios} to a state so that 
  the terminal will function in Raw Mode.
}
{None.}
{ \seep{CFSetOSpeed}, \seep{CFSetISpeed}, \seem{termios}{2}}

For an example, see \seef{TCGetAttr}.

\function{TCSendBreak}{(Fd,Duration:longint)}{Boolean}
{ \var{TCSendBreak} 
  Sends zero-valued bits on an asynchrone serial connection decsribed by
  file-descriptor \var{Fd}, for duration \var{Duration}.

  The function returns \var{True} if the action was performed successfully,
\var{False} otherwise.
}
{Errors are reported in LinuxError.}
{\seem{termios}{2}}

Function TCSetPGrp(Fd,Id:longint):boolean;
{ \var{TCSetPGrp}
  Sets the Process Group Id to \var{Id}. 

  The function returns \var{True} if the call was successful, \var{False}
otherwise.
}
{Errors are returned in LinuxError.}
{\seef{TCGetPGrp}\seem{termios}{2}}

\function{TCGetPGrp}{(Fd:longint;var Id:longint)}{boolean}
{ \var{TCGetPGrp}
  returns the process group ID of a foreground process group in \var{Id} 

  The function returns \var{True} if the call was succesfull, \var{False}
  otherwise
}
{Errors are reported in LinuxError}
{\seem{termios}{2}}

\function{TCDrain}{(Fd:longint)}{Boolean}
{ \var{TCDrain}
  waits until all data to file descriptor \var{Fd} is transmitted.
  
  The function returns \var{True} if the call was succesfull, \var{False}
  otherwise.
}
{Errors are reported in LinuxError}
{\seem{termios}{2}}

\function {TCFlow}{(Fd,Act:longint)}{Boolean}
{ \var{TCFlow}
  suspends/resumes transmission or reception of data to or from the file
descriptor \var{Fd}, depending
  on the action \var {Act}. This can be one of the following pre-defined
values: 
\begin{description}
\item [TCOOFF\ ] suspend reception/transmission,
\item [TCOON\ ] resume  reception/transmission,
\item [TCIOFF\ ] transmit a stop character to stop input from the terminal, 
\item [TCION\ ] transmit start to resume input from the terminal.
\end{description}

The function returns \var{True} if the call was succesfull, \var{False}
otherwise.
}
{Errors are reported in LinuxError.}
{\seem{termios}{2}}

\function{TCFlush}{(Fd,QSel:longint)}{Boolean}
{ \var{TCFlush}
  discards all data sent or received to/from file descriptor \var{fd}. 
 \var{QSel} indicates which queue
  should be discard. It can be one of the following pre-defined values :
\begin{description}
\item [TCIFLUSH\ ] input,
\item [TCOFLUSH\ ] output,
\item [TCIOFLUSH\ ] both input and output.
\end{description}

The function returns \var{True} if the call was succesfull, \var{False}
otherwise.
}
{Errors are reported in LinuxError.}
{\seem{termios}{2}}