diff --git a/docs/crt.tex b/docs/crt.tex index dff0c6ff54..8878301b11 100644 --- a/docs/crt.tex +++ b/docs/crt.tex @@ -20,8 +20,10 @@ % \chapter{The CRT unit.} \label{ch:crtunit} + +\FPCexampledir{crtex} This chapter describes the \var{CRT} unit for Free Pascal, both under \dos -and \linux. The unit was first written for \dos by Florian kl\"ampfl. +\linux and \windows. The unit was first written for \dos by Florian kl\"ampfl. The unit was ported to \linux by Mark May\footnote{Current e-mail address \textsf{mmay@dnaco.net}}, and enhanced by Micha\"el Van Canneyt and Peter Vreman. It works on the \linux console, and in xterm and rxvt windows @@ -102,28 +104,30 @@ screen. It is defined on \dos only. \begin{verbatim} var lastmode : Word; \end{verbatim} + +% Procedures and functions. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Procedures and Functions} + \begin{procedure}{AssignCrt} \Declaration Procedure AssignCrt (Var F: Text); - \Description - -Assigns a file F to the console. Everything written to the file F goes to -the console instead. If the console contains a window, everything is written -to the window instead. +\var{AssignCrt} Assigns a file F to the console. Everything written to +the file F goes to the console instead. If the console contains a window, +everything is written to the window instead. \Errors None. \SeeAlso \seep{Window} \end{procedure} -\latex{\lstinputlisting{crtex/ex1.pp}} - \html{\input{crtex/ex1.tex}} -\begin{procedure}{BigCursor} -\Declaration -Procedure BigCursor ; +\FPCexample{ex1} + +\begin{procedure}{CursorBig} +\Declaration +Procedure CursorBig ; \Description Makes the cursor a big rectangle. Not implemented on \linux. @@ -132,10 +136,10 @@ None. \SeeAlso \seep{CursorOn}, \seep{CursorOff} \end{procedure} + \begin{procedure}{ClrEol} \Declaration Procedure ClrEol ; - \Description ClrEol clears the current line, starting from the cursor position, to the end of the window. The cursor doesn't move @@ -144,12 +148,12 @@ None. \SeeAlso \seep{DelLine}, \seep{InsLine}, \seep{ClrScr} \end{procedure} -\latex{\lstinputlisting{crtex/ex9.pp}} - \html{\input{crtex/ex9.tex}} + +\FPCexample{ex9} + \begin{procedure}{ClrScr} \Declaration Procedure ClrScr ; - \Description ClrScr clears the current window (using the current colors), and sets the cursor in the top left @@ -159,12 +163,12 @@ None. \SeeAlso \seep{Window} \end{procedure} -\latex{\lstinputlisting{crtex/ex8.pp}} - \html{\input{crtex/ex8.tex}} + +\FPCexample{ex8} + \begin{procedure}{CursorOff} \Declaration Procedure CursorOff ; - \Description Switches the cursor off (i.e. the cursor is no longer visible). @@ -172,24 +176,22 @@ Not implemented on \linux. \Errors None. \SeeAlso -\seep{CursorOn}, \seep{BigCursor} +\seep{CursorOn}, \seep{CursorBig} \end{procedure} \begin{procedure}{CursorOn} \Declaration Procedure CursorOn ; - \Description Switches the cursor on. Not implemented on \linux. \Errors None. \SeeAlso -\seep{BigCursor}, \seep{CursorOff} +\seep{CursorBig}, \seep{CursorOff} \end{procedure} \begin{procedure}{Delay} \Declaration Procedure Delay (DTime: Word); - \Description Delay waits a specified number of milliseconds. The number of specified seconds is an approximation, and may be off a lot, if system load is high. @@ -198,12 +200,12 @@ None \SeeAlso \seep{Sound}, \seep{NoSound} \end{procedure} -\latex{\lstinputlisting{crtex/ex15.pp}} - \html{\input{crtex/ex15.tex}} + +\FPCexample{ex15} + \begin{procedure}{DelLine} \Declaration Procedure DelLine ; - \Description DelLine removes the current line. Lines following the current line are scrolled 1 line up, and an empty line is inserted at the bottom of the @@ -213,12 +215,12 @@ None. \SeeAlso \seep{ClrEol}, \seep{InsLine}, \seep{ClrScr} \end{procedure} -\latex{\lstinputlisting{crtex/ex11.pp}} - \html{\input{crtex/ex11.tex}} + +\FPCexample{ex11} + \begin{procedure}{GotoXY} \Declaration Procedure GotoXY (X: Byte; Y: Byte); - \Description Positions the cursor at \var{(X,Y)}, \var{X} in horizontal, \var{Y} in vertical direction relative to the origin of the current window. The origin @@ -229,12 +231,12 @@ None. \SeeAlso \seef{WhereX}, \seef{WhereY}, \seep{Window} \end{procedure} -\latex{\lstinputlisting{crtex/ex6.pp}} - \html{\input{crtex/ex6.tex}} + +\FPCexample{ex6} + \begin{procedure}{HighVideo} \Declaration Procedure HighVideo ; - \Description HighVideo switches the output to highlighted text. (It sets the high intensity bit of the video attribute) @@ -245,12 +247,12 @@ None. \seep{TextColor}, \seep{TextBackground}, \seep{LowVideo}, \seep{NormVideo} \end{procedure} -\latex{\lstinputlisting{crtex/ex14.pp}} - \html{\input{crtex/ex14.tex}} + +\FPCexample{ex14} + \begin{procedure}{InsLine} \Declaration Procedure InsLine ; - \Description InsLine inserts an empty line at the current cursor position. Lines following the current line are scrolled 1 line down, @@ -261,12 +263,12 @@ None. \SeeAlso \seep{ClrEol}, \seep{DelLine}, \seep{ClrScr} \end{procedure} -\latex{\lstinputlisting{crtex/ex10.pp}} - \html{\input{crtex/ex10.tex}} + +\FPCexample{ex10} + \begin{function}{KeyPressed} \Declaration Function KeyPressed : Boolean; - \Description The Keypressed function scans the keyboard buffer and sees if a key has been pressed. If this is the case, \var{True} is returned. If not, @@ -279,12 +281,12 @@ None. \SeeAlso \seef{ReadKey} \end{function} -\latex{\lstinputlisting{crtex/ex2.pp}} - \html{\input{crtex/ex2.tex}} + +\FPCexample{ex2} + \begin{procedure}{LowVideo} \Declaration Procedure LowVideo ; - \Description LowVideo switches the output to non-highlighted text. (It clears the high intensity bit of the video attribute) @@ -299,7 +301,6 @@ For an example, see \seep{HighVideo} \begin{procedure}{NormVideo} \Declaration Procedure NormVideo ; - \Description NormVideo switches the output to the defaults, read at startup. (The defaults are read from the cursor position at startup) @@ -314,7 +315,6 @@ For an example, see \seep{HighVideo} \begin{procedure}{NoSound} \Declaration Procedure NoSound ; - \Description Stops the speaker sound. @@ -324,12 +324,12 @@ None. \SeeAlso \seep{Sound} \end{procedure} -\latex{\lstinputlisting{crtex/ex16.pp}} - \html{\input{crtex/ex16.tex}} + +\FPCexample{ex16} + \begin{function}{ReadKey} \Declaration Function ReadKey : Char; - \Description The ReadKey function reads 1 key from the keyboard buffer, and returns this. @@ -344,12 +344,14 @@ None. \SeeAlso \seef{KeyPressed} \end{function} -\latex{\lstinputlisting{crtex/ex3.pp}} - \html{\input{crtex/ex3.tex}} + + +\FPCexample{ex3} + + \begin{procedure}{Sound} \Declaration Procedure Sound (hz : word); - \Description Sounds the speaker at a frequency of \var{hz}. This is not supported in \linux @@ -358,10 +360,10 @@ None. \SeeAlso \seep{NoSound} \end{procedure} + \begin{procedure}{TextBackground} \Declaration Procedure TextBackground (CL: Byte); - \Description TextBackground sets the background color to \var{CL}. \var{CL} can be one of the @@ -373,12 +375,12 @@ None. \seep{TextColor}, \seep{HighVideo}, \seep{LowVideo}, \seep{NormVideo} \end{procedure} -\latex{\lstinputlisting{crtex/ex13.pp}} - \html{\input{crtex/ex13.tex}} + +\FPCexample{ex13} + \begin{procedure}{TextColor} \Declaration Procedure TextColor (CL: Byte); - \Description TextColor sets the foreground color to \var{CL}. \var{CL} can be one of the @@ -390,12 +392,26 @@ None. \seep{TextBackground}, \seep{HighVideo}, \seep{LowVideo}, \seep{NormVideo} \end{procedure} -\latex{\lstinputlisting{crtex/ex12.pp}} - \html{\input{crtex/ex12.tex}} + +\FPCexample{ex12} + +\begin{procedure}{TextMode} +\Declaration +procedure TextMode(Mode: Integer); +\Description +\var{TextMode} sets the textmode of the screen (i.e. the number of lines +and columns of the screen). The lower byte is use to set the VGA text mode. + +This procedure is only implemented on \dos. +\Errors +None. +\SeeAlso +\seep{Window} +\end{procedure} + \begin{function}{WhereX} \Declaration Function WhereX : Byte; - \Description WhereX returns the current X-coordinate of the cursor, relative to the @@ -407,12 +423,12 @@ None. \SeeAlso \seep{GotoXY}, \seef{WhereY}, \seep{Window} \end{function} -\latex{\lstinputlisting{crtex/ex7.pp}} - \html{\input{crtex/ex7.tex}} + +\FPCexample{ex7} + \begin{function}{WhereY} \Declaration Function WhereY : Byte; - \Description WhereY returns the current Y-coordinate of the cursor, relative to the @@ -424,12 +440,12 @@ None. \SeeAlso \seep{GotoXY}, \seef{WhereX}, \seep{Window} \end{function} -\latex{\lstinputlisting{crtex/ex7.pp}} - \html{\input{crtex/ex7.tex}} + +\FPCexample{ex7} + \begin{procedure}{Window} \Declaration Procedure Window (X1, Y1, X2, Y2: Byte); - \Description Window creates a window on the screen, to which output will be sent. \var{(X1,Y1)} are the coordinates of the upper left corner of the window, @@ -444,5 +460,7 @@ None. \SeeAlso \seep{GotoXY}, \seef{WhereX}, \seef{WhereY}, \seep{ClrScr} \end{procedure} -\latex{\lstinputlisting{crtex/ex5.pp}} -\html{\input{crtex/ex5.tex}} + + +\FPCexample{ex5} + diff --git a/docs/dos.tex b/docs/dos.tex index 4c54a2ad2e..ec25994c6c 100644 --- a/docs/dos.tex +++ b/docs/dos.tex @@ -19,20 +19,25 @@ % Boston, MA 02111-1307, USA. % \chapter{The DOS unit.} -This chapter describes the \var{DOS} unit for Free pascal, both under \dos -and \linux. The unit was first written for \dos by Florian kl\"ampfl. -The unit was ported to \linux by Mark May\footnote{Current -e-mail address \textsf{mmay@dnaco.net}}, and enhanced by Micha\"el Van -Canneyt. -Under \linux, some of the functionality is lost, as it is either impossible -or meaningless to implement it. Other than that, -the functionality for both operating systems is the same. -This chapter is divided in two sections. +\FPCexampledir{dosex} + +This chapter describes the \var{DOS} unit for Free pascal, both under +\dos, \ostwo, \windows and \linux. +The unit was first written for \dos by Florian kl\"ampfl. It was ported to +\linux by Mark May\footnote{Current e-mail address \textsf{mmay@dnaco.net}}, +and enhanced by Micha\"el Van Canneyt. + +Under non-\dos systems, some of the functionality is lost, as it is either impossible +or meaningless to implement it. Other than that, the functionality for all +operating systems is the same. + +This chapter is divided in two sections: \begin{itemize} \item The first section lists the pre-defined constants, types and variables. \item The second section describes the functions which appear in the interface part of the DOS unit. \end{itemize} + \section{Types, Variables, Constants} \subsection {Constants} The DOS unit implements the following constants: @@ -61,16 +66,14 @@ The DOS unit implements the following constants: The following string types are defined for easy handling of filenames : \begin{verbatim} - ComStr = String[127]; { For command-lines } - PathStr = String[79]; { For full path for file names } - DirStr = String[67]; { For Directory and (DOS) drive string } - NameStr = String[8]; { For Name of file } - ExtStr = String[4]; { For Extension of file } + ComStr = String[255]; { For command-lines } + PathStr = String[255]; { For full path for file names } + DirStr = String[255]; { For Directory and (DOS) drive string } + NameStr = String[255]; { For Name of file } + ExtStr = String[255]; { For Extension of file } \end{verbatim} -Under \linux, these strings all have length 255. \begin{verbatim} -{$PACKRECORDS 1} - SearchRec = Record + SearchRec = Packed Record Fill : array[1..21] of byte; { Fill replaced with declarations below, for Linux} Attr : Byte; {attribute of found file} @@ -184,7 +187,6 @@ Other values are possible, but are not documented. \begin{procedure}{AddDisk} \Declaration Procedure AddDisk (Const S : String); - \Description \var{AddDisk} adds a filename \var{S} to the internal list of disks. It is implemented for \linux only. @@ -203,16 +205,16 @@ initialization code presets the first three disks to: The first call to \var{AddDisk} will therefore add a name for the second harddisk, The second call for the third drive, and so on until 23 drives have been added (corresponding to drives \var{'D:'} to \var{'Z:'}) - \Errors None \SeeAlso \seef{DiskFree}, \seef{DiskSize} \end{procedure} + + \begin{function}{DiskFree} \Declaration Function DiskFree (Drive: byte) : Int64; - \Description \var{DiskFree} returns the number of free bytes on a disk. The parameter @@ -241,12 +243,12 @@ These settings can be coded in \var{dos.pp}, in the initialization part. \SeeAlso \seef{DiskSize}, \seep{AddDisk} \end{function} -\latex{\lstinputlisting{dosex/ex6.pp}} -\html{\input{dosex/ex6.tex}} + +\FPCexample{ex6} + \begin{function}{DiskSize} \Declaration Function DiskSize (Drive: byte) : Int64; - \Description \var{DiskSize} returns the total size (in bytes) of a disk. The parameter @@ -277,7 +279,6 @@ For an example, see \seef{DiskFree}. \begin{function}{DosExitCode} \Declaration Function DosExitCode : Word; - \Description \var{DosExitCode} contains (in the low byte) the exit-code of a program @@ -287,12 +288,12 @@ None. \SeeAlso \seep{Exec} \end{function} -\latex{\lstinputlisting{dosex/ex5.pp}} -\html{\input{dosex/ex5.tex}} + +\FPCexample{ex5} + \begin{function}{DosVersion} \Declaration Function DosVersion : Word; - \Description \var{DosVersion} returns the \dos version number. On \linux systems, it returns the Linux version (The first 2 numbers, e.g Linux version 2.1.76 will @@ -303,13 +304,13 @@ None. \end{function} -\latex{\lstinputlisting{dosex/ex1.pp}} -\html{\input{dosex/ex1.tex}} + +\FPCexample{ex1} + \begin{function}{EnvCount} \Declaration -Function EnvCount : longint; -\Description +Function EnvCount : longint;\Description \var{EnvCount} returns the number of environment variables. \Errors None. @@ -319,8 +320,7 @@ None. \begin{function}{EnvStr} \Declaration -Function EnvStr (Index: integer) : string; -\Description +Function EnvStr (Index: integer) : string;\Description \var{EnvStr} returns the \var{Index}-th \var{Name=Value} pair from the list of environment variables. @@ -331,12 +331,12 @@ The length is limited to 255 characters. This may cause problems under \SeeAlso \seef{EnvCount}, \seef{Dos:GetEnv} \end{function} -\latex{\lstinputlisting{dosex/ex13.pp}} -\html{\input{dosex/ex13.tex}} + +\FPCexample{ex13} + \begin{procedure}{Exec} \Declaration Procedure Exec (const Path: pathstr; const ComLine: comstr); - \Description \var{Exec} executes the program in \var{Path}, with the options given by @@ -353,7 +353,6 @@ For an example, see \seef{DosExitCode} \begin{functionl}{FExpand}{Dos:FExpand} \Declaration Function FExpand (const path: pathstr) : pathstr; - \Description \var{FExpand} takes its argument and expands it to a complete filename, i.e. @@ -367,11 +366,10 @@ the name is left as it is. (filenames are case sensitive under Unix) \SeeAlso \lstinputlisting{dosex/ex5.pp} \end{functionl} -\html{\input{dosex/ex5.tex}} + \begin{procedure}{FindClose} \Declaration Procedure FindClose (Var F: SearchRec); - \Description \textbf{\linux only} @@ -398,7 +396,6 @@ None. \begin{procedure}{FindFirst} \Declaration Procedure FindFirst (const Path: pathstr; Attr: word; var F: SearchRec); - \Description \var{FindFirst} searches the file specified in \var{Path}, checks the @@ -416,12 +413,12 @@ Errors are reported in DosError. \seep{FindNext}, \seep{FindClose} \end{procedure} -\latex{\lstinputlisting{dosex/ex7.pp}} -\html{\input{dosex/ex7.tex}} + +\FPCexample{ex7} + \begin{procedure}{FindNext} \Declaration Procedure FindNext (var f: searchRec); - \Description \var{FindNext} takes as an argument a \var{SearchRec} from a previous @@ -438,7 +435,6 @@ For an example, see \seep{FindFirst}. \begin{functionl}{FSearch}{Dos:FSearch} \Declaration Function FSearch (Path: pathstr; DirList: string) : pathstr; - \Description \var{FSearch} searches the file \var{Path} in all directories listed in \var{DirList}. The full name of the found file is returned. @@ -451,14 +447,14 @@ None. \SeeAlso \seefl{FExpand}{Dos:FExpand} \end{functionl} -\latex{\lstinputlisting{dosex/ex10.pp}} -\html{\input{dosex/ex10.tex}} + +\FPCexample{ex10} + \begin{procedure}{FSplit} \Declaration Procedure FSplit (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 @@ -471,12 +467,12 @@ None. \SeeAlso \seefl{FSearch}{Dos:FSearch} \end{procedure} -\latex{\lstinputlisting{dosex/ex12.pp}} -\html{\input{dosex/ex12.tex}} + +\FPCexample{ex12} + \begin{procedure}{GetCBreak} \Declaration Procedure GetCBreak (var breakvalue: boolean); - \Description \var{GetCBreak} gets the status of CTRL-Break checking under \dos. @@ -492,8 +488,7 @@ not implemented, i.e. the call does nothing. \begin{procedurel}{GetDate}{Dos:GetDate} \Declaration -Procedure GetDate (var year, month, mday, wday: word); -\Description +Procedure GetDate (var year, month, mday, wday: word);\Description \var{GetDate} returns the system's date. \var{Year} is a number in the range 1980..2099.\var{mday} is the day of the month, @@ -503,12 +498,12 @@ None. \SeeAlso \seepl{GetTime}{Dos:GetTime},\seep{SetDate} \end{procedurel} -\latex{\lstinputlisting{dosex/ex2.pp}} -\html{\input{dosex/ex2.tex}} + +\FPCexample{ex2} + \begin{functionl}{GetEnv}{Dos:GetEnv} \Declaration Function GetEnv (EnvVar: String) : String; - \Description \var{Getenv} returns the value of the environment variable \var{EnvVar}. @@ -520,12 +515,12 @@ None. \SeeAlso \seef{EnvCount}, \seef{EnvStr} \end{functionl} -\latex{\lstinputlisting{dosex/ex14.pp}} -\html{\input{dosex/ex14.tex}} + +\FPCexample{ex14} + \begin{procedure}{GetFAttr} \Declaration Procedure GetFAttr (var F; var Attr: word); - \Description \var{GetFAttr} returns the file attributes of the file-variable \var{f}. @@ -552,12 +547,12 @@ Errors are reported in \var{DosError} \SeeAlso \seep{SetFAttr} \end{procedure} -\latex{\lstinputlisting{dosex/ex8.pp}} -\html{\input{dosex/ex8.tex}} + +\FPCexample{ex8} + \begin{procedure}{GetFTime} \Declaration Procedure GetFTime (var F; var Time: longint); - \Description \var{GetFTime} returns the modification time of a file. @@ -569,27 +564,25 @@ Errors are reported in \var{DosError} \SeeAlso \seep{SetFTime}, \seep{PackTime},\seep{UnPackTime} \end{procedure} -\latex{\lstinputlisting{dosex/ex9.pp}} -\html{\input{dosex/ex9.tex}} + +\FPCexample{ex9} + \begin{procedure}{GetIntVec} \Declaration Procedure GetIntVec (IntNo: byte; var Vector: pointer); - \Description \var{GetIntVec} returns the address of interrupt vector \var{IntNo}. \Errors -None. Under \linux, this call exists bout isn't implemented, -i.e. it does nothing. +Under non- \dos operating systems, this call does nothing. \SeeAlso \seep{SetIntVec} \end{procedure} \begin{function}{GetLongName} \Declaration -function GetLongName(var p : String) : boolean; -\Description +function GetLongName(var p : String) : boolean;\Description This function is only implemented in the GO32V2 version of \fpc. \var{GetLongName} changes the filename \var{p} to a long filename @@ -601,16 +594,15 @@ The function returns \var{True} if the \dos call was successful, This function should only be necessary when using the DOS extender under Windows 95 and higher. -\errors +\Errors If the \dos call was not succesfull, \var{False} is returned. -\seealso +\SeeAlso \seef{GetShortName} \end{function} \begin{function}{GetShortName} \Declaration -function GetShortName(var p : String) : boolean; -\Description +function GetShortName(var p : String) : boolean;\Description This function is only implemented in the GO32V2 version of \fpc. \var{GetShortName} changes the filename \var{p} to a short filename @@ -622,16 +614,15 @@ The function returns \var{True} if the \dos call was successful, This function should only be necessary when using the DOS extender under Windows 95 and higher. -\errors +\Errors If the \dos call was not successful, \var{False} is returned. -\seealso +\SeeAlso \seef{GetLongName} \end{function} \begin{procedurel}{GetTime}{Dos:GetTime} \Declaration Procedure GetTime (var hour, minute, second, sec100: word); - \Description \var{GetTime} returns the system's time. \var{Hour} is a on a 24-hour time @@ -644,13 +635,13 @@ None. \seep{SetTime} \end{procedurel} -\latex{\lstinputlisting{dosex/ex3.pp}} -\html{\input{dosex/ex3.tex}} + +\FPCexample{ex3} + \begin{procedure}{GetVerify} \Declaration Procedure GetVerify (var verify: boolean); - \Description \var{GetVerify} returns the status of the verify flag under \dos. When @@ -666,7 +657,6 @@ Under \linux, Verify is always \begin{procedure}{Intr} \Declaration Procedure Intr (IntNo: byte; var Regs: registers); - \Description \var{Intr} executes a software interrupt number \var{IntNo} (must be between @@ -678,24 +668,22 @@ kernel. The only allowed interrupt is 80h, the Linux kernel entry interrupt. \SeeAlso \seep{MSDos}, see the \linux unit. \end{procedure} + \begin{procedure}{Keep} \Declaration Procedure Keep (ExitCode: word); - \Description - \var{Keep} terminates the program, but stays in memory. This is used for TSR (Terminate Stay Resident) programs which catch some interrupt. \var{ExitCode} is the same parameter as the \var{Halt} function takes. \Errors -Under \linux, this call does nothing. +Under non-\dos operating systems, this call does nothing. \SeeAlso \seem{Halt}{} \end{procedure} \begin{procedure}{MSDos} \Declaration Procedure MSDos (var regs: registers); - \Description \var{MSDos} executes an MS-\dos call (int 21h). This is the same as doing a @@ -708,7 +696,6 @@ None. \begin{procedure}{PackTime} \Declaration Procedure PackTime (var T: datetime; var P: longint); - \Description \var{UnPackTime} converts the date and time specified in \var{T} @@ -718,12 +705,12 @@ None. \SeeAlso \seep{SetFTime}, \seep{FindFirst}, \seep{FindNext}, \seep{UnPackTime} \end{procedure} -\latex{\lstinputlisting{dosex/ex4.pp}} -\html{\input{dosex/ex4.tex}} + +\FPCexample{ex4} + \begin{procedure}{SetCBreak} \Declaration Procedure SetCBreak (breakvalue: boolean); - \Description \var{SetCBreak} sets the status of CTRL-Break checking under \dos. @@ -739,7 +726,6 @@ but is not implemented, i.e. it does nothing. \begin{procedure}{SetDate} \Declaration Procedure SetDate (year,month,day: word); - \Description \var{SetDate} sets the system's internal date. \var{Year} is a number @@ -756,7 +742,6 @@ root-only privilege, and is hence not implemented. \begin{procedure}{SetFAttr} \Declaration Procedure SetFAttr (var F; Attr: word); - \Description \var{SetFAttr} sets the file attributes of the file-variable \var{F}. @@ -782,7 +767,6 @@ Under \linux the call exists, but is not implemented, i.e. it does nothing. \begin{procedure}{SetFTime} \Declaration Procedure SetFTime (var F; Time: longint); - \Description \var{SetFTime} sets the modification time of a file, @@ -794,26 +778,23 @@ Errors are reported in \var{DosError} \SeeAlso \seep{GetFTime}, \seep{PackTime},\seep{UnPackTime} \end{procedure} + \begin{procedure}{SetIntVec} \Declaration Procedure SetIntVec (IntNo: byte; Vector: pointer); - \Description - \var{SetIntVec} sets interrupt vector \var{IntNo} to \var{Vector}. \var{Vector} should point to an interrupt procedure. \Errors -Under \linux, this -call exists but is not implemented, the kernel manages all interrupts. +Under non- \dos operating systems, this call does nothing. \SeeAlso \seep{GetIntVec} \end{procedure} + \begin{procedure}{SetTime} \Declaration Procedure SetTime (hour,minute,second,sec100: word); - \Description - \var{SetTime} sets the system's internal clock. The \var{Hour} parameter is on a 24-hour time scale. \Errors @@ -825,7 +806,6 @@ as setting the time is a root-only privilege. \begin{procedure}{SetVerify} \Declaration Procedure SetVerify (verify: boolean); - \Description \var{SetVerify} sets the status of the verify flag under \dos. When @@ -841,7 +821,6 @@ Under \linux, Verify is always \begin{procedure}{SwapVectors} \Declaration Procedure SwapVectors ; - \Description \var{SwapVectors} swaps the contents of the internal table of interrupt @@ -857,7 +836,6 @@ managed by the kernel. \begin{procedure}{UnPackTime} \Declaration Procedure UnPackTime (p: longint; var T: datetime); - \Description \var{UnPackTime} converts the file-modification time in \var{p} diff --git a/docs/getopts.tex b/docs/getopts.tex index 0d225b8553..3b065f561d 100644 --- a/docs/getopts.tex +++ b/docs/getopts.tex @@ -20,7 +20,7 @@ % \chapter{The GETOPTS unit.} This document describes the GETOPTS unit for Free Pascal. It was written for -\linux\ by Micha\"el Van Canneyt. It also works under DOS and Tp7. +\linux\ by Micha\"el Van Canneyt. It now also works for all supported platforms. The getopts unit provides a mechanism to handle command-line options in a structured way, much like the GNU getopts mechanism. It allows you to diff --git a/docs/graph.tex b/docs/graph.tex index 5d73f77cbd..8194b64841 100644 --- a/docs/graph.tex +++ b/docs/graph.tex @@ -21,14 +21,16 @@ % Documentation for the 'Graph' unit of Free Pascal. % Michael Van Canneyt, July 1997 \chapter{The GRAPH unit.} -This document describes the \var{GRAPH} unit for Free Pascal, under \dos. -The unit was first written for \dos by Florian kl\"ampfl. -This chapter is divided in three sections. +This document describes the \var{GRAPH} unit for Free Pascal, for all +platforms. The unit was first written for \dos by Florian kl\"ampfl. +This chapter is divided in 4 sections. \begin{itemize} \item The first section gives an introduction to the graph unit. \item The second section lists the pre-defined constants, types and variables. \item The second section describes the functions which appear in the interface part of the \file{GRAPH} unit. +\item The last part describes some system-specific issues. + \end{itemize} \section{Introduction} \label{se:Introduction} @@ -1183,4 +1185,14 @@ None. \SeeAlso \seef{TextHeight} \end{function} - + +% Target specific issues. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Target specific issues} +In what follows we describe some things that are different on the various +platforms: + +\subsection{\dos} +\subsection{\windows} +\subsection{\linux} + diff --git a/docs/heaptrc.tex b/docs/heaptrc.tex index 02e43d44dc..c4d5f3573d 100644 --- a/docs/heaptrc.tex +++ b/docs/heaptrc.tex @@ -20,7 +20,7 @@ % \chapter{The HEAPTRC unit.} This chapter describes the HEAPTRC unit for \fpc. It was written by -Pierre Muller. +Pierre Muller. It is system independent, and works on all supported systems. \section{Purpose} @@ -102,6 +102,8 @@ const quicktrace : boolean = true; HaltOnError : boolean = true; keepreleased : boolean = false; + add_tail : boolean = true; + usecrc : boolean = true \end{lstlisting}{} \var{Tracesize} specifies how many levels of calls are displayed of the @@ -128,6 +130,13 @@ blocks is kept. This is useful if you suspect that the same memory block is released twice. However, this option is very memory intensive, so use it sparingly, and only when it's really necessary. +If \var{add\_tail} is \var{True} (the default) then a check is also +performed on the memory location just behind the allocated memory. + +If \var{usecrc} is \var{True} (the default) then a crc check is performed +on locations before and after the allocated memory. This is useful to +detect memory overwrites. + \section{Functions and procedures} \begin{procedure}{DumpHeap} @@ -173,16 +182,34 @@ yet. If memory was already allocated prior to the call to \var{SetExtraInfo}, then an error will be displayed on standard error output, and a \seep{DumpHeap} is executed. \SeeAlso -\seep{DumpHeap} +\seep{DumpHeap},\seep{SetHeapTraceOutput} + \end{procedure} \latex{\lstinputlisting{heapex/setinfo.pp}} \html{\input{heapex/setinfo.tex}} +\begin{procedure}{SetHeapTraceOutput} +\Declaration +Procedure SetHeapTraceOutput(const name : string); +\Description +\var{SetHeapTraceOutput} sets the filename into which heap trace info +will be written. By default information is written to standard output, +this function allows you to redirect the information to a file with +full filename \var{name}. +\Errors +If the file cannot be written to, errors will occur when writing the +trace. +\SeeAlso +\seep{SetExtraInfo} +\end{procedure} % % $Log$ -% Revision 1.4 2000-02-07 11:21:06 michael +% Revision 1.5 2000-05-16 21:07:55 michael +% + Implemented large part of TODO list. Too much to denote +% +% Revision 1.4 2000/02/07 11:21:06 michael % + Documented heaptrc and lineinfo % % Revision 1.3 1999/06/25 22:12:16 michael diff --git a/docs/ipc.tex b/docs/ipc.tex index 6a503dc174..8cd6e891ce 100644 --- a/docs/ipc.tex +++ b/docs/ipc.tex @@ -22,6 +22,7 @@ This chapter describes the IPC unit for Free Pascal. It was written for \linux by Micha\"el Van Canneyt. It gives all the functionality of system V Inter-Process Communication: shared memory, semaphores and messages. +It works only on the \linux operating system. The chapter is divided in 2 sections: \begin{itemize} diff --git a/docs/mmx.tex b/docs/mmx.tex index b64d651106..67c038d026 100644 --- a/docs/mmx.tex +++ b/docs/mmx.tex @@ -21,7 +21,8 @@ \chapter{The MMX unit} This chapter describes the \file{MMX} unit. This unit allows you to use the \var{MMX} capabilities of the \fpc compiler. It was written by Florian -Kl\"ampfl for the \var{I386} processor. +Kl\"ampfl for the \var{I386} processor. It should work on all platforms that +use the Intel processor. \section{Variables, Types and constants} The following types are defined in the \var{MMX} unit: \begin{verbatim} diff --git a/docs/mouse.tex b/docs/mouse.tex index 99c4d0a609..62183b6d42 100644 --- a/docs/mouse.tex +++ b/docs/mouse.tex @@ -1,5 +1,5 @@ \chapter{The MsMouse unit} -The msmouse unit provides basic mouse handling under Dos (Go32v1 and Go32v2) +The msmouse unit provides basic mouse handling under \dos (Go32v1 and Go32v2) Some general remarks about the msmouse unit: \begin{itemize} \item The mouse driver does not know when the text screen scrolls. This results diff --git a/docs/objects.tex b/docs/objects.tex index 7cdc6e81f9..cbe89806ba 100644 --- a/docs/objects.tex +++ b/docs/objects.tex @@ -20,7 +20,8 @@ % \chapter{The Objects unit.} This chapter documents the \file{objects} unit. The unit was implemented by -many people, and was mainly taken from the FreeVision sources. +many people, and was mainly taken from the FreeVision sources. It has been +ported to all supported platforms. The methods and fields that are in a \var{Private} part of an object declaration have been left out of this documentation. diff --git a/docs/printer.tex b/docs/printer.tex index d3993a58b8..eaa119f330 100644 --- a/docs/printer.tex +++ b/docs/printer.tex @@ -20,9 +20,11 @@ % \chapter{The PRINTER unit.} This chapter describes the PRINTER unit for Free Pascal. It was written for -\dos by Florian kl\"ampfl, and -it was written for \linux by Micha\"el Van Canneyt. Its basic functionality -is the same for both systems. +\dos by Florian kl\"ampfl, and it was written for \linux by Micha\"el Van +Canneyt, and has been ported to \windows as well. +Its basic functionality is the same for both systems, although there are +minor differences on \linux. + The chapter is divided in 2 sections: \begin{itemize} \item The first section lists types, constants and variables from the diff --git a/docs/prog.tex b/docs/prog.tex index 24f4ecd3f0..2d4cd07880 100644 --- a/docs/prog.tex +++ b/docs/prog.tex @@ -872,14 +872,16 @@ indices, enumeration types, subrange types, etc. Specifying the \var{\{\$R+\}} switch tells the computer to generate code to check these indices. If, at run-time, an index or enumeration type is specified that is out of the declared range of the compiler, then a run-time error is -generated, and the program exits with exit code 201. +generated, and the program exits with exit code 201. This can happen when +doing a typecast (implicit or explicit) on an enumeration type or subrange +type. The \var{\{\$RANGECHECKS OFF\}} switch tells the compiler not to generate range checking code. This may result in faulty program behaviour, but no run-time errors will be generated. \begin{remark} -\item The standard functions \var{val} and \var{Read} will also check ranges +The standard functions \var{val} and \var{Read} will also check ranges when the call is compiled in \var{\{\$R+\}} mode. \end{remark} @@ -2436,8 +2438,31 @@ ppc386 prlen.pp \end{verbatim} Supposing, of course, that the program source resides in \file{prlen.pp}. -You cannot use procedures or functions that have a variable number of -arguments in C. Pascal doesn't support this feature of C. +To use functions in C that have a variable number of arguments, you must +compile your unit or program in \var{objfpc} mode or \var{Delphi} mode, +and use the \var{Array of const} argument, as in the following example: + +\begin{verbatim} +program testaocc; + +{$mode objfpc} + +Const + P : Pchar + = 'example'; + F : Pchar + = 'This %s uses printf to print numbers (%d) and strings.'#10; + +procedure printf(fm: pchar;args: array of const);cdecl;external 'c'; + +begin + printf(F,[P,123]); +end. +\end{verbatim} +The output of this program looks like this: +\begin{verbatim} +This example uses printf to print numbers (123) and strings. +\end{verbatim} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Making a shared library @@ -3060,8 +3085,8 @@ Offset & What is stored & Optional ? \\ \hline +x & parameters & Yes \\ +12 & function result & Yes \\ +8 & self & Yes \\ -+4 & Frame pointer of parent procedure & Yes \\ -+0 & Return address & No\\ \hline ++4 & Return address & No\\ ++0 & Frame pointer of parent procedure & Yes \\ \hline \end{FPCltable} \subsection{ Intel x86 version } @@ -3080,12 +3105,17 @@ size will be used instead, otherwise the default stack size is used. \subsubsection{ Linux } -Under Linux, stack size is only limited by the available memory of +Under \linux, stack size is only limited by the available memory of +the system. + +\subsubsection{ Windows } + +Under \windows, stack size is only limited by the available memory of the system. \subsubsection{ OS/2 } -Under OS/2, stack size is determined by one of the runtime +Under \ostwo, stack size is determined by one of the runtime environment variables set for EMX. Therefore, the stack size is user defined. diff --git a/docs/ref.tex b/docs/ref.tex index f1c1e46990..9628df69e0 100644 --- a/docs/ref.tex +++ b/docs/ref.tex @@ -333,6 +333,7 @@ public published read register +saveregisters stdcall virtual write @@ -2977,6 +2978,16 @@ end; ['EAX','EBX']; \end{verbatim} This will tell the compiler that it should save and restore the contents of the \var{EAX} and \var{EBX} registers when it encounters this asm statement. + +\fpc supports various styles of assembler syntax. By default, \var{AT\&T} +syntax is assumed. You can change the default assembler style with the +\var{\{\$asmmode xxx\}} switch in your code, or the \var{-R} command-line +option. More about this can be found in the \progref. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Using functions and procedures. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Using functions and procedures} \label{ch:Procedures} \fpc supports the use of functions and procedures, but with some extras: @@ -3238,6 +3249,9 @@ begin printf(Fmt,[P,123]); end. \end{verbatim} +Remark that this is not true for Delphi, so code relying on this feature +will not be portable. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Function overloading \section{Function overloading} @@ -3388,6 +3402,7 @@ various possibilities: does support a number of additional modifiers. They are used mainly for assembler and reference to C object files. More on the use of modifiers can be found in the \progref. + \subsection{Public} The \var{Public} keyword is used to declare a function globally in a unit. This is useful if you don't want a function to be accessible from the unit @@ -3412,6 +3427,7 @@ If another program or unit uses this unit, it will not be able to use the function \var{Second}, since it isn't declared in the interface part. However, it will be possible to access the function \var{Second} at the assembly-language level, by using it's mangled name (see the \progref). + \subsection{cdecl} \label{se:cdecl} The \var{cdecl} modifier can be used to declare a function that uses a C @@ -3440,6 +3456,7 @@ sensitive, this means also that the name of the function must be exactly the same. the \fpc compiler will use the name {\em exactly} as it is typed in the declaration. \end{remark} + \subsection{popstack} \label{se:popstack} Popstack does the same as \var{cdecl}, namely it tells the \fpc compiler @@ -3448,6 +3465,7 @@ that a function uses the C calling convention. In difference with the for a normal pascal function. With \var{popstack} you could access functions by their pascal names in a library. + \subsection{Export} Sometimes you must provide a callback function for a C library, or you want your routines to be callable from a C program. Since \fpc and C use @@ -3470,6 +3488,7 @@ This modifier works in the same way as the \var{export} modifier. More information about these modifiers can be found in the \progref, in the section on the calling mechanism and the chapter on linking. \end{remark} + \subsection{StdCall} As of version 0.9.8, \fpc supports the Delphi \var{stdcall} modifier. This modifier does actually nothing, since the \fpc compiler by default @@ -3478,6 +3497,15 @@ modifier does under Delphi (which pushes parameters on the stack from left to right). More information about this modifier can be found in the \progref, in the section on the calling mechanism and the chapter on linking. + +\subsection{saveregisters} +As of version 0.99.15, \fpc has the \var{saveregisters} modifier. If this +modifier is specified after a procedure or function, then the \fpc compiler +will save all registers on procedure entry, and restore them when the +procedure exits (except for registers where return values are stored). + +You should not need this modifier, except maybe when calling assembler code. + \subsection{Alias} The \var{Alias} modifier allows you to specify a different name for a procedure or function. This is mostly useful for referring to this procedure @@ -4353,19 +4381,45 @@ second section contains the supported functions and procedures. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Types, Constants and Variables \section{Types, Constants and Variables} + \subsection{Types} The following integer types are defined in the System unit: \begin{verbatim} -shortint = -128..127; +Shortint = -128..127; +SmallInt = -32768..32767; Longint = $80000000..$7fffffff; -integer = -32768..32767; byte = 0..255; word = 0..65535; +dword = cardinal; +longword = cardinal; +Integer = smallint; +\end{verbatim} +The following types are used for the functions that need compiler magic +such as \seep{Val} or \seep{Str}: +\begin{verbatim} +StrLenInt = LongInt; +ValSInt = Longint; +ValUInt = Cardinal; +ValReal = Extended; +\end{verbatim} +The following character types are defined for Delphi compatibility: +\begin{verbatim} +TAnsiChar = Char; +AnsiChar = TAnsiChar; \end{verbatim} And the following pointer types: \begin{verbatim} PChar = ^char; pPChar = ^PChar; + PAnsiChar = PChar; + PQWord = ^QWord; + PInt64 = ^Int64; + pshortstring = ^shortstring; + plongstring = ^longstring; + pansistring = ^ansistring; + pwidestring = ^widestring; + pextended = ^extended; + ppointer = ^pointer; \end{verbatim} For the \seef{SetJmp} and \seep{LongJmp} calls, the following jump bufer type is defined (for the I386 processor): @@ -4376,7 +4430,115 @@ type is defined (for the I386 processor): end; PJmp_buf = ^jmp_buf; \end{verbatim} +The following records and pointers can be used if you want to scan the +entries in the string message handler tables: +\begin{verbatim} + tmsgstrtable = record + name : pshortstring; + method : pointer; + end; + pmsgstrtable = ^tmsgstrtable; + + tstringmessagetable = record + count : dword; + msgstrtable : array[0..0] of tmsgstrtable; + end; + pstringmessagetable = ^tstringmessagetable; +\end{verbatim} + +The base class for all classes is defined as: +\begin{verbatim} +Type + TObject = Class + Public + constructor create; + destructor destroy;virtual; + class function newinstance : tobject;virtual; + procedure freeinstance;virtual; + function safecallexception(exceptobject : tobject; + exceptaddr : pointer) : longint;virtual; + procedure defaulthandler(var message);virtual; + procedure free; + class function initinstance(instance : pointer) : tobject; + procedure cleanupinstance; + function classtype : tclass; + class function classinfo : pointer; + class function classname : shortstring; + class function classnameis(const name : string) : boolean; + class function classparent : tclass; + class function instancesize : longint; + class function inheritsfrom(aclass : tclass) : boolean; + class function inheritsfrom(aclass : tclass) : boolean; + class function stringmessagetable : pstringmessagetable; + procedure dispatch(var message); + procedure dispatchstr(var message); + class function methodaddress(const name : shortstring) : pointer; + class function methodname(address : pointer) : shortstring; + function fieldaddress(const name : shortstring) : pointer; + procedure AfterConstruction;virtual; + procedure BeforeDestruction;virtual; + procedure DefaultHandlerStr(var message);virtual; + end; + TClass = Class Of TObject; + PClass = ^TClass; +\end{verbatim} +Unhandled exceptions can be treated using a constant of the +\var{TExceptProc} type: +\begin{verbatim} +TExceptProc = Procedure (Obj : TObject; Addr,Frame: Pointer); +\end{verbatim} +\var{Obj} is the exception object that was used to raise the exception, +\var{Addr} and \var{Frame} contain the exact address and stack frame +where the exception was raised. + +The \var{TVarRec} type is used to access the elements passed in a \var{Array +of Const} argument to a function or procedure: +\begin{verbatim} +Type + PVarRec = ^TVarRec; + TVarRec = record + case VType : Longint of + vtInteger : (VInteger: Longint); + vtBoolean : (VBoolean: Boolean); + vtChar : (VChar: Char); + vtExtended : (VExtended: PExtended); + vtString : (VString: PShortString); + vtPointer : (VPointer: Pointer); + vtPChar : (VPChar: PChar); + vtObject : (VObject: TObject); + vtClass : (VClass: TClass); + vtAnsiString : (VAnsiString: Pointer); + vtWideString : (VWideString: Pointer); + vtInt64 : (VInt64: PInt64); + end; +\end{verbatim} +The heap manager uses the \var{TMemoryManager} type: +\begin{verbatim} + PMemoryManager = ^TMemoryManager; + TMemoryManager = record + Getmem : Function(Size:Longint):Pointer; + Freemem : Function(var p:pointer):Longint; + FreememSize : Function(var p:pointer;Size:Longint):Longint; + AllocMem : Function(Size:longint):Pointer; + ReAllocMem : Function(var p:pointer;Size:longint):Pointer; + MemSize : function(p:pointer):Longint; + MemAvail : Function:Longint; + MaxAvail : Function:Longint; + HeapSize : Function:Longint; + end; +\end{verbatim} +More information on using this record can be found in \progref. + \subsection{Constants} +The following constants define the maximum values that can be used with +various types: +\begin{verbatim} + MaxSIntValue = High(ValSInt); + MaxUIntValue = High(ValUInt); + maxint = maxsmallint; + maxLongint = $7fffffff; + maxSmallint = 32767; +\end{verbatim} The following constants for file-handling are defined in the system unit: \begin{verbatim} Const @@ -4402,6 +4564,84 @@ represents the processor number (such as Test8086, Test68000), and are used to determine on what generation of processor the program is running on. \end{remark} +The following constants are defined to access VMT entries: +\begin{verbatim} + vmtInstanceSize = 0; + vmtParent = 8; + vmtClassName = 12; + vmtDynamicTable = 16; + vmtMethodTable = 20; + vmtFieldTable = 24; + vmtTypeInfo = 28; + vmtInitTable = 32; + vmtAutoTable = 36; + vmtIntfTable = 40; + vmtMsgStrPtr = 44; + vmtMethodStart = 48; + vmtDestroy = vmtMethodStart; + vmtNewInstance = vmtMethodStart+4; + vmtFreeInstance = vmtMethodStart+8; + vmtSafeCallException = vmtMethodStart+12; + vmtDefaultHandler = vmtMethodStart+16; + vmtAfterConstruction = vmtMethodStart+20; + vmtBeforeDestruction = vmtMethodStart+24; + vmtDefaultHandlerStr = vmtMethodStart+28; +\end{verbatim} +You should always use the constant names, and never their values, because +the VMT table can change, breaking your code. + +The following constants will be used for the planned \var{variant} support: +\begin{verbatim} + varEmpty = $0000; + varNull = $0001; + varSmallint = $0002; + varInteger = $0003; + varSingle = $0004; + varDouble = $0005; + varCurrency = $0006; + varDate = $0007; + varOleStr = $0008; + varDispatch = $0009; + varError = $000A; + varBoolean = $000B; + varVariant = $000C; + varUnknown = $000D; + varByte = $0011; + varString = $0100; + varAny = $0101; + varTypeMask = $0FFF; + varArray = $2000; + varByRef = $4000; +\end{verbatim} +The following constants are used in the \var{TVarRec} record: +\begin{verbatim} +vtInteger = 0; +vtBoolean = 1; +vtChar = 2; +vtExtended = 3; +vtString = 4; +vtPointer = 5; +vtPChar = 6; +vtObject = 7; +vtClass = 8; +vtWideChar = 9; +vtPWideChar = 10; +vtAnsiString = 11; +vtCurrency = 12; +vtVariant = 13; +vtInterface = 14; +vtWideString = 15; +vtInt64 = 16; +vtQWord = 17; +\end{verbatim} +The \var{ExceptProc} is called when an unhandled exception occurs: +\begin{verbatim} +Const + ExceptProc : TExceptProc = Nil; +\end{verbatim} +It is set in the \file{objpas} unit, but you can set it yourself to change +the default exception handling. + \subsection{Variables} The following variables are defined and initialized in the system unit: \begin{verbatim} @@ -4426,6 +4666,8 @@ you did). In your exit procedure you then restore the value of \var{ExitProc}, such that if it was non-\var{Nil} the exit-procedure can be called. +\FPCexample{ex98} + The \var{ErrorAddr} and \var{ExitCode} can be used to check for error-conditions. If \var{ErrorAddr} is non-\var{Nil}, a run-time error has occurred. If so, \var{ExitCode} contains the error code. If \var{ErrorAddr} is @@ -4433,7 +4675,11 @@ occurred. If so, \var{ExitCode} contains the error code. If \var{ErrorAddr} is program terminated normally. \var{ExitCode} is always passed to the operating system as the exit-code of -your process. +your process. + +\begin{remark} +The maximum error code under \linux is 127. +\end{remark} Under \file{GO32}, the following constants are also defined : \begin{verbatim} @@ -4445,6 +4691,12 @@ const \end{verbatim} These constants allow easy access to the bios/screen segment via mem/absolute. +The randomize function uses a seed stored in the \var{RandSeed} variable: +\begin{verbatim} + RandSeed : Cardinal; +\end{verbatim} +This variable is initialized in the initialization code of the system unit. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Functions and Procedures \section{Functions and Procedures} @@ -4740,6 +4992,9 @@ Function Cos (X : Real) : Real; \Description \var{Cos} returns the cosine of \var{X}, where X is an angle, in radians. + +If the absolute value of the argument is larger than \var{2^63}, then the +result is undefined. \Errors None. \SeeAlso @@ -5058,6 +5313,21 @@ None. \seep{Freemem}, \seep{Dispose}, \seep{New} \end{procedure} For an example, see \seep{Freemem}. + +\begin{procedure}{GetMemoryManager} +\Declaration +procedure GetMemoryManager(var MemMgr: TMemoryManager); +\Description +\var{GetMemoryManager} stores the current Memory Manager record in +\var{MemMgr}. +\Errors +None. +\SeeAlso +\seep{SetMemoryManager}, \seef{IsMemoryManagerSet}. +\end{procedure} + +For an example, see \progref. + \begin{procedure}{Halt} \Declaration Procedure Halt [(Errnum : byte)]; @@ -5110,7 +5380,7 @@ None \begin{function}{High} \Declaration -Function High (Type identifier or variable reference) : Longint; +Function High (Type identifier or variable reference) : Ordinal; \Description The return value of \var{High} depends on it's argument: @@ -5123,7 +5393,8 @@ Function High (Type identifier or variable reference) : Longint; procedure, then \var{High} returns the highest index of the array, as if the array has a zero-based index. \end{enumerate} - +The return type is always the same type as the type of the argument +(This can lead to some nasty surprises !). \Errors None. \SeeAlso @@ -5164,6 +5435,18 @@ None. \end{procedure} \FPCexample{ex33} +\begin{function}{IsMemoryManagerSet} +\Declaration +function IsMemoryManagerSet: Boolean; +\Description +\var{IsMemoryManagerSet} will return \var{True} if the memory manager has +been set to another value than the system heap manager, it will return +\var{False} otherwise. +\Errors +None. +\SeeAlso +\seep{SetMemoryManager}, \seep{GetMemoryManager} +\end{function} \begin{function}{Int} \Declaration @@ -5311,6 +5594,7 @@ None. \seef{SetJmp} \end{procedure} For an example, see \seef{SetJmp} + \begin{function}{Low} \Declaration Function Low (Type identifier or variable reference) : Longint; @@ -5323,7 +5607,7 @@ value in the range of the given ordinal type. \item If the argument is an array type or an array type variable then \var{Low} returns the lowest possible value of it's index. \end{enumerate} - +The return type is always the same type as the type of the argument \Errors None. \SeeAlso @@ -5875,6 +6159,20 @@ None. \FPCexample{ex60} +\begin{procedure}{SetMemoryManager} +\Declaration +procedure SetMemoryManager(const MemMgr: TMemoryManager); +\Description +\var{SetMemoryManager} sets the current memory manager record to +\var{MemMgr}. +\Errors +None. +\SeeAlso +\seep{GetMemoryManager}, \seef{IsMemoryManagerSet} +\end{procedure} + +For an example, see \progref. + \begin{function}{SetJmp} \Declaration Function SetJmp (Var Env : Jmp\_Buf) : Longint; @@ -5955,7 +6253,10 @@ Function Sin (X : Real) : Real; \Description \var{Sin} returns the sine of its argument \var{X}, where \var{X} is an -angle in radians. +angle in radians. + +If the absolute value of the argument is larger than \var{2^63}, then the +result is undefined. \Errors None. \SeeAlso diff --git a/docs/sockets.tex b/docs/sockets.tex index a94e7f04f1..bb318b58ee 100644 --- a/docs/sockets.tex +++ b/docs/sockets.tex @@ -20,7 +20,8 @@ % \chapter{The SOCKETS unit.} This chapter describes the SOCKETS unit for Free Pascal. -it was written for \linux by Micha\"el Van Canneyt. +it was written for \linux by Micha\"el Van Canneyt, and ported to \windows +by Florian Klaempfl. The chapter is divided in 2 sections: \begin{itemize} \item The first section lists types, constants and variables from the diff --git a/docs/strings.tex b/docs/strings.tex index a0a2555917..b3241f3310 100644 --- a/docs/strings.tex +++ b/docs/strings.tex @@ -19,8 +19,9 @@ % Boston, MA 02111-1307, USA. % \chapter{The STRINGS unit.} -This chapter describes the \var{STRINGS} unit for -\fpc. +This chapter describes the \var{STRINGS} unit for \fpc. This unit is system +independent, and therefore works on all supported platforms. + Since the unit only provides some procedures and functions, there is only one section, which gives the declarations of these functions, together with an explanation. diff --git a/docs/sysutils.tex b/docs/sysutils.tex index 7ac980720a..e066d8c25b 100644 --- a/docs/sysutils.tex +++ b/docs/sysutils.tex @@ -23,7 +23,8 @@ This chapter describes the \file{sysutils} unit. The \var{sysutils} unit was largely written by Gertjan Schouten, and completed by michael Van Canneyt. It aims to be compatible to the Delphi sysutils unit, but in contrast with -the latter, it is designed to work on multiple platforms. +the latter, it is designed to work on multiple platforms. It is implemented +on all supported platforms. This chapter starts out with a definition of all types and constants that are defined, followed by a complete explanation of each function. diff --git a/docs/user.tex b/docs/user.tex index 5eac82aa01..39a66d97e3 100644 --- a/docs/user.tex +++ b/docs/user.tex @@ -86,7 +86,7 @@ on a port to ALPHA Architecture}. Currently, it supports 6 operating systems: \item \linux \item \atari (version 0.99.5 only) \item \amiga (version 0.99.5 only) -\item \windowsnt +\item \windows \item \ostwo (using the EMX package, so it also works on DOS/Windows) \end{itemize} and work is in progress to port it to other platforms (notably, \freebsd). @@ -99,8 +99,8 @@ And, unlike these ancestors, it supports multiple platforms. It also differs from them in the sense that you cannot use compiled units from one system for the other. -Also, at the time of writing, there is no Integrated Development Environment -(IDE) available for \fpc. This gap will, hopefully, be filled in the future. +Also, at the time of writing, there is only a early beta version of an +Integrated Development Environment (IDE) available for \fpc. \fpc consists of three parts : \begin{enumerate} @@ -161,14 +161,11 @@ The compiler needs at least the following hardware: \begin{enumerate} \item An I386 or higher processor. A coprocessor is not required, although it will slow down your program's performance if you do floating point calculations. -\item 2 Mb of free memory. Under \dos, if you use DPMI memory management, +\item 4 Mb of free memory. Under \dos, if you use DPMI memory management, such as under Windows, you will need at least 16 Mb. \item At least 500 Kb. free disk space. \end{enumerate} -% -% - % Software requirements \subsection{Software requirements} @@ -186,6 +183,18 @@ recompiling of the compiler and Run-Time Library, this is needed. \end{enumerate} Other than that, \fpc should run on almost any I386 \linux system. +\subsubsection{Under Windows} +The \dos distribution contains all the files you need to run the compiler +and compile pascal programs. However, it may be a good idea to install +the \file{mingw32} tools or the \var{cygwin} development tools. Links +to both of these tools can be found on \var{http://www.freepascal.org} + +\subsubsection{Under OS/2} +While the \fpc distribution comes with all necessary tools, it is a good +idea to install the EMX extender in order to compile and run +programs with the Free Pascal compiler. The EMX extender can be found on:\\ +\var{http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html} + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Installing the compiler. \section{Installing the compiler.} @@ -193,7 +202,7 @@ The installation of \fpc is easy, but is platform-dependent. We discuss the process for each platform separately. % Installing under DOS -\subsection{Installing under DOS} +\subsection{Installing under DOS or Windows} \subsubsection{Mandatory installation steps.} First, you must get the latest distribution files of \fpc. They come as zip files, which you must unzip first, or you can download the compiler as a @@ -249,7 +258,7 @@ it is necessary to install a coprocessor emulation, since \fpc uses the coprocessor to do all floating point operations. The installation of the coprocessor emulation is handled by the -installation program (\file{INSTALL.EXE}). However, +installation program (\file{INSTALL.EXE}) under \dos and \windows. % % Installing under Linux @@ -332,7 +341,7 @@ If you want the \fpc compiler to use this configuration file, it must be present in \file{/etc}, or you can set the environment variable \var{PPC\_CONFIG\_PATH}. Under \file{csh}, you can do this by adding a \begin{verbatim} -setenv PPC_CONFIG_PATH /usr/lib/ppc/0.99.1 +setenv PPC_CONFIG_PATH /usr/lib/ppc/0.99.14 \end{verbatim} line to your \file{.login} file in your home directory. (see also the next section) @@ -374,8 +383,8 @@ these programs. The compiler is called \begin{itemize} -\item \file{PPC386.EXE} under \dos, and \item \file{ppc386} under \linux +\item \file{PPC386.EXE} under other target systems. \end{itemize} To compile a program (e.g \verb|demo\hello.pp|) simply type : \begin{verbatim} @@ -385,14 +394,14 @@ at the command prompt. If you don't have a configuration file, then you may need to tell the compiler where it can find the units, for instance as follows: \begin{verbatim} -ppc386 -Upc:\pp\rtl\dos\go32v2 hello +ppc386 -Fuc:\pp\units\go32v2\rtl hello \end{verbatim} under \dos, and under \linux you could type \begin{verbatim} -ppc386 -Up/usr/lib/fpc/0.99.7/linuxunits hello +ppc386 -Fu/usr/lib/fpc/0.99.14/units/linux/rtl hello \end{verbatim} This is, of course, assuming that you installed under \verb|C:\PP| or -\file{/usr/lib/fpc/0.99.7}, respectively. +\file{/usr/lib/fpc/0.99.14}, respectively. If you got no error messages, the compiler has generated an executable called \file{hello} (no extension) under \linux, and a file \file{hello.exe} @@ -406,9 +415,6 @@ If all went well, you should see the following friendly greeting: \begin{verbatim} Hello world \end{verbatim} -In the \dos case, this friendly greeting may be preceded by some ugly -message from the \file{GO32} extender program. This unfriendly behavior can -be switched off by setting the \file{GO32} environment variable. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Usage @@ -473,7 +479,38 @@ look for compiled versions of these units in the following way: \end{enumerate} You can add a directory to the unit search path with the \var{-Fu} option (\seeo{Fu}). Every occurrence of one of this options will {\em insert} -a directory to the unit search path. +a directory to the unit search path. i.e. last path on the command line +will be searched first. + +The compiler adds several paths to the unit search path: +\begin{enumerate} +\item The contents of the environment variable \var{XXUNITS}, where \var{XX} +musrt be replaced with one of the supported targets: \var{GO32V2}, +\var{LINUX},\var{WIN32}, \var{OS2}. +\item The standard unit directory. This directory is determined +from the \var{FPCDIR} environment variable. If this variable is not set, +then it is defaulted to the following: +\begin{itemize} +\item On \linux: +\begin{verbatim} + /usr/local/lib/fpc/VERSION +or + /usr/lib/fpc/VERSION +\end{verbatim} +whichever is found first. +\item On other OSes: the compiler binary directory, with '../' appended +to it, if it exists. +\end{itemize} +After this directory is determined , the following paths are added to the +search path: +\begin{enumerate} +\item FPCDIR/units/TARGET +\item FPCDIR/units/TARGET/rtl +\end{enumerate} +Here target must be replaced by the name of the target you are compiling for. +\end{enumerate} +You can see what paths the compiler will search by giving the compiler +the \var{-vu} option. On \linux, the compiler will first convert the filename of a unit to all-lowercase. This is necessary, since Pascal is case-independent, and @@ -487,7 +524,7 @@ same directories, but with the truncated name. For instance, suppose that the file \file{foo.pp} needs the unit \file{bar}. Then the command \begin{verbatim} -ppc386 -Up.. -Upunits foo.pp +ppc386 -Fu.. -Fuunits foo.pp \end{verbatim} will tell the compiler to look for the unit \file{bar} in the following places: @@ -496,6 +533,7 @@ places: \item In the directory where the compile binary is (not under \linux). \item In the parent directory of the current directory. \item In the subdirectory \file{units} of the current directory +\item In the standard unit directory. \end{enumerate} If the compiler finds the unit it needs, it will look for the source file of @@ -513,7 +551,7 @@ It is recommended to set the unit search path in the configuration file path on the command-line every time you want to compile something. % Include files. -\section{Include files} +\subsection{Include files} If you include files in your source with the \var{\{\$I filename\}} directive, the compiler will look for it in the following places: @@ -547,7 +585,7 @@ will cause the compiler to look in the following directories for \end{enumerate} % Object files. -\section{Object files} +\subsection{Object files} When you link to object files (using the \var{\{\$L file.o\}} directive, the compiler will look for this file in the same way as it looks for include files: @@ -562,6 +600,7 @@ option. % Configuration file \subsection{Configuration file} +\label{searchconfig} Unless you specify the \var{-n} (\seeo{n}) option, the compiler will look for a configuration file \file{ppc386.cfg} in the following places: @@ -582,6 +621,15 @@ for a configuration file \file{ppc386.cfg} in the following places: \end{enumerate} \end{itemize} +\subsection{About long filenames} +\fpc can handle long filenames under \windows; it will use support for +long filenames if it is available. + +If no support for long filenames is present, it will truncate unit names +to 8 characters. + +It is not recommended to put units in directories that contain spaces in +their names, since the linker doesn't understand such filenames. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Compiling a program @@ -664,13 +712,7 @@ file, which will be linked as a whole into your program. Not only is it possible to compile a shared library under \windows and \linux, but also it is possible to take existing units and put them -together in 1 static or shared library. - - -begin{} - - - +together in 1 static or shared library (using the \file{ppumove} tool) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Creating an executable for GO32V1, PMODE/DJ targets @@ -1165,23 +1207,9 @@ before the options that you type on the command line. You can specify comments in the configuration file with the \var{\#} sign. Everything from the \var{\#} on will be ignored. -The compiler looks for the \file{ppc386.cfg} file in the following places : -\begin{itemize} -\item Under \linux -\begin{enumerate} -\item The current directory. -\item In your home directory, it looks for \file{.ppc386.cfg}. -\item The directory specified in the environment variable -\var{PPC\_CONFIG\_PATH}, and if it's not set under \file{/etc}. -\end{enumerate} -\item Under all other OSes: -\begin{enumerate} -\item The current directory. -\item If it is set, the directory specified in the environment variable. -\var{PPC\_CONFIG\_PATH}. -\item The directory where the compiler is. -\end{enumerate} -\end{itemize} +The algorithm to determine which file is used as a configuration file +is decribed in \ref{searchconfig} on page \pageref{searchconfig}. + When the compiler has finished reading the configuration file, it continues to treat the command line options. @@ -1221,7 +1249,7 @@ encountered, after which normal processing is resumed. Example : \begin{verbatim} #IFDEF VER0_99_5 --Up/usr/lib/fpc/0.99.5/linuxunits +-Fu/usr/lib/fpc/0.99.5/linuxunits #ENDIF \end{verbatim} In the above example, \file{/usr/lib/fpc/0.99.5/linuxunits} will be added to @@ -1241,7 +1269,7 @@ encountered, after which normal processing is resumed. Example : \begin{verbatim} #IFNDEF VER0_99_5 --Up/usr/lib/fpc/0.99.6/linuxunits +-Fu/usr/lib/fpc/0.99.6/linuxunits #ENDIF \end{verbatim} In the above example, \file{/usr/lib/fpc/0.99.6/linuxunits} will be added to @@ -1263,9 +1291,9 @@ encountered, after which normal processing is resumed. Example : \begin{verbatim} #IFDEF VER0_99_5 --Up/usr/lib/fpc/0.99.6/linuxunits +-Fu/usr/lib/fpc/0.99.6/linuxunits #ELSE --Up/usr/lib/fpc/0.99.5/linuxunits +-Fu/usr/lib/fpc/0.99.5/linuxunits #ENDIF \end{verbatim} In the above example, \file{/usr/lib/fpc/0.99.5/linuxunits} will be added to @@ -1432,14 +1460,17 @@ they are in Delphi. Using the \var{-So} switch will solve this problem if you want to compile Turbo Pascal code that uses these words. \item The reserved words \var{FAR, NEAR} are ignored. This is because \fpc is a 32 bit compiler, so they're obsolete. -\item \var{INTERRUPT} only will work on a DOS machine. +\item \var{INTERRUPT} will work only on the \dos target. \item Boolean expressions are only evaluated until their result is completely determined. The rest of the expression will be ignored. \item By default the compiler uses \var{AT\&T} assembler syntax. -This is mainly because \fpc uses \gnu \var{as}. However other assembler -forms are available, \progref. +This is mainly because \fpc uses \gnu \var{as}. However, other assembler +forms are available. For more information, see \progref. \item Turbo Vision is not completely available. There is FreeVision, but the -degree of compatibility with Turbo Vision is unclear at this time. +degree of compatibility with Turbo Vision is unclear at this +time\footnote{At the time of writing, FreeVision has been taken off the +net, because there are some copyright issues which make it impossible to +distribute it.}. \item The 'overlay' unit is not available. It also isn't necessary, since \fpc is a 32 bit compiler, so program size shouldn't be a point. \item There are more reserved words. (see appendix \ref{ch:reserved} for a @@ -1581,7 +1612,7 @@ begin end; \end{verbatim} -\item recursive function calls are handled dfferently. Consider the +\item recursive function calls are handled differently. Consider the following example : \begin{verbatim} Function expr : Longint; @@ -1638,7 +1669,7 @@ this by calling \dos function \var{71A0h} and checking whether long filenames are supported on the \file{C:} drive. It is possible to disable the long filename support by setting the -\var{LFNSupport} variable to \var{False} +\var{LFNSupport} variable to \var{False}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Utilities. @@ -1649,6 +1680,17 @@ It is possible to disable the long filename support by setting the Besides the compiler and the Run-Time Library, \fpc comes with some utility programs and units. Here we list these programs and units. +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Demo programs and examples. +\section{Demo programs and examples} +Also distributed with \fpc comes a series of demonstration programs. +These programs have no other purpose than demonstrating the capabilities of +\fpc. They are located in the \file{demo} directory of the sources. + +All example programs of the documentation are available. Check out the +directories that end on \file{ex} in the documentation sources. There you +will find all example sources. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Supplied programs \section{Supplied programs} @@ -1678,16 +1720,6 @@ letters: \item [a:\ ] show everything (default if no -V option is present). \end{description} -\subsection{Demo programs} -Also distributed with \fpc comes a series of demonstration programs. -These programs have no other purpose than demonstrating the capabilities of -\fpc. They are located in the \file{demo} directory of the sources. - -\subsection{Documentation Example programs} - -All example programs of the documentation are available. Check out the -directories that end on \file{ex} in the documentation sources. There you -will find all example sources. \subsection{ppumove program} @@ -2039,6 +2071,7 @@ code. \item [objects] This unit provides basic routines for handling objects. \item [objpas] is used for Delphi compatibility; you should never load this unit explicitly; it is automatically loaded if you request Delphi mode. +\item [ports] provides access to the PC hardware ports. \item [strings] This unit provides basic string handling routines for the \var{pchar} type, comparable to similar routines in standard \var{C} libraries. @@ -2064,8 +2097,6 @@ draw lines on the screen, display texts etc. It provides the same functions as the Turbo Pascal unit. \item [go32] This unit provides access to possibilities of the \var{GO32} \dos extender. -\item [ports] This unit provides access to the ports[] construct of -Turbo Pascal. \item [printer] This unit provides all you need for rudimentary access to the printer. \end{itemize} @@ -2073,6 +2104,7 @@ to the printer. % % Under Windows % +\subsection{Under Windows} \begin{itemize} \item [dos] This unit provides basic routines for accessing the operating system \dos. It emulates this functionality @@ -2130,13 +2162,27 @@ extensively. Programs using this construct must be run as ruit or setuid root, and are a serious security risk on your system. \end{itemize} +\subsection{under OS/2} +\begin{itemize} +\item [doscalls] interface to \file{doscalls.dll}. +\item [dive] interface to \file{dive.dll} +\item [emx] Provides access to the EMX extender. +\item [pm*] various programs to access o program manager functions. +\item [viocalls] interface to \file{viocalls.dll} screen handling library. +\item [moucalls] interface to \file{moucalls.dll} mouse handling library. +\item [kbdcalls] interface to \file{kbdcalls.dll} keyboard handling library. +\item [moncalls] interface to \file{moncalls.dll} monitoring handling library. +\end{itemize} + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Debugging %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Debugging your Programs} -\fpc supports debug information for the \gnu debugger \var{gdb}. +\fpc supports debug information for the \gnu debugger \var{gdb}, or +it's derivatives \file{Insight} on win32 or \file{ddd} on \linux. + This chapter describes shortly how to use this feature. It doesn't attempt to describe completely the \gnu debugger, however. For more information on the workings of the \gnu debugger, see the \var{gdb} @@ -2162,7 +2208,7 @@ program. You will notice that the size of the executable increases substantially because of this\footnote{A good reason not to include debug information in an executable you plan to distribute.}. -Note that the above will only generate debug information {\var for the code +Note that the above will only generate debug information {\em for the code that has been generated} when compiling \file{hello.pp}. This means that if you used some units (the system unit, for instance) which were not compiled with debugging support, no debugging support will be available for the code