% % $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.} \label{ch:linux} \FPCexampledir{linuxex} 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 3 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 gives and overview of all available functions, grouped by category. \item The third section describes all procedures and functions in the LINUX unit. \end{itemize} % Type, Variable and Constant declarations %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \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} tfpreg = record significand: array[0..3] of word; exponent: word; end; pfpstate = ^tfpstate; tfpstate = record cw, sw, tag, ipoff, cssel, dataoff, datasel: cardinal; st: array[0..7] of tfpreg; status: cardinal; end; PSigContextRec = ^SigContextRec; SigContextRec = record gs, __gsh: word; fs, __fsh: word; es, __esh: word; ds, __dsh: word; edi: cardinal; esi: cardinal; ebp: cardinal; esp: cardinal; ebx: cardinal; edx: cardinal; ecx: cardinal; eax: cardinal; trapno: cardinal; err: cardinal; eip: cardinal; cs, __csh: word; eflags: cardinal; esp_at_signal: cardinal; ss, __ssh: word; fpstate: pfpstate; oldmask: cardinal; cr2: cardinal; end; \end{verbatim} The above records contain information about the processor state and process state at the moment a signal is sent to your program. The records below are used in catching signals. \begin{verbatim} TSigAction = procedure(Sig: Longint; SigContext: SigContextRec);cdecl; SignalHandler = Procedure ( Sig : Integer);cdecl; PSignalHandler = SignalHandler; SignalRestorer = Procedure;cdecl; PSignalrestorer = SignalRestorer; SigActionRec = packed record Handler : record case byte of 0: (Sh: SignalHandler); 1: (Sa: TSigAction); end; Sa_Mask : SigSet; Sa_Flags : Longint; Sa_restorer : SignalRestorer; { Obsolete - Don't use } 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 \var{timespec} record is needed in the \seef{NanoSleep} function: \begin{verbatim} timespec = packed record tv_sec,tv_nsec:longint; end; \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} the \seef{FLock} call uses the following mode constants : \begin{verbatim} LOCK_SH = 1; LOCK_EX = 2; LOCK_UN = 8; LOCK_NB = 4; \end{verbatim} The \seef{MMap} function uses the following constants to specify access to mapped memory: \begin{verbatim} PROT_READ = $1; { page can be read } PROT_WRITE = $2; { page can be written } PROT_EXEC = $4; { page can be executed } PROT_NONE = $0; { page can not be accessed } \end{verbatim} and the following constants to specify the type of mapping. \begin{verbatim} MAP_SHARED = $1; { Share changes } MAP_PRIVATE = $2; { Changes are private } MAP_TYPE = $f; { Mask for type of mapping } MAP_FIXED = $10; { Interpret addr exactly } MAP_ANONYMOUS = $20; { don't use a file } \end{verbatim} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Functions and procedures by category \section{Function list by category} What follows is a listing of the available functions, grouped by category. For each function there is a reference to the page where you can find the function. \subsection{File Input/Output routines} Functions for handling file input/output. \begin{funclist} \funcref{Dup}{Duplicate a file handle} \funcref{Dup2}{Copy one file handle to another} \procref{Fcntl}{General file control} \funcref{fdClose}{Close file descriptor} \funcref{fdFlush}{Flush file descriptor} \funcref{fdOpen}{Open new file descriptor} \funcref{fdRead}{Read from file descriptor} \funcref{fdSeek}{Position in file} \funcref{fdTruncate}{Truncate file} \funcref{fdWrite}{Write to file descriptor} \funcref{GetFS}{Get file descriptor of pascal file} \funcref{Select}{Wait for input from file descriptor} \funcref{SelectText}{Wait for input from pascal file} \end{funclist} \subsection{General File handling routines} Functions for handling files on disk. \begin{funclist} \funcref{Access}{Check access rights on file} \funcref{BaseName}{Return name part of file} \funcref{Chown}{Change owner of file} \funcref{Chmod}{Change access rights on file} \funcref{DirName}{Return directory part of file} \procrefl{FSplit}{LFsplit}{Split filename in parts} \funcref{FExpand}{Return full-grown filename} \funcref{FLock}{Set lock on a file} \funcref{FNMatch}{Match filename to searchpattern} \funcref{FSearch}{Search for a file in a path} \funcref{FSStat}{Return filesystem information} \funcref{FStat}{Return file information} \funcref{FRename}{Rename file} \funcref{LStat}{Return information on a link} \funcref{Link}{Create a link} \funcref{ReadLink}{Read contents of a symbolic link} \funcref{SymLink}{Create a symbolic link} \funcref{Umask}{Set the file creation mask} \funcref{UnLink}{Remove a file} \funcref{Utime}{Change file timestamps} \end{funclist} \subsection{Pipes, FIFOs and streams } Functions for creating and managing pipes. \begin{funclist} \funcref{AssignPipe}{Create a pipe} \funcref{AssignStream}{Create pipes to program's input and output} \funcref{MkFifo}{Make a fifo} \funcref{PClose}{Close a pipe} \procref{POpen}{Open a pipe for to program's input or output} \end{funclist} \subsection{Directory handling routines} Functions for reading and searching directories. \begin{funclist} \funcref{CloseDir}{Close directory handle} \funcref{Glob}{Return files matching a search expression} \procref{GlobFree}{Free result of Glob} \funcref{OpenDir}{Open directory for reading} \funcref{ReadDir}{Read directory entry} \procref{SeekDir}{Seek directory} \funcref{TellDir}{Seek directory} \end{funclist} \subsection{Process handling} Functions for managing processes and programs. \begin{funclist} \funcref{Clone}{Create a thread} \procref{Execl}{Execute process with command-line list} \procref{Execle}{Execute process with command-line list and environment} \procref{Execlp}{Search in path and execute process with command list} \procref{Execv}{Execute process} \procref{Execve}{Execute process with environment} \procref{Execvp}{Search in path and execute process} \funcref{Fork}{Spawn child process} \funcref{GetEGid}{Get effective group id} \funcref{GetEnv}{Get environment variable} \funcref{GetEUid}{Get effective user id} \funcref{GetGid}{Get group id} \funcref{GetPid}{Get process id} \funcref{GetPPid}{Get parent process id} \funcref{GetPriority}{Get process priority} \funcref{GetUid}{Get user id} \procref{Nice}{Change priority of process} \funcref{SetPriority}{Change priority of process} \funcref{Shell}{Execute shell command} \funcref{WaitPid}{Wait for child process to terminate} \end{funclist} \subsection{Signals} Functions for managing and responding to signals. \begin{funclist} \funcref{Alarm}{Send alarm signal to self} \funcref{Kill}{Send arbitrary signal to process} \procref{pause}{Wait for signal to arrive} \procref{SigAction}{Set signal action} \funcref{Signal}{Set signal action} \funcref{SigPending}{See if signals are waiting} \procref{SigProcMask}{Set signal processing mask} \procref{SigRaise}{Send signal to self} \procref{SigSuspend}{Sets signal mask and waits for signal} \funcref{NanoSleep}{Waits for a specific amount of time} \end{funclist} \subsection{System information} Functions for retrieving system information such as date and time. \begin{funclist} \procref{GetDate}{Return system date} \procref{GetDateTime}{Return system date and time} \funcref{GetDomainName}{Return system domain name} \funcref{GetEpochTime}{Return epoch time} \funcref{GetHostName}{Return system host name} \procref{GetLocalTimezone}{Return system timezone} \procref{GetTime}{Return system time} \funcref{GetTimeOfDay}{Return system time} \funcref{GetTimezoneFile}{Return name of timezone file} \procref{ReadTimezoneFile}{Read timezone file contents} \funcref{SysInfo}{Return general system information} \procref{Uname}{Return system information} \end{funclist} \subsection{Terminal functions} Functions for controlling the terminal to which the process is connected. \begin{funclist} \procref{CFMakeRaw}{Set terminal to raw mode} \procref{CFSetISpeed}{Set terminal reading speed} \procref{CFSetOSpeed}{Set terminal writing speed} \procref{IOCtl}{General IO control call} \funcref{IsATTY}{See if filedescriptor is a terminal} \funcref{TCDrain}{Wait till all output was written} \funcref{TCFlow}{Suspend transmission or receipt of data} \funcref{TCFlush}{Discard data written to terminal} \funcref{TCGetAttr}{Get terminal attributes} \funcref{TCGetPGrp}{Return PID of foreground process} \funcref{TCSendBreak}{Send data for specific time} \funcref{TCSetAttr}{Set terminal attributes} \funcref{TCSetPGrp}{Set foreground process} \funcref{TTYName}{Name of tty file} \end{funclist} \subsection{Port input/output} Functions for reading and writing to the hardware ports. \begin{funclist} \funcref{IOperm}{Set permissions for port access} \procref{ReadPort}{Read data from port} \procref{ReadPortB}{Read 1 byte from port} \procref{ReadPortL}{Read 4 bytes from port} \procref{ReadPortW}{Read 2 bytes from port} \procref{WritePort}{Write data to port} \procref{WritePortB}{Write 1 byte to port} \procref{WritePortL}{Write 4 bytes to port} \procref{WritePortW}{Write 2 bytes to port} \end{funclist} \subsection{Utility routines} Auxiliary functions that are useful in connection with the other functions. \begin{funclist} \funcref{CreateShellArgV}{Create an array of pchars from string} \procref{EpochToLocal}{Convert epoch time to local time} \procrefl{FD\_Clr}{FDClr}{Clear item of select filedescriptors} \funcrefl{FD\_IsSet}{FDIsSet}{Check item of select filedescriptors} \procrefl{FD\_Set}{FDSet}{Set item of select filedescriptors} \procrefl{FD\_ZERO}{FDZero}{Clear all items in select filedecriptors} \funcref{LocalToEpoch}{Convert local time to epoch time} \funcref{MMap}{Map a file into memory} \funcref{MUnMap}{Unmap previously mapped memory file} \funcref{Octal}{Convert octal to digital} \funcrefl{S\_ISBLK}{ISBLK}{Check file mode for block device} \funcrefl{S\_ISCHR}{ISCHR}{Check file mode for character device} \funcrefl{S\_ISDIR}{ISDIR}{Check file mode for directory} \funcrefl{S\_ISFIFO}{ISFIFO}{Check file mode for FIFO} \funcrefl{S\_ISLNK}{ISLNK}{Check file mode for symboloc link} \funcrefl{S\_ISREG}{ISREG}{Check file mode for regular file} \funcrefl{S\_ISSOCK}{ISSOCK}{Check file mode for socket} \funcref{StringToPPchar}{Create an array of pchars from string} \end{funclist} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Functions and procedures \section{Functions and procedures} \begin{function}{Access} \Declaration Function Access (Path : Pathstr; Mode : integer) : Boolean; \Description 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. \Errors \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} \SeeAlso \seef{Chown}, \seef{Chmod}, \seem{Access}{2} \end{function} \FPCexample{ex26} \begin{function}{Alarm} \Declaration Function Alarm(Sec : longint) : Longint; \Description Alarm schedules an alarm signal to be delivered to your process in \var{Sec} seconds. When \var{Sec} seconds have elapsed, Linux will send a \var{SIGALRM} signal to the current process. If \var{Sec} is zero, then no new alarm will be set. Whatever the value of \var{Sec}, any previous alarm is cancelled. The function returns the number of seconds till the previously scheduled alarm was due to be delivered, or zero if there was none. \Errors{None} \end{function} \FPCexample{ex59} \begin{function}{AssignPipe} \Declaration Function AssignPipe(var pipe\_in,pipe\_out:longint):boolean; Function AssignPipe(var pipe\_in,pipe\_out:text):boolean; Function AssignPipe(var pipe\_in,pipe\_out:file):boolean; \Description \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}. This call is overloaded. The in and out pipe can take three forms: an typed or untyped file, a text file or a file descriptor. If a text file is passed then reading and writing from/to the pipe can be done through the usual \var{Readln(Pipe\_in,...)} and \var{Writeln (Pipe\_out,...)} procedures. The function returns \var{True} if everything went succesfully, \var{False} otherwise. \Errors In case the function fails and returns \var{False}, \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} \SeeAlso \seep{POpen}, \seef{MkFifo}, \seem{pipe}{2} \end{function} \FPCexample{ex36} \begin{function}{AssignStream} \Declaration Function AssignStream(Var StreamIn,Streamout:text; Const Prog:String) : longint; Function AssignStream(var StreamIn, StreamOut, StreamErr: Text; const prog: String): LongInt; \Description \var{AssignStream} creates a 2 or 3 pipes, i.e. two (or three) file objects, one for input, one for output,(and one for standard error) the other ends of these pipes are connected to standard input and output (and standard error) 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 can be read from \var{StreamIn}. Whatever is written by \var{Prog} to it's standard error read from \var{StreamErr}, if present. Reading and writing happens through the usual \var{Readln(StreamIn,...)} and \var{Writeln (StreamOut,...)} procedures. {\em Remark:} You should {\em not} use \var{Reset} or \var{Rewrite} on a file opened with \var{POpen}. This will close the file before re-opening it again, thereby closing the connection with the program. The function returns the process ID of the spawned process, or -1 in case of error. \Errors In case of error (return value -1) \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 \SeeAlso \seef{AssignPipe}, \seep{POpen},\seem{pipe}{2} \end{function} \FPCexample{ex38} \begin{function}{BaseName} \Declaration Function BaseName (Const Path;Const Suf : Pathstr) : Pathstr; \Description 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. \Errors None. \SeeAlso \seef{DirName}, \seef{FExpand}, \seem{Basename}{1} \end{function} \FPCexample{ex48} \begin{procedure}{CFMakeRaw} \Declaration Procedure CFMakeRaw (var Tios:TermIOS); \Description \var{CFMakeRaw} Sets the flags in the \var{Termios} structure \var{Tios} to a state so that the terminal will function in Raw Mode. \Errors None. \SeeAlso \seep{CFSetOSpeed}, \seep{CFSetISpeed}, \seem{termios}{2} \end{procedure} For an example, see \seef{TCGetAttr}. \begin{procedure}{CFSetISpeed} \Declaration Procedure CFSetISpeed (var Tios:TermIOS;Speed:Longint); \Description \var{CFSetISpeed} Sets the input baudrate in the \var{TermIOS} structure \var{Tios} to \var{Speed}. \Errors None. \SeeAlso \seep{CFSetOSpeed}, \seep{CFMakeRaw}, \seem{termios}{2} \end{procedure} \begin{procedure}{CFSetOSpeed} \Declaration Procedure CFSetOSpeed (var Tios:TermIOS;Speed:Longint); \Description \var{CFSetOSpeed} Sets the output baudrate in the \var{Termios} structure \var{Tios} to \var{Speed}. \Errors None. \SeeAlso \seep{CFSetISpeed}, \seep{CFMakeRaw}, \seem{termios}{2} \end{procedure} \begin{function}{Chown} \Declaration Function Chown (Path : Pathstr;NewUid,NewGid : Longint) : Boolean; \Description \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 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} \SeeAlso \seef{Chmod}, \seef{Access}, \seem{Chown}(2) \end{function} \FPCexample{ex24} \begin{function}{Chmod} \Declaration Function Chmod (Path : Pathstr;NewMode : Longint) : Boolean; \Description \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 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} \SeeAlso \seef{Chown}, \seef{Access}, \seem{Chmod}(2), \seef{Octal} \end{function} \FPCexample{ex23} \begin{function}{Clone} \Declaration TCloneFunc=function(args:pointer):longint;cdecl; Clone(func:TCloneFunc;sp:pointer;flags:longint;args:pointer):longint; \Description Clone creates a child process which is a copy of the parent process, just like \seef{Fork} does. In difference with \var{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 \var{Func}, and passes it \var{Args}. The return value of \var{Func} is either the explicit return value of the function, or the exit code of the child process. The \var{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 \var{Flags} determine the behaviour of the \var{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: \begin{description} \item[CLONE\_VM] Parent and child share the same memory space, including memory (un)mapped with subsequent \var{mmap} calls. \item[CLONE\_FS] Parent and child have the same view of the filesystem; the \var{chroot}, \var{chdir} and \var{umask} calls affect both processes. \item[CLONE\_FILES] the file descriptor table of parent and child is shared. \item[CLONE\_SIGHAND] the parent and child share the same table of signal handlers. The signal masks are different, though. \item[CLONE\_PID] PArent and child have the same process ID. \end{description} 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. \begin{description} \item [sys\_eagain] Too many processes are running. \item [sys\_enomem] Not enough memory to create child process. \end{description} \SeeAlso \seef{Fork}, \seem{clone}{2} \end{function} \FPCexample{ex71} \begin{function}{CloseDir} \Declaration Function CloseDir (p:pdir) : integer; \Description \var{CloseDir} closes the directory pointed to by \var{p}. It returns zero if the directory was closed succesfully, -1 otherwise. \Errors Errors are returned in LinuxError. \SeeAlso \seef{OpenDir}, \seef{ReadDir}, \seep{SeekDir}, \seef{TellDir}, \seem{closedir}{3} \end{function} For an example, see \seef{OpenDir}. \begin{function}{CreateShellArgV} \Declaration function CreateShellArgV(const prog:string):ppchar; function CreateShellArgV(const prog:Ansistring):ppchar; \Description \var{CreateShellArgV} creates an array of 3 \var{PChar} pointers that can be used as arguments to \var{ExecVE} the first elements in the array will contain \var{/bin/sh}, the second will contain \var{-c}, and the third will contain \var{prog}. The function returns a pointer to this array, of type \var{PPChar}. \Errors None. \SeeAlso \seef{Shell} \end{function} \FPCexample{ex61} \begin{function}{DirName} \Declaration Function DirName (Const Path : Pathstr) : Pathstr; \Description 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. \Errors None. \SeeAlso \seef{BaseName}, \seef{FExpand}, \seem{Dirname}{1} \end{function} \FPCexample{ex47} \begin{function}{Dup} \Declaration Function Dup(oldfile:longint;var newfile:longint):Boolean; Function Dup(var oldfile,newfile:text):Boolean; Function Dup(var oldfile,newfile:file):Boolean; \Description Makes \var{NewFile} an exact copy of \var{OldFile}, after having flushed the buffer of \var{OldFile} in case it is a Text file or untyped file. 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. The function returns \var{False} in case of an error, \var{True} if successful. \Errors In case of errors, \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} \SeeAlso \seef{Dup2}, \seem{Dup}{2} \end{function} \FPCexample{ex31} \begin{function}{Dup2} \Declaration Function Dup2(oldfile,newfile:longint):Boolean; Function Dup2(var oldfile,newfile:text):Boolean; Function Dup2(var oldfile,newfile:file):Boolean; \Description Makes \var{NewFile} an exact copy of \var{OldFile}, after having flushed the buffer of \var{OldFile} in the case of text or untyped files. \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. The function returns \var{True} if succesful, false otherwise. \Errors In case of error, \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} \SeeAlso \seef{Dup}, \seem{Dup2}{2} \end{function} \FPCexample{ex32} \begin{procedure}{EpochToLocal} \Declaration Procedure EpochToLocal (Epoch : Longint; var Year,Month,Day,Hour,Minute,Second : Word); \Description Converts the epoch time (=Number of seconds since 00:00:00 , January 1, 1970, corrected for your time zone ) to local date and time. This function takes into account the timzeone settings of your system. \Errors None \SeeAlso \seef{GetEpochTime}, \seef{LocalToEpoch}, \seep{GetTime},\seep{GetDate} \end{procedure} \FPCexample{ex3} \begin{procedure}{Execl} \Declaration Procedure Execl (Path : pathstr); \Description 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 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} \SeeAlso \seep{Execve}, \seep{Execv}, \seep{Execvp}, \seep{Execle}, \seep{Execlp}, \seef {Fork}, \seem{execvp}{3} \end{procedure} \FPCexample{ex10} \begin{procedure}{Execle} \Declaration Procedure Execle (Path : pathstr, Ep : ppchar); \Description 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 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} \SeeAlso \seep{Execve}, \seep{Execv}, \seep{Execvp}, \seep{Execl}, \seep{Execlp}, \seef {Fork}, \seem{execvp}{3} \end{procedure} \FPCexample{ex11} \begin{procedure}{Execlp} \Declaration Procedure Execlp (Path : pathstr); \Description 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 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} \SeeAlso \seep{Execve}, \seep{Execv}, \seep{Execvp}, \seep{Execle}, \seep{Execl}, \seef {Fork}, \seem{execvp}{3} \end{procedure} \FPCexample{ex12} \begin{procedure}{Execv} \Declaration Procedure Execv (Path : pathstr; args : ppchar); \Description 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 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} \SeeAlso \seep{Execve}, \seep{Execvp}, \seep{Execle}, \seep{Execl}, \seep{Execlp}, \seef {Fork}, \seem{execv}{3} \end{procedure} \FPCexample{ex8} \begin{procedure}{Execve} \Declaration Procedure Execve(Path:pchar;args:ppchar;ep:ppchar); Procedure Execve (Path : pathstr; args,ep : ppchar); \Description 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 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} \SeeAlso \seep{Execve}, \seep{Execv}, \seep{Execvp} \seep{Execle}, \seep{Execl}, \seep{Execlp}, \seef {Fork}, \seem{execve}{2} \end{procedure} \FPCexample{ex7} \begin{procedure}{Execvp} \Declaration Procedure Execvp (Path : pathstr; args : ppchar); \Description 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 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} \SeeAlso \seep{Execve}, \seep{Execv}, \seep{Execle}, \seep{Execl}, \seep{Execlp}, \seef {Fork}, \seem{execvp}{3} \end{procedure} \FPCexample{ex9} \begin{procedurel}{FD\_ZERO}{FDZero} \Declaration Procedure FD\_ZERO (var fds:fdSet); \Description \var{FD\_ZERO} clears all the filedescriptors in the file descriptor set \var{fds}. \Errors None. \SeeAlso \seef{Select}, \seef{SelectText}, \seef{GetFS}, \seepl{FD\_Clr}{FDClr}, \seepl{FD\_Set}{FDSet}, \seefl{FD\_IsSet}{FDIsSet} \end{procedurel} For an example, see \seef{Select}. \begin{procedurel}{FD\_Clr}{FDClr} \Declaration Procedure FD\_Clr (fd:longint;var fds:fdSet); \Description \var{FD\_Clr} clears file descriptor \var{fd} in filedescriptor s et \var{fds}. \Errors None. \SeeAlso \seef{Select}, \seef{SelectText}, \seef{GetFS}, \seepl{FD\_ZERO}{FDZero}, \seepl{FD\_Set}{FDSet}, \seefl{FD\_IsSet}{FDIsSet} \end{procedurel} For an example, see \seef{Select}. \begin{functionl}{FD\_IsSet}{FDIsSet} \Declaration Function FD\_IsSet (fd:longint;var fds:fdSet) : boolean; \Description \var{FD\_Set} Checks whether file descriptor \var{fd} in filedescriptor set \var{fds} is set. \Errors None. \SeeAlso \seef{Select}, \seef{SelectText}, \seef{GetFS}, \seepl{FD\_ZERO}{FDZero}, \seepl{FD\_Clr}{FDClr}, \seepl{FD\_Set}{FDSet} \end{functionl} For an example, see \seef{Select}. \begin{procedurel}{FD\_Set}{FDSet} \Declaration Procedure FD\_Set (fd:longint;var fds:fdSet); \Description \var{FD\_Set} sets file descriptor \var{fd} in filedescriptor set \var{fds}. \Errors None. \SeeAlso \seef{Select}, \seef{SelectText}, \seef{GetFS},\seepl{FD\_ZERO}{FDZero}, \seepl{FD\_Clr}{FDClr}, \seefl{FD\_IsSet}{FDIsSet} \end{procedurel} For an example, see \seef{Select}. \begin{function}{fdClose} \Declaration Function fdClose (fd:longint) : boolean; \Description \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 Errors are returned in LinuxError \SeeAlso \seef{fdOpen}, \seef{fdRead}, \seef{fdWrite},\seef{fdTruncate}, \seef{fdFlush}, seef{FdSeek} \end{function} For an example, see \seef{fdOpen}. \begin{function}{fdFlush} \Declaration Function fdFlush (fd:Longint) : boolean; \Description \var{fdflush} flushes the Linux kernel file buffer, so the file is actually written to disk. This is NOT the same as the internal buffer, maintained by Free Pascal. The function returns \var{True} if the call was successful, \var{false} if an error occurred. \Errors Errors are returned in LinuxError. \SeeAlso \seef{fdOpen}, \seef{fdClose}, \seef{fdRead},\seef{fdWrite}, \seef{fdTruncate}, \seef{fdSeek} \end{function} For an example, see \seef{fdRead}. \begin{function}{fdOpen} \Declaration Function fdOpen(PathName:String;flags:longint):longint; Function fdOpen(PathName:Pchar ;flags:longint):longint; Function fdOpen(PathName:String;flags,mode:longint):longint; Function fdOpen(PathName:Pchar ;flags,mode:longint):longint; \Description \var{fdOpen} opens a file in \var{PathName} with flags \var{flags} One of the following: \begin{description} \item [Open\_RdOnly] File is opened Read-only. \item [Open\_WrOnly] File is opened Write-only. \item [Open\_RdWr] File is opened Read-Write. \end{description} The flags may be\var{OR}-ed with one of the following constants: \begin{description} \item [Open\_Accmode] File is opened \item [Open\_Creat] File is created if it doesn't exist. \item [Open\_Excl] If the file is opened with \var{Open\_Creat} and it already exists, the call wil fail. \item [Open\_NoCtty] If the file is a terminal device, it will NOT become the process' controlling terminal. \item [Open\_Trunc] If the file exists, it will be truncated. \item [Open\_Append] the file is opened in append mode. {\em Before each write}, the file pointer is positioned at the end of the file. \item [Open\_NonBlock] The file is opened in non-blocking mode. No operation on the file descriptor will cause the calling process to wait till. \item [Open\_NDelay] Idem as \var{Open\_NonBlock} \item [Open\_Sync] The file is opened for synchronous IO. Any write operation on the file will not return untill the data is physically written to disk. \item [Open\_NoFollow] if the file is a symbolic link, the open fails. (\linux 2.1.126 and higher only) \item [Open\_Directory] if the file is not a directory, the open fails. (\linux 2.1.126 and higher only) \end{description} \var{PathName} can be of type \var{PChar} or \var{String}. 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 Errors are returned in LinuxError \SeeAlso \seef{fdClose}, \seef{fdRead}, \seef{fdWrite},\seef{fdTruncate}, \seef{fdFlush}, \seef{fdSeek} \end{function} \FPCexample{ex19} \begin{function}{fdRead} \Declaration Function fdRead (fd:longint;var buf;size:longint) : longint; \Description \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 Errors are returned in LinuxError. \SeeAlso \seef{fdOpen}, \seef{fdClose}, \seef{fdWrite},\seef{fdTruncate}, \seef{fdFlush}, \seef{fdSeek} \end{function} \FPCexample{ex20} \begin{function}{fdSeek} \Declaration Function fdSeek (fd,Pos,SeekType:longint) : longint; \Description \var{fdSeek} sets the current fileposition of file \var{fd} to \var{Pos}, starting from \var{SeekType}, which can be one of the following: \begin{description} \item [Seek\_Set] \ \var{Pos} is the absolute position in the file. \item [Seek\_Cur] \ \var{Pos} is relative to the current position. \item [Seek\_end] \ \var{Pos} is relative to the end of the file. \end{description} The function returns the new fileposition, or -1 of an error occurred. \Errors Errors are returned in LinuxError. \SeeAlso \seef{fdOpen}, \seef{fdWrite}, \seef{fdClose}, \seef{fdRead},\seef{fdTruncate}, \seef{fdFlush} \end{function} For an example, see \seef{fdOpen}. \begin{function}{fdTruncate} \Declaration Function fdTruncate (fd,size:longint) : boolean; \Description \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 Errors are returned in LinuxError. \SeeAlso \seef{fdOpen}, \seef{fdClose}, \seef{fdRead},\seef{fdWrite},\seef{fdFlush}, \seef{fdSeek} \end{function} \begin{function}{fdWrite} \Declaration Function fdWrite (fd:longint;var buf;size:longint) : longint; \Description \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 Errors are returned in LinuxError. \SeeAlso \seef{fdOpen}, \seef{fdClose}, \seef{fdRead},\seef{fdTruncate}, \seef{fdSeek}, \seef{fdFlush} \end{function} \begin{function}{FExpand} \Declaration Function FExpand (Const Path: Pathstr) : pathstr; \Description Expands \var {Path} to a full path, starting from root, eliminating directory references such as . and .. from the result. \Errors None \SeeAlso \seef{BaseName},\seef{DirName} \end{function} \FPCexample{ex45} \begin{function}{FLock} \Declaration Function Flock (fd,mode : longint) : boolean; Function Flock (var T : text;mode : longint) : boolean; Function Flock (var F : File;mode : longint) : boolean; \Description \var{FLock} implements file locking. it sets or removes a lock on the file \var{F}. F can be of type \var{Text} or \var{File}, or it can be a \linux filedescriptor (a longint) \var{Mode} can be one of the following constants : \begin{description} \item [LOCK\_SH] \ sets a shared lock. \item [LOCK\_EX] \ sets an exclusive lock. \item [LOCK\_UN] \ unlocks the file. \item [LOCK\_NB] \ This can be OR-ed together with the other. If this is done the application doesn't block when locking. \end{description} The function returns \var{True} if successful, \var{False} otherwise. \Errors If an error occurs, it is reported in \var{LinuxError}. \SeeAlso \seef{Fcntl}, \seem{flock}{2} \end{function} \begin{function}{FNMatch} \Declaration Function FNMatch(const Pattern,Name:string):Boolean; \Description \var{FNMatch} returns \var{True} if the filename in \var{Name} matches the wildcard pattern in \var{Pattern}, \var{False} otherwise. \var{Pattern} can contain the wildcards \var{*} (match zero or more arbitrary characters) or \var{?} (match a single character). \Errors None. \SeeAlso \seef{FSearch}, \seef{FExpand} \end{function} \FPCexample{ex69} \begin{function}{FSearch} \Declaration Function FSearch (Path : pathstr;DirList : string) : Pathstr; \Description 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. \Errors An empty string if no such file was found. \SeeAlso \seef{BaseName}, \seef{DirName}, \seef{FExpand}, \seef{FNMatch} \end{function} \FPCexample{ex46} \begin{procedurel}{FSplit}{LFsplit} \Declaration Procedure FSplit(const Path:PathStr; \\ Var Dir:DirStr;Var Name:NameStr;Var Ext:ExtStr); \Description \var{FSplit} splits a full file name into 3 parts : A \var{Path}, a \var{Name} and an extension (in \var{ext}). The extension is taken to be all letters after the last dot (.). \Errors None. \SeeAlso \seef{FSearch} \end{procedurel} \FPCexample{ex67} \begin{function}{FSStat} \Declaration Function FSStat (Path : Pathstr; Var Info : statfs) : Boolean; Function FSStat (Fd:longint;Var Info:stat) : Boolean; \Description Return in \var{Info} information about the filesystem on which the file \var{Path} resides, or on which the file with file descriptor \var{fd} resides. Info is of type \var{statfs}. The function returns \var{True} if the call was succesfull, \var{False} if the call failed. \Errors \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} \SeeAlso \seef{FStat}, \seef{LStat}, \seem{statfs}{2} \end{function} \FPCexample{ex30} \begin{function}{FStat} \Declaration Function FStat(Path:Pathstr;Var Info:stat):Boolean; Function FStat(Fd:longint;Var Info:stat):Boolean; Function FStat(var F:Text;Var Info:stat):Boolean; Function FStat(var F:File;Var Info:stat):Boolean; \Description \var{FStat} gets information about the file specified in one of the following: \begin{description} \item [Path] a file on the filesystem. \item [Fd] a valid file descriptor. \item [F] an opened text file or untyped file. \end{description} 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. \Errors \var{LinuxError} is used to report errors. \begin{description} \item[sys\_enoent] \var{Path} does not exist. \end{description} \SeeAlso \seef{FSStat}, \seef{LStat}, \seem{stat}{2} \end{function} \FPCexample{ex28} \begin{function}{Fcntl} \Declaration Function Fcntl(Fd:longint;Cmd:Integer):integer; Function Fcntl(var Fd:Text;Cmd:Integer):integer; \Description Read a file's attributes. \var{Fd} is an assigned file, or a valid file descriptor. \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} \Errors \var{LinuxError} is used to report errors. \begin{description} \item[sys\_ebadf] \var{Fd} has a bad file descriptor. \end{description} \SeeAlso \seep{Fcntl}, \seem{Fcntl}{2} \end{function} \begin{procedure}{Fcntl} \Declaration Procedure Fcntl (Fd : text, Cmd : Integer; Arg : longint); Procedure Fcntl (Fd:longint;Cmd:longint;Arg:Longint); \Description Read or Set a file's attributes. \var{Fd} is an assigned file or a valid file descriptor. \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} \Errors \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} \SeeAlso \seef{Fcntl}, \seem{Fcntl}{2}, seef{FLock} \end{procedure} \begin{function}{Fork} \Declaration Function Fork : Longint; \Description 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}). \Errors 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} \SeeAlso \seep{Execve}, \seef{Clone}, \seem{fork}{2} \end{function} \begin{function}{FRename} \Declaration Function FReName (OldName,NewName : Pchar) : Boolean; Function FReName (OldName,NewName : String) : Boolean; \Description \var{FRename} renames the file \var{OldName} to \var{NewName}. \var{NewName} can be in a different directory than \var{OldName}, but it cannot be on another partition (device). Any existing file on the new location will be replaced. If the operation fails, then the \var{OldName} file will be preserved. The function returns \var{True} on succes, \var{False} on failure. \Errors On error, errors are reported in \var{LinuxError}. Possible errors include: \begin{description} \item[sys\_eisdir] \var{NewName} exists and is a directory, but \var{OldName} is not a directory. \item[sys\_exdev] \var{NewName} and \var{OldName} are on different devices. \item[sys\_enotempty or sys\_eexist] \var{NewName} is an existing, non-empty directory. \item[sys\_ebusy] \var{OldName} or \var{NewName} is a directory and is in use by another process. \item[sys\_einval] \var{NewName} is part of \var{OldName}. \item[sys\_emlink] \var{OldPath} or \var{NewPath} already have tha maximum amount of links pointing to them. \item[sys\_enotdir] part of \var{OldName} or \var{NewName} is not directory. \item[sys\_efault] For the \var{pchar} case: One of the pointers points to an invalid address. \item[sys\_eaccess] access is denied when attempting to move the file. \item[sys\_enametoolong] Either \var{OldName} or \var{NewName} is too long. \item[sys\_enoent] a directory component in \var{OldName} or \var{NewName} didn't exist. \item[sys\_enomem] not enough kernel memory. \item[sys\_erofs] \var{NewName} or \var{OldName} is on a read-only file system. \item[sys\_eloop] too many symbolic links were encountered trying to expand \var{OldName} or \var{NewName} \item[sys\_enospc] the filesystem has no room for the new directory entry. \end{description} \SeeAlso \seef{UnLink} \end{function} \begin{procedure}{GetDate} \Declaration Procedure GetDate (Var Year, Month, Day : Word) ; \Description Returns the current date. \Errors None \SeeAlso \seef{GetEpochTime}, \seep{GetTime}, \seep{GetDateTime}, \seep{EpochToLocal} \end{procedure} \FPCexample{ex6} \begin{procedure}{GetDateTime} \Declaration Procedure GetDateTime(Var Year,Month,Day,hour,minute,second:Word); \Description Returns the current date and time. The time is corrected for the local time zone. This procedure is equivalent to the \seep{GetDate} and \var{GetTime} calls. \Errors None \SeeAlso \seef{GetEpochTime}, \seep{GetTime}, \seep{EpochToLocal}, \seep{GetDate} \end{procedure} \FPCexample{ex60} \begin{function}{GetDomainName} \Declaration Function GetDomainName : String; \Description Get the domain name of the machine on which the process is running. An empty string is returned if the domain is not set. \Errors None. \SeeAlso \seef{GetHostName},seem{Getdomainname}{2} \end{function} \FPCexample{ex39} \begin{function}{GetEGid} \Declaration Function GetEGid : Longint; \Description Get the effective group ID of the currently running process. \Errors None. \SeeAlso \seef{GetGid}, \seem{getegid}{2} \end{function} \FPCexample{ex18} \begin{function}{GetEUid} \Declaration Function GetEUid : Longint; \Description Get the effective user ID of the currently running process. \Errors None. \SeeAlso \seef{GetEUid}, \seem{geteuid}{2} \end{function} \FPCexample{ex17} \begin{function}{GetEnv} \Declaration Function GetEnv (P : String) : PChar; \Description 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. \Errors None. \SeeAlso \seem{sh}{1}, \seem{csh}{1} \end{function} \FPCexample{ex41} \begin{function}{GetEpochTime} \Declaration Function GetEpochTime : longint; \Description 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. \Errors no errors \SeeAlso \seep{EpochToLocal}, \seep{GetTime}, \seem{time}{2} \end{function} \FPCexample{ex1} \begin{function}{GetFS} \Declaration Function GetFS (Var F : Any File Type) : Longint; \Description \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. \Errors In case the file was not opened, then -1 is returned. \SeeAlso \seef{Select} \end{function} \FPCexample{ex34} \begin{function}{GetGid} \Declaration Function GetGid : Longint; \Description Get the real group ID of the currently running process. \Errors None. \SeeAlso \seef{GetEGid}, \seem{getgid}{2} \end{function} \FPCexample{ex18} \begin{function}{GetHostName} \Declaration Function GetHostName : String; \Description Get the hostname of the machine on which the process is running. An empty string is returned if hostname is not set. \Errors None. \SeeAlso \seef{GetDomainName},seem{Gethostname}{2} \end{function} \FPCexample{ex40} \begin{procedure}{GetLocalTimezone} \Declaration procedure GetLocalTimezone(timer:longint;var leap\_correct,leap\_hit:longint); procedure GetLocalTimezone(timer:longint); \Description \var{GetLocalTimeZone} returns the local timezone information. It also initializes the \var{TZSeconds} variable, which is used to correct the epoch time to local time. There should never be any need to call this function directly. It is called by the initialization routines of the Linux unit. \SeeAlso \seef{GetTimezoneFile}, \seep{ReadTimezoneFile} \end{procedure} \begin{function}{GetPid} \Declaration Function GetPid : Longint; \Description Get the Process ID of the currently running process. \Errors None. \SeeAlso \seef{GetPPid}, \seem{getpid}{2} \end{function} \FPCexample{ex16} \begin{function}{GetPPid} \Declaration Function GetPPid : Longint; \Description Get the Process ID of the parent process. \Errors None. \SeeAlso \seef{GetPid}, \seem{getppid}{2} \end{function} \FPCexample{ex16} \begin{function}{GetPriority} \Declaration Function GetPriority (Which,Who : Integer) : Integer; \Description 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. \Errors 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} \SeeAlso \seef{SetPriority}, \seep{Nice}, \seem{Getpriority}{2} \end{function} For an example, see \seep{Nice}. \begin{procedure}{GetTime} \Declaration procedure GetTime(var hour,min,sec,msec,usec:word); procedure GetTime(var hour,min,sec,sec100:word); procedure GetTime(var hour,min,sec:word); \Description Returns the current time of the day, adjusted to local time. Upon return, the parameters are filled with \begin{description} \item[hour] Hours since 00:00 today. \item[min] minutes in current hour. \item[sec] seconds in current minute. \item[sec100] hundreds of seconds in current second. \item[msec] milliseconds in current second. \item[usec] microseconds in current second. \end{description} \Errors None \SeeAlso \seef{GetEpochTime}, \seep{GetDate}, \seep{GetDateTime}, \seep{EpochToLocal} \end{procedure} \FPCexample{ex5} \begin{procedure}{GetTimeOfDay} \Declaration Procedure GetTimeOfDay(var tv:timeval); \Description \var{GetTimeOfDay} returns the number of seconds since 00:00, January 1 1970, GMT in a \var{timeval} record. This time NOT corrected any way, not taking into account timezones, daylight savings time and so on. It is simply a wrapper to the kernel system call. To get the local time, \seep{GetTime}. \Errors None. \SeeAlso \seep{GetTime}, \seef{GetTimeOfDay} \end{procedure} \begin{function}{GetTimeOfDay} \Declaration Function GetTimeOfDay:longint; \Description \var{GetTimeOfDay} returns the number of seconds since 00:00, January 1 1970, GMT. This time NOT corrected any way, not taking into account timezones, daylight savings time and so on. It is simply a wrapper to the kernel system call. To get the local time, \seep{GetTime}. \Errors None. \SeeAlso \seep{GetTimeOfDay}, \seep{GetTime} \end{function} \begin{function}{GetTimezoneFile} \Declaration function GetTimezoneFile:string; \Description \var{GetTimezoneFile} returns the location of the current timezone file. The location of file is determined as follows: \begin{enumerate} \item If \file{/etc/timezone} exists, it is read, and the contents of this file is returned. This should work on Debian systems. \item If \file{/usr/lib/zoneinfo/localtime} exists, then it is returned. (this file is a symlink to the timezone file on SuSE systems) \item If \file{/etc/localtime} exists, then it is returned. (this file is a symlink to the timezone file on RedHat systems) \end{enumerate} \Errors If no file was found, an empty string is returned. \SeeAlso \seep{ReadTimezoneFile} \end{function} \begin{function}{GetUid} \Declaration Function GetUid : Longint; \Description Get the real user ID of the currently running process. \Errors None. \SeeAlso \seef{GetEUid}, \seem{getuid}{2} \end{function} \FPCexample{ex17} \begin{function}{Glob} \Declaration Function Glob (Const Path : Pathstr) : PGlob; \Description 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. \Errors 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} \SeeAlso \seep{GlobFree}, \seem{Glob}{3} \end{function} \FPCexample{ex49} \begin{procedure}{GlobFree} \Declaration Procedure GlobFree (Var P : Pglob); \Description Releases the memory, occupied by a pglob structure. \var{P} is set to nil. \Errors None \SeeAlso \seef{Glob} \end{procedure} For an example, see \seef{Glob}. \begin{procedure}{IOCtl} \Declaration Procedure IOCtl (Handle,Ndx: Longint; Data: Pointer); \Description 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 Errors are reported in LinuxError. They are very dependent on the used function, that's why we don't list them here \SeeAlso \seem{ioctl}{2} \end{procedure} \FPCexample{ex54} \begin{function}{IOperm} \Declaration Function IOperm (From,Num : Cadinal; Value : Longint) : boolean; \Description \var{IOperm} sets permissions on \var{Num} ports starting with port \var{From} to \var{Value}. The function returns \var{True} if the call was successfull, \var{False} otherwise. {\em Remark:} \begin{itemize} \item This works ONLY as root. \item Only the first \var{0x03ff} ports can be set. \item When doing a \seef{Fork}, the permissions are reset. When doing a \seep{Execve} they are kept. \end{itemize} \Errors Errors are returned in \var{LinuxError} \SeeAlso \seem{ioperm}{2} \end{function} \begin{function}{IsATTY} \Declaration Function IsATTY (var f) : Boolean; \Description 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. \Errors No errors are reported \SeeAlso \seep{IOCtl},\seef{TTYName} \end{function} \begin{functionl}{S\_ISBLK}{ISBLK} \Declaration Function S\_ISBLK (m:integer) : boolean; \Description \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}. \Errors \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} \SeeAlso ISLNK. \end{functionl} \begin{functionl}{S\_ISCHR}{ISCHR} \Declaration Function S\_ISCHR (m:integer) : boolean; \Description \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}. \Errors \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} \SeeAlso ISLNK. \end{functionl} \begin{functionl}{S\_ISDIR}{ISDIR} \Declaration Function S\_ISDIR (m:integer) : boolean; \Description \var{S\_ISDIR} checks the file mode \var{m} to see whether the file is a directory. If so it returns \var{True} \Errors \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} \SeeAlso ISLNK. \end{functionl} \begin{functionl}{S\_ISFIFO}{ISFIFO} \Declaration Function S\_ISFIFO (m:integer) : boolean; \Description \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}. \Errors \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} \SeeAlso ISLNK. \end{functionl} \begin{functionl}{S\_ISLNK}{ISLNK} \Declaration Function S\_ISLNK (m:integer) : boolean; \Description \var{S\_ISLNK} checks the file mode \var{m} to see whether the file is a symbolic link. If so it returns \var{True} \Errors \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} \SeeAlso \end{functionl} \FPCexample{ex53} \begin{functionl}{S\_ISREG}{ISREG} \Declaration Function S\_ISREG (m:integer) : boolean; \Description \var{S\_ISREG} checks the file mode \var{m} to see whether the file is a regular file. If so it returns \var{True} \Errors \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} \SeeAlso ISLNK. \end{functionl} \begin{functionl}{S\_ISSOCK}{ISSOCK} \Declaration Function S\_ISSOCK (m:integer) : boolean; \Description \var{S\_ISSOCK} checks the file mode \var{m} to see whether the file is a socket. If so it returns \var{True}. \Errors \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} \SeeAlso ISLNK. \end{functionl} \begin{function}{Kill} \Declaration Function Kill (Pid : Longint; Sig : Integer) : Integer; \Description 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. \Errors \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} \SeeAlso \seep{SigAction}, \seef{Signal}, \seem{Kill}{2} \end{function} \begin{function}{LStat} \Declaration Function LStat (Path : Pathstr; Var Info : stat) : Boolean; \Description \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. \Errors \var{LinuxError} is used to report errors. \begin{description} \item[sys\_enoent] \var{Path} does not exist. \end{description} \SeeAlso \seef{FStat}, \seef{FSStat}, \seem{stat}{2} \end{function} \FPCexample{ex29} \begin{function}{Link} \Declaration Function Link (OldPath,NewPath : pathstr) : Boolean; \Description \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 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} \SeeAlso \seef{SymLink}, \seef{UnLink}, \seem{Link}{2} \end{function} \FPCexample{ex21} \begin{function}{LocalToEpoch} \Declaration Function LocalToEpoch (Year,Month,Day,Hour,Minute,Second : Word) : longint; \Description Converts the Local time to epoch time (=Number of seconds since 00:00:00 , January 1, 1970 ). \Errors None \SeeAlso \seef{GetEpochTime}, \seep{EpochToLocal}, \seep{GetTime},\seep{GetDate} \end{function} \FPCexample{ex4} \begin{function}{MkFifo} \Declaration Function MkFifo (PathName: String; Mode : Longint) : Boolean; \Description \var{MkFifo} creates named a named pipe in the filesystem, with name \var{PathName} and mode {Mode}. \Errors \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} \SeeAlso \seep{POpen}, \seef{MkFifo}, \seem{mkfifo}{4} \end{function} \begin{function}{MMap} \Declaration Function MMap(const m:tmmapargs):longint; \Description \var{MMap} maps or unmaps files or devices into memory. The different fields of the argument \var{m} determine what and how the \var{mmap} maps this: \begin{description} \item[address] Address where to mmap the device. This address is a hint, and may not be followed. \item[size] Size (in bytes) of area to be mapped. \item[prot] Protection of mapped memory. This is a OR-ed combination of the following constants: \begin{description} \item[PROT\_EXEC] The memory can be executed. \item[PROT\_READ] The memory can be read. \item[PROT\_WRITE] The memory can be written. \item[PROT\_NONE] The memory can not be accessed. \end{description} \item[flags] Contains some options for the mmap call. It is an OR-ed combination of the following constants: \begin{description} \item[MAP\_FIXED] Do not map at another address than the given address. If the address cannot be used, \var{MMap} will fail. \item[MAP\_SHARED] Share this map with other processes that map this object. \item[MAP\_PRIVATE] Create a private map with copy-on-write semantics. \item[MAP\_ANONYMOUS] \var{fd} does not have to be a file descriptor. \end{description} One of the options \var{MAP\_SHARED} and \var{MAP\_PRIVATE} must be present, but not both at the same time. \item[fd] File descriptor from which to map. \item[offset] Offset to be used in file descriptor fd. \end{description} The function returns a pointer to the mapped memory, or a -1 in case of en error. \Errors On error, -1 is returned and LinuxError is set to the error code: \begin{description} \item[Sys\_EBADF] \var{fd} is not a valid file descriptor and \var{MAP\_ANONYMOUS} was not specified. \item[Sys\_EACCES] \var{MAP\_PRIVATE} was specified, but fd is not open for reading. Or \var{MAP\_SHARED} was asked and \var{PROT\_WRITE} is set, fd is not open for writing \item[Sys\_EINVAL] One of the record fields \var{Start}, \var{length} or \var{offset} is invalid. \item[Sys\_ETXTBUSY] \var{MAP\_DENYWRITE} was set but the object specified by fd is open for writing. \item[Sys\_EAGAIN] \var{fd} is locked, or too much memory is locked. \item[Sys\_ENOMEM] Not enough memory for this operation. \end{description} \SeeAlso \seef{MUnMap}, \seem{mmap}{2} \end{function} \FPCexample{ex66} \begin{function}{MUnMap} \Declaration function MUnMap (P : Pointer; Size : Longint) : Boolean; \Description \var{MUnMap} unmaps the memory block of size \var{Size}, pointed to by \var{P}, which was previously allocated with \seef{MMap}. The function returns \var{True} if successful, \var{False} otherwise. \Errors In case of error the function returns \var{False} and \var{LinuxError} is set to an error value. See \seef{MMap} for possible error values. \SeeAlso \seef{MMap}, \seem{munmap}{2} \end{function} For an example, see \seef{MMap}. \begin{function}{NanoSleep} \Declaration Function NanoSleep(const req : timespec;var rem : timespec) : longint; \Description \var{NanoSleep} suspends the process till a time period as specified in \var{req} has passed. Then the function returns. If the call was interrupted (e.g. by some signal) then the function may return earlier, and \var{rem} will contain the remaining time till the end of the intended period. In this case the return value will be -1, and \var{LinuxError} will be set to \var{EINTR} If the function returns without error, the return value is zero. \Errors If the call was interrupted, -1 is returned, and \var{LinuxError} is set to \var{EINTR}. If invalid time values were specified, then -1 is returned and \var{LinuxError} is set to \var{EINVAL}. \SeeAlso \seep{Pause}, \seef{Alarm} \end{function} \FPCexample{ex70} \begin{procedure}{Nice} \Declaration Procedure Nice ( N : Integer); \Description \var{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 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} \SeeAlso \seef{GetPriority}, \seef{SetPriority}, \seem{Nice}{2} \end{procedure} \FPCexample{ex15} \begin{function}{Octal} \Declaration Function Octal(l:longint):longint; \Description \var{Octal} will convert a number specified as an octal number to it's decimal value. This is useful for the \seef{Chmod} call, where permissions are specified as octal numbers. \Errors No checking is performed whether the given number is a correct Octal number. e.g. specifying \var{998} is possible; the result will be wrong in that case. \SeeAlso \seef{Chmod}. \end{function} \FPCexample{ex68} \begin{function}{OpenDir} \Declaration Function OpenDir (f:pchar) : pdir; Function OpenDir (f:string) : pdir; \Description \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 Errors are returned in LinuxError. \SeeAlso \seef{CloseDir}, \seef{ReadDir}, \seep{SeekDir}, \seef{TellDir}, \seem{opendir}{3} \end{function} \FPCexample{ex35} \begin{procedure}{pause} \Declaration Procedure Pause; \Description \var{Pause} puts the process to sleep and waits until the application receives a signal. If a signal handler is installed for the received sigal, the handler will be called and after that pause will return control to the process. \Errors None. \end{procedure} For an example, see \seef{Alarm}. \begin{function}{PClose} \Declaration Function PClose (Var F : FileType) : longint; \Description \var{PClose} closes a file opened with \var{POpen}. It waits for the command to complete, and then returns the exit status of the command. \Errors \var{LinuxError} is used to report errors. If it is different from zero, the exit status is not valid. \SeeAlso \seep{POpen} \end{function} For an example, see \seep{POpen} \begin{procedure}{POpen} \Declaration Procedure POpen (Var F : FileType; Cmd : pathstr; rw : char); \Description 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 prior to using it. \var{F} can be of type \var{Text} or \var{File}. A file opened with \var {POpen} can be closed with \var{Close}, but also with \seef{PClose}. The result is the same, but \var{PClose} returns the exit status of the command \var{Cmd}. \Errors Errors are reported in \var{LinuxError} and are essentially those of the Execve, Dup and AssignPipe commands. \SeeAlso \seef{AssignPipe}, \seem{popen}{3}, \seef{PClose} \end{procedure} \FPCexample{ex37} \begin{function}{ReadDir} \Declaration Function ReadDir (p:pdir) : pdirent; \Description \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 Errors are returned in LinuxError. \SeeAlso \seef{CloseDir}, \seef{OpenDir}, \seep{SeekDir}, \seef{TellDir}, \seem{readdir}{3} \end{function} For an example, see \seef{OpenDir}. \begin{function}{ReadLink} \Declaration Function ReadLink(name,linkname:pchar;maxlen:longint):longint; Function ReadLink(name:pathstr):pathstr; \Description \var{ReadLink} returns the file the symbolic link \var{name} is pointing to. The first form of this function accepts a buffer \var{linkname} of length \var{maxlen} where the filename will be stored. It returns the actual number of characters stored in the buffer. The second form of the function returns simply the name of the file. \Errors On error, the first form of the function returns -1; the second one returns an empty string. \var{LinuxError} is set to report errors: \begin{description} \item[SYS\_ENOTDIR] A part of the path in \var{Name} is not a directory. \item[SYS\_EINVAL] maxlen is not positive, or the file is not a symbolic link. \item[SYS\_ENAMETOOLONG] A pathname, or a component of a pathname, was too long. \item[SYS\_ENOENT] the link \var{name} does not exist. \item[SYS\_EACCES] No permission to search a directory in the path \item[SYS\_ELOOP] Too many symbolic links were encountered in trans­ lating the pathname. \item[SYS\_EIO] An I/O error occurred while reading from the file system. \item[SYS\_EFAULT] The buffer is not part of the the process's memory space. \item[SYS\_ENOMEM] Not enough kernel memory was available. \end{description} \SeeAlso \seef{SymLink} \end{function} \FPCexample{ex62} \begin{procedure}{ReadPort} \Declaration Procedure ReadPort (Port : Longint; Var Value : Byte); Procedure ReadPort (Port : Longint; Var Value : Word); Procedure ReadPort (Port : Longint; Var Value : Longint); \Description \var{ReadPort} reads one Byte, Word or Longint from port \var{Port} into \var{Value}. Note that you need permission to read a port. This permission can be set by the root user with the \seef{IOperm} call. \Errors In case of an error (not enough permissions read this port), runtime 216 ({\em Access Violation}) will occur. \SeeAlso \seef{IOperm}, \seep{ReadPortB}, \seep{ReadPortW}, \seep{ReadPortL},\seep{WritePort}, \seep{WritePortB}, \seep{WritePortL}, \seep{WritePortW} \end{procedure} \begin{procedure}{ReadPortB} \Declaration Procedure ReadPortB (Port : Longint; Var Buf; Count: longint); Function ReadPortB (Port : Longint): Byte; \Description The procedural form of \var{ReadPortB} reads \var{Count} bytes from port \var{Port} and stores them in \var{Buf}. There must be enough memory allocated at \var{Buf} to store \var{Count} bytes. The functional form of \var{ReadPortB} reads 1 byte from port \var{B} and returns the byte that was read. Note that you need permission to read a port. This permission can be set by the root user with the \seef{IOperm} call. \Errors In case of an error (not enough permissions read this port), runtime 216 ({\em Access Violation}) will occur. \SeeAlso \seef{IOperm}, \seep{ReadPort}, \seep{ReadPortW}, \seep{ReadPortL},\seep{WritePort}, \seep{WritePortB}, \seep{WritePortL}, \seep{WritePortW} \end{procedure} \begin{procedure}{ReadPortL} \Declaration function ReadPortL (Port : Longint): LongInt; Procedure ReadPortL (Port : Longint; Var Buf; Count: longint); \Description The procedural form of \var{ReadPortL} reads \var{Count} longints from port \var{Port} and stores them in \var{Buf}. There must be enough memory allocated at \var{Buf} to store \var{Count} Longints. The functional form of \var{ReadPortB} reads 1 longint from port \var{B} and returns the longint that was read. Note that you need permission to read a port. This permission can be set by the root user with the \seef{IOperm} call. \Errors In case of an error (not enough permissions read this port), runtime 216 ({\em Access Violation}) will occur. \SeeAlso \seef{IOperm}, \seep{ReadPort}, \seep{ReadPortW}, \seep{ReadPortB},\seep{WritePort}, \seep{WritePortB}, \seep{WritePortL}, \seep{WritePortW} \end{procedure} \begin{procedure}{ReadPortW} \Declaration Procedure ReadPortW (Port : Longint; Var Buf; Count: longint); function ReadPortW (Port : Longint): Word; \Description The procedural form of \var{ReadPortB} reads \var{Count} words from port \var{Port} and stores them in \var{Buf}. There must be enough memory allocated at \var{Buf} to store \var{Count} words. The functional form of \var{ReadPortB} reads 1 word from port \var{B} and returns the word that was read. Note that you need permission to read a port. This permission can be set by the root user with the \seef{IOperm} call. \Errors In case of an error (not enough permissions read this port), runtime 216 ({\em Access Violation}) will occur. \SeeAlso \seef{IOperm}, \seep{ReadPort}, \seep{ReadPortB}, \seep{ReadPortL},\seep{WritePort}, \seep{WritePortB}, \seep{WritePortL}, \seep{WritePortW} \end{procedure} \begin{procedure}{ReadTimezoneFile} \Declaration procedure ReadTimezoneFile(fn:string); \Description \var{ReadTimeZoneFile} reads the timezone file \var{fn} and initializes the local time routines based on the information found there. There should be no need to call this function. The initialization routines of the \file{linux} unit call this routine at unit startup. \Errors None. \SeeAlso \seef{GetTimezoneFile}, \seep{GetLocalTimezone} \end{procedure} \begin{procedure}{SeekDir} \Declaration Procedure SeekDir (p:pdir;off:longint); \Description \var{SeekDir} sets the directory pointer to the \var{off}-th entry in the directory structure pointed to by \var{p}. \Errors Errors are returned in LinuxError. \SeeAlso \seef{CloseDir}, \seef{ReadDir}, \seef{OpenDir}, \seef{TellDir}, \seem{seekdir}{3} \end{procedure} For an example, see \seef{OpenDir}. \begin{function}{Select} \Declaration Function Select (N : Longint; \\ var readfds,writefds,exceptfds : PFDset; Var Timeout) : Longint; \Description \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\_ZERO}{FDZero}, \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. \Errors 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} \SeeAlso \seef{SelectText}, \seef{GetFS}, \seepl{FD\_ZERO}{FDZero}, \seepl{FD\_Clr}{FDClr}, \seepl{FD\_Set}{FDSet}, \seefl{FD\_IsSet}{FDIsSet} \end{function} \FPCexample{ex33} \begin{function}{SelectText} \Declaration Function SelectText ( var T : Text; TimeOut :PTime) : Longint; \Description \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. \Errors See \seef{Select}. \var{SYS\_EBADF} can also mean that the file wasn't opened. \SeeAlso \seef{Select}, \seef{GetFS} \end{function} \begin{function}{SetPriority} \Declaration Function SetPriority (Which,Who,Prio : Integer) : Integer; \Description 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. \Errors 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} \SeeAlso \seef{GetPriority}, \seep{Nice}, \seem{Setpriority}{2} \end{function} For an example, see \seep{Nice}. \begin{function}{Shell} \Declaration Function Shell (Command : String) : Longint; \Description \var{Shell} invokes the bash shell (\file{/bin/sh}), and feeds it the command \var{Command} (using the \var{-c} option). The function then waits for the command to complete, and then returns the exit status of the command, or 127 if it could not complete the \seef{Fork} or \seep{Execve} calls. \Errors Errors are reported in LinuxError. \SeeAlso \seep{POpen}, \seef{Fork}, \seep{Execve}, \seem{system}{3} \end{function} \FPCexample{ex56} \begin{procedure}{SigAction} \Declaration Procedure SigAction (Signum : Integer; Var Act,OldAct : PSigActionRec); \Description 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} \Errors \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} \SeeAlso \seep{SigProcMask}, \seef{SigPending}, \seep{SigSuspend}, \seef{Kill}, \seem{Sigaction}{2} \end{procedure} \FPCexample{ex57} \begin{function}{SigPending} \Declaration Function SigPending : SigSet; \Description Sigpending allows the examination of pending signals (which have been raised while blocked.) The signal mask of pending signals is returned. \Errors None \SeeAlso \seep{SigAction}, \seep{SigProcMask}, \seep{SigSuspend}, \seef{Signal}, \seef{Kill}, \seem{Sigpending}{2} \end{function} \begin{procedure}{SigProcMask} \Declaration Procedure SigProcMask (How : Integer; SSet,OldSSet : PSigSet); \Description 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. \Errors \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} \SeeAlso \seep{SigAction}, \seef{SigPending}, \seep{SigSuspend}, \seef{Kill}, \seem{Sigprocmask}{2} \end{procedure} \begin{procedure}{SigRaise} \Declaration Procedure SigRaise(Sig:integer); \Description \var{SigRaise} sends a \var{Sig} signal to the current process. \Errors None. \SeeAlso \seef{Kill}, \seef{GetPid} \end{procedure} \FPCexample{ex65} \begin{procedure}{SigSuspend} \Declaration Procedure SigSuspend (Mask : SigSet); \Description 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. \Errors None \SeeAlso \seep{SigAction}, \seep{SigProcMask}, \seef{SigPending}, \seef{Signal}, \seef{Kill}, \seem{SigSuspend}{2} \end{procedure} \begin{function}{Signal} \Declaration Function Signal (SigNum : Integer; Handler : SignalHandler) : SignalHandler; \Description 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. \Errors \var {LinuxError} is used to report errors : \begin{description} \item[SIG\_ERR] An error occurred. \end{description} \SeeAlso \seep{SigAction},\seef{Kill}, \seem{Signal}{2} \end{function} \FPCexample{ex58} \begin{function}{StringToPPchar} \Declaration Function StringToPPChar(Var S:STring):ppchar; \Description \var{StringToPPChar} splits the string \var{S} in words, replacing any whitespace with zero characters. It returns a pointer to an array of pchars that point to the first letters of the words in S. This array is terminated by a \var{Nil} pointer. The function does {\em not} add a zero character to the end of the string unless it ends on whitespace. The function reserves memory on the heap to store the array of \var{PChar}; The caller is responsible for freeing this memory. This function can be called to create arguments for the various \var{Exec} calls. \Errors None. \SeeAlso \seef{CreateShellArgV}, \seep{Execve}, \seep{Execv} \end{function} \FPCexample{ex70} \begin{function}{SymLink} \Declaration Function SymLink (OldPath,NewPath : pathstr) : Boolean; \Description \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 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} \SeeAlso \seef{Link}, \seef{UnLink}, \seef{ReadLink}, \seem{Symlink}{2} \end{function} \FPCexample{ex22} \begin{function}{SysInfo} \Declaration Function SysInfo(var Info:TSysinfo):Boolean; \Description \var{SysInfo} returns system information in \var{Info}. Returned information in \var{Info} includes: \begin{description} \item[uptime] Number of seconds since boot. \item[loads] 1, 5 and 15 minute load averages. \item[totalram] total amount of main memory. \item[freeram] amount of free memory. \item[sharedram] amount of shared memory \item[bufferram] amount of memory used by buffers. \item[totalswap] total amount of swapspace. \item[freeswap] amount of free swapspace. \item[procs] number of current processes. \end{description} \Errors None. \SeeAlso \seep{Uname} \end{function} \FPCexample{ex64} \begin{function}{TCDrain} \Declaration Function TCDrain (Fd:longint) : Boolean; \Description \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 Errors are reported in LinuxError \SeeAlso \seem{termios}{2} \end{function} \begin{function}{TCFlow} \Declaration Function TCFlow (Fd,Act:longint) : Boolean; \Description \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 Errors are reported in LinuxError. \SeeAlso \seem{termios}{2} \end{function} \begin{function}{TCFlush} \Declaration Function TCFlush (Fd,QSel:longint) : Boolean; \Description \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 Errors are reported in LinuxError. \SeeAlso \seem{termios}{2} \end{function} \begin{function}{TCGetAttr} \Declaration Function TCGetAttr (fd:longint;var tios:TermIOS) : Boolean; \Description \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 Errors are reported in LinuxError \SeeAlso \seef{TCSetAttr}, \seem{termios}{2} \end{function} \FPCexample{ex55} \begin{function}{TCGetPGrp} \Declaration Function TCGetPGrp (Fd:longint;var Id:longint) : boolean; \Description \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 Errors are reported in LinuxError \SeeAlso \seem{termios}{2} \end{function} \begin{function}{TCSendBreak} \Declaration Function TCSendBreak (Fd,Duration:longint) : Boolean; \Description \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 Errors are reported in LinuxError. \SeeAlso \seem{termios}{2} \end{function} \begin{function}{TCSetAttr} \Declaration Function TCSetAttr (Fd:longint;OptAct:longint;var Tios:TermIOS) : Boolean; \Description \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 Errors are reported in LinuxError. \SeeAlso \seef{TCGetAttr}, \seem{termios}{2} \end{function} For an example, see \seef{TCGetAttr}. \begin{function}{TCSetPGrp} \Declaration Function TCSetPGrp (Fd,Id:longint) : boolean; \Description \var{TCSetPGrp} Sets the Process Group Id to \var{Id}. The function returns \var{True} if the call was successful, \var{False} otherwise. \Errors Errors are returned in LinuxError. \SeeAlso \seef{TCGetPGrp}, \seem{termios}{2} \end{function} For an example, see \seef{TCGetPGrp}. \begin{function}{TTYName} \Declaration Function TTYName (var f) : String; \Description 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} \Errors Returns an empty string in case of an error. \var{Linuxerror} may be set to indicate what error occurred, but this is uncertain. \SeeAlso \seef{IsATTY},\seep{IOCtl} \end{function} \begin{function}{TellDir} \Declaration Function TellDir (p:pdir) : longint; \Description \var{TellDir} returns the current location in the directory structure pointed to by \var{p}. It returns -1 on failure. \Errors Errors are returned in LinuxError. \SeeAlso \seef{CloseDir}, \seef{ReadDir}, \seep{SeekDir}, \seef{OpenDir}, \seem{telldir}{3} \end{function} For an example, see \seef{OpenDir}. \begin{function}{Umask} \Declaration Function Umask (Mask : Integer) : Integer; \Description Change the file creation mask for the current user to \var{Mask}. The current mask is returned. \Errors None \SeeAlso \seef{Chmod}, \seem{Umask}{2} \end{function} \FPCexample{ex27} \begin{procedure}{Uname} \Declaration Procedure Uname (var unamerec:utsname); \Description \var{Uname} gets the name and configuration of the current \linux kernel, and returns it in \var{unamerec}. \Errors \var{LinuxError} is used to report errors. \SeeAlso \seef{GetHostName}, \seef{GetDomainName}, \seem{uname}{2} \end{procedure} \begin{function}{UnLink} \Declaration Function UnLink (Var Path) : Boolean; \Description \var{UnLink} decreases the link count on file \var{Path}. \var{Path} can be of type \var{PathStr} or \var{PChar}. 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 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} \SeeAlso \seef{Link}, \seef{SymLink}, \seem{Unlink}{2} \end{function} For an example, see \seef{Link}. \begin{function}{Utime} \Declaration Function Utime (path : pathstr; utim : utimbuf) : Boolean; \Description \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 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. \SeeAlso \seef{GetEpochTime}, \seef{Chown}, \seef{Access}, \seem{utime}(2) \end{function} \FPCexample{ex25} \begin{function}{WaitPid} \Declaration Function WaitPid (Pid : longint; Status : pointer; Options : Longint) : Longint; \Description \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. \item[\_\_WCLONE] Causes \var{WaitPid} also to wait for threads created by the \seef{Clone} call. \end{description} Upon return, it returns the exit status of the process, or -1 in case of failure. \Errors Errors are returned in LinuxError. \SeeAlso \seef{Fork}, \seep{Execve}, \seem{waitpid}{2} \end{function} For an example, see \seef{Fork}. \begin{procedure}{WritePort} \Declaration Procedure WritePort (Port : Longint; Value : Byte); Procedure WritePort (Port : Longint; Value : Word); Procedure WritePort (Port : Longint; Value : Longint); \Description \var{WritePort} writes \var{Value} -- 1 byte, Word or longint -- to port \var{Port}. Note: You need permission to write to a port. This permission can be set with root permission with the \var{IOperm} call. \Errors In case of an error (not enough permissions to write to this port), runtime 216 ({\em Access Violation}) will occur. \SeeAlso \seef{IOperm}, \seep{WritePortB}, \seep{WritePortL}, \seep{WritePortW}, \seep{ReadPortB}, \seep{ReadPortL}, \seep{ReadPortW} \end{procedure} \begin{procedure}{WritePortB} \Declaration Procedure WritePortB (Port : Longint; Value : Byte); Procedure WritePortB (Port : Longint; Var Buf; Count: longint); \Description The first form of \var{WritePortB} writes 1 byte to port \var{Port}. The second form writes \var{Count} bytes from \var{Buf} to port \var{Port}. Note: You need permission to write to a port. This permission can be set with root permission with the \var{IOperm} call. \Errors In case of an error (not enough permissions to write to this port), runtime 216 ({\em Access Violation}) will occur. \SeeAlso \seef{IOperm}, \seep{WritePort}, \seep{WritePortL}, \seep{WritePortW}, \seep{ReadPortB}, \seep{ReadPortL}, \seep{ReadPortW} \end{procedure} \begin{procedure}{WritePortL} \Declaration Procedure WritePortL (Port : Longint; Value : Longint); Procedure WritePortL (Port : Longint; Var Buf; Count: longint); \Description The first form of \var{WritePortB} writes 1 byte to port \var{Port}. The second form writes \var{Count} bytes from \var{Buf} to port \var{Port}. Note: You need permission to write to a port. This permission can be set with root permission with the \var{IOperm} call. \Errors In case of an error (not enough permissions to write to this port), runtime 216 ({\em Access Violation}) will occur. \SeeAlso \seef{IOperm}, \seep{WritePort}, \seep{WritePortB}, \seep{WritePortW}, \seep{ReadPortB}, \seep{ReadPortL}, \seep{ReadPortW} \end{procedure} \begin{procedure}{WritePortW} \Declaration Procedure WritePortW (Port : Longint; Var Buf; Count: longint); Procedure WritePortW (Port : Longint; Value : Word); \Description The first form of \var{WritePortB} writes 1 byte to port \var{Port}. The second form writes \var{Count} bytes from \var{Buf} to port \var{Port}. Note: You need permission to write to a port. This permission can be set with root permission with the \var{IOperm} call. \Errors In case of an error (not enough permissions to write to this port), runtime 216 ({\em Access Violation}) will occur. \SeeAlso \seef{IOperm}, \seep{WritePort}, \seep{WritePortL}, \seep{WritePortB}, \seep{ReadPortB}, \seep{ReadPortL}, \seep{ReadPortW} \end{procedure}