% % $Id$ % This file is part of the FPC documentation. % Copyright (C) 1999, 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 SYSUTILS unit.} 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. This chapter starts out with a definition of all types and constants that are defined, followed by a complete explanation of each function. \section{Constants and types} The following general-purpose constants are defined: \begin{verbatim} const SecsPerDay = 24 * 60 * 60; // Seconds and milliseconds per day MSecsPerDay = SecsPerDay * 1000; DateDelta = 693594; // Days between 1/1/0001 and 12/31/1899 Eoln = #10; \end{verbatim} The following types are used frequently in date and time functions. They are the same on all platforms. \begin{verbatim} type TSystemTime = record Year, Month, Day: word; Hour, Minute, Second, MilliSecond: word; end ; TDateTime = double; TTimeStamp = record Time: integer; { Number of milliseconds since midnight } Date: integer; { One plus number of days since 1/1/0001 } end ; \end{verbatim} The following type is used in the \seef{FindFirst},\seef{FindNext} and \seep{FindClose} functions. The \var{win32} version differs from the other versions. If code is to be portable, that part shouldn't be used. \begin{verbatim} Type THandle = Longint; TSearchRec = Record Time,Size, Attr : Longint; Name : TFileName; ExcludeAttr : Longint; FindHandle : THandle; {$ifdef Win32} FindData : TWin32FindData; {$endif} end; \end{verbatim} The following constants are file-attributes that need to be matched in the findfirst call. \begin{verbatim} Const faReadOnly = $00000001; faHidden = $00000002; faSysFile = $00000004; faVolumeId = $00000008; faDirectory = $00000010; faArchive = $00000020; faAnyFile = $0000003f; \end{verbatim} The following constants can be used in the \seef{FileOpen} call. \begin{verbatim} Const fmOpenRead = $0000; fmOpenWrite = $0001; fmOpenReadWrite = $0002; \end{verbatim} The following variables are used in the case translation routines. \begin{verbatim} type TCaseTranslationTable = array[0..255] of char; var UpperCaseTable: TCaseTranslationTable; LowerCaseTable: TCaseTranslationTable; \end{verbatim} The initialization code of the \file{sysutils} unit fills these tables with the appropriate values. For the win32 and go32v2 versions, this information is obtained from the operating system. The following constants control the formatting of dates. For the Win32 version of the \file{sysutils} unit, these constants are set according to the internationalization settings of Windows by the initialization code of the unit. \begin{verbatim} Const DateSeparator: char = '-'; ShortDateFormat: string = 'd/m/y'; LongDateFormat: string = 'dd" "mmmm" "yyyy'; ShortMonthNames: array[1..12] of string[128] = ('Jan','Feb','Mar','Apr','May','Jun', 'Jul','Aug','Sep','Oct','Nov','Dec'); LongMonthNames: array[1..12] of string[128] = ('January','February','March','April', 'May','June','July','August', 'September','October','November','December'); ShortDayNames: array[1..7] of string[128] = ('Sun','Mon','Tue','Wed','Thu','Fri','Sat'); LongDayNames: array[1..7] of string[128] = ('Sunday','Monday','Tuesday','Wednesday', 'Thursday','Friday','Saturday'); \end{verbatim} The following constants control the formatting of times. For the Win32 version of the \file{sysutils} unit, these constants are set according to the internationalization settings of Windows by the initialization code of the unit. \begin{verbatim} Const ShortTimeFormat: string = 'hh:nn'; LongTimeFormat: string = 'hh:nn:ss'; TimeSeparator: char = ':'; TimeAMString: string[7] = 'AM'; TimePMString: string[7] = 'PM'; \end{verbatim} The following constants control the formatting of currencies and numbers. For the Win32 version of the \file{sysutils} unit, these constants are set according to the internationalization settings of Windows by the initialization code of the unit. \begin{verbatim} Const DecimalSeparator : Char = '.'; ThousandSeparator : Char = ','; CurrencyDecimals : Byte = 2; CurrencyString : String[7] = '$'; { Format to use when formatting currency : 0 = $1 1 = 1$ 2 = $ 1 3 = 1 $ 4 = Currency string replaces decimal indicator. e.g. 1$50 } CurrencyFormat : Byte = 1; { Same as above, only for negative currencies: 0 = ($1) 1 = -$1 2 = $-1 3 = $1- 4 = (1$) 5 = -1$ 6 = 1-$ 7 = 1$- 8 = -1 $ 9 = -$ 1 10 = $ 1- } NegCurrFormat : Byte = 5; \end{verbatim} The following types are used in various string functions. \begin{verbatim} type PString = ^String; TFloatFormat = (ffGeneral, ffExponent, ffFixed, ffNumber, ffCurrency); \end{verbatim} The following constants are used in the file name handling routines. Do not use a slash of backslash character directly as a path separator; instead use the \var{OsDirSeparator} character. \begin{verbatim} Const DirSeparators : set of char = ['/','\']; {$ifdef Linux} OSDirSeparator = '/'; {$else} OsDirSeparator = '\'; {$endif} \end{verbatim} \section{Date and time functions} \subsection{Date and time formatting characters} \label{se:formatchars} Various date and time formatting routines accept a format string. to format the date and or time. The following characters can be used to control the date and time formatting: \begin{description} \item[c] : shortdateformat + ' ' + shorttimeformat \item[d] : day of month \item[dd] : day of month (leading zero) \item[ddd] : day of week (abbreviation) \item[dddd] : day of week (full) \item[ddddd] : shortdateformat \item[dddddd] : longdateformat \item[m] : month \item[mm] : month (leading zero) \item[mmm] : month (abbreviation) \item[mmmm] : month (full) \item[y] : year (four digits) \item[yy] : year (two digits) \item[yyyy] : year (with century) \item[h] : hour \item[hh] : hour (leading zero) \item[n] : minute \item[nn] : minute (leading zero) \item[s] : second \item[ss] : second (leading zero) \item[t] : shorttimeformat \item[tt] : longtimeformat \item[am/pm] : use 12 hour clock and display am and pm accordingly \item[a/p] : use 12 hour clock and display a and p accordingly \item[/] : insert date seperator \item[:] : insert time seperator \item["xx"] : literal text \item['xx'] : literal text \end{description} \begin{type}{TDateTime} \Declaration TDateTime = Double; \Description Many functions return or require a \var{TDateTime} type, which contains a date and time in encoded form. The date and time are converted to a double as follows: \end{type} \begin{function}{Date} \Declaration Function Date: TDateTime; \Description \var{Date} returns the current date in \var{TDateTime} format. For more information about the \var{TDateTime} type, see \seety{TDateTime}. \Errors None. \SeeAlso \seef{Time},\seef{Now}, \seety{TDateTime}. \end{function} \latex{\inputlisting{sysutex/ex1.pp}} \html{\input{sysutex/ex1.tex}} \begin{function}{DateTimeToFileDate} \Declaration Function DateTimeToFileDate(DateTime : TDateTime) : Longint; \Description \var{DateTimeToFileDate} function converts a date/time indication in \var{TDateTime} format to a filedate function, such as returned for instance by the \seef{FileAge} function. \Errors None. \SeeAlso \seef{Time}, \seef{Date}, \seef{FileDateToDateTime}, \seep{DateTimeToSystemTime}, \seef{DateTimeToTimeStamp} \end{function} \latex{\inputlisting{sysutex/ex2.pp}} \html{\input{sysutex/ex2.tex}} \begin{function}{DateTimeToStr} \Declaration Function DateTimeToStr(DateTime: TDateTime): string; \Description \var{DateTimeToStr} returns a string representation of \var{DateTime} using the formatting specified in \var{ShortDateTimeFormat}. It corresponds to a call to \var{FormatDateTime('c',DateTime)} (see \sees{formatchars}). \Errors None. \SeeAlso \seef{FormatDateTime}, \seety{TDateTime}. \end{function} \latex{\inputlisting{sysutex/ex3.pp}} \html{\input{sysutex/ex3.tex}} \begin{procedure}{DateTimeToString} \Declaration Procedure DateTimeToString(var Result: string; const FormatStr: string; const DateTime: TDateTime); \Description \var{DateTimeToString} returns in \var{Result} a string representation of \var{DateTime} using the formatting specified in \var{FormatStr}. for a list of characters that can be used in the \var{FormatStr} formatting string, see \sees{formatchars}. \Errors In case a wrong formatting character is found, an \var{EConvertError} is raised. \SeeAlso \seef{FormatDateTime}, \sees{formatchars}. \end{procedure} \latex{\inputlisting{sysutex/ex4.pp}} \html{\input{sysutex/ex4.tex}} \begin{procedure}{DateTimeToSystemTime} \Declaration Procedure DateTimeToSystemTime(DateTime: TDateTime; var SystemTime: TSystemTime); \Description \var{DateTimeToSystemTime} converts a date/time pair in \var{DateTime}, with \var{TDateTime} format to a system time \var{SystemTime}. \Errors None. \SeeAlso \seef{DateTimeToFileDate}, \seef{SystemTimeToDateTime}, \seef{DateTimeToTimeStamp} \end{procedure} \latex{\inputlisting{sysutex/ex5.pp}} \html{\input{sysutex/ex5.tex}} \begin{function}{DateTimeToTimeStamp} \Declaration Function DateTimeToTimeStamp(DateTime: TDateTime): TTimeStamp; \Description \var{DateTimeToSystemTime} converts a date/time pair in \var{DateTime}, with \var{TDateTime} format to a \var{TTimeStamp} format. \Errors None. \SeeAlso \seef{DateTimeToFileDate}, \seef{SystemTimeToDateTime}, \seep{DateTimeToSystemTime} \end{function} \latex{\inputlisting{sysutex/ex6.pp}} \html{\input{sysutex/ex6.tex}} \begin{function}{DateToStr} \Declaration Function DateToStr(Date: TDateTime): string; \Description \var{DateToStr} converts \var{Date} to a string representation. It uses \var{ShortDateFormat} as it's formatting string. It is hence completely equivalent to a \var{FormatDateTime('ddddd', Date)}. \Errors None. \SeeAlso \seef{TimeToStr}, \seef{DateTimeToStr}, \seef{FormatDateTime}, \seef{StrToDate} \end{function} \latex{\inputlisting{sysutex/ex7.pp}} \html{\input{sysutex/ex7.tex}} \begin{function}{DayOfWeek} \Declaration Function DayOfWeek(DateTime: TDateTime): integer; \Description \var{DayOfWeek} returns the day of the week from \var{DateTime}. \var{Sunday} is counted as day 1, \var{Saturday} is counted as day 7. The result of \var{DayOfWeek} can serve as an index to the \var{LongDayNames} constant array, to retrieve the name of the day. \Errors None. \SeeAlso \seef{Date}, \seef{DateToStr} \end{function} \latex{\inputlisting{sysutex/ex8.pp}} \html{\input{sysutex/ex8.tex}} \begin{procedure}{DecodeDate} \Declaration Procedure DecodeDate(Date: TDateTime; var Year, Month, Day: word); \Description \var{DecodeDate} decodes the Year, Month and Day stored in \var{Date}, and returns them in the \var{Year}, \var{Month} and \var{Day} variables. \Errors None. \SeeAlso \seef{EncodeDate}, \seep{DecodeTime}. \end{procedure} \latex{\inputlisting{sysutex/ex9.pp}} \html{\input{sysutex/ex9.tex}} \begin{procedure}{DecodeTime} \Declaration Procedure DecodeTime(Time: TDateTime; var Hour, Minute, Second, MilliSecond: word); \Description \var{DecodeDate} decodes the hours, minutes, second and milliseconds stored in \var{Time}, and returns them in the \var{Hour}, \var{Minute} and \var{Second} and \var{MilliSecond} variables. \Errors None. \SeeAlso \seef{EncodeTime}, \seep{DecodeDate}. \end{procedure} \latex{\inputlisting{sysutex/ex10.pp}} \html{\input{sysutex/ex10.tex}} \begin{function}{EncodeDate} \Declaration Function EncodeDate(Year, Month, Day :word): TDateTime; \Description \var{EncodeDate} encodes the \var{Year}, \var{Month} and \var{Day} variables to a date in \var{TDateTime} format. It does the opposite of the \seep{DecodeDate} procedure. The parameters must lie withing valid ranges (boundaries included): \begin{description} \item[Year] must be between 1 and 9999. \item[Month] must be within the range 1-12. \item[Day] msut be between 1 and 31. \end{description} \Errors In case one of the parameters is out of it's valid range, 0 is returned. \SeeAlso \seef{EncodeTime}, \seep{DecodeDate}. \end{function} \latex{\inputlisting{sysutex/ex11.pp}} \html{\input{sysutex/ex11.tex}} \begin{function}{EncodeTime} \Declaration Function EncodeTime(Hour, Minute, Second, MilliSecond:word): TDateTime; \Description \var{EncodeTime} encodes the \var{Hour}, \var{Minute}, \var{Second}, \var{MilliSecond} variables to a \var{TDateTime} format result. It does the opposite of the \seep{DecodeTime} procedure. The parameters must have a valid range (boundaries included): \begin{description} \item[Hour] must be between 0 and 23. \item[Minute,second] must both be between 0 and 59. \item[Millisecond] must be between 0 and 999. \end{description} \Errors In case one of the parameters is outside of it's valid range, 0 is returned. \SeeAlso \seef{EncodeDate}, \seep{DecodeTime}. \end{function} \latex{\inputlisting{sysutex/ex12.pp}} \html{\input{sysutex/ex12.tex}} \begin{function}{FileDateToDateTime} \Declaration Function FileDateToDateTime(Filedate : Longint) : TDateTime; \Description \var{FileDateToDateTime} converts the date/time encoded in \var{filedate} to a \var{TDateTime} encoded form. It can be used to convert date/time values returned by the \seef{FileAge} or \seef{FindFirst}/\seef{FindNext} functions to \var{TDateTime} form. \Errors None. \SeeAlso \seef{DateTimeToFileDate} \end{function} \latex{\inputlisting{sysutex/ex13.pp}} \html{\input{sysutex/ex13.tex}} \begin{function}{FormatDateTime} \Declaration Function FormatDateTime(FormatStr: string; DateTime: TDateTime):string; \Description \var{FormatDateTime} formats the date and time encoded in \var{DateTime} according to the formatting given in \var{FormatStr}. The complete list of formatting characters can be found in \sees{formatchars}. \Errors On error (such as an invalid character in the formatting string), and \var{EConvertError} exception is raised. \SeeAlso \seef{DateTimeToStr}, \seef{DateToStr}, \seef{TimeToStr}, \seef{StrToDateTime} \end{function} \latex{\inputlisting{sysutex/ex14.pp}} \html{\input{sysutex/ex14.tex}} \begin{function}{IncMonth} \Declaration Function IncMonth(const DateTime: TDateTime; NumberOfMonths: integer): TDateTime; \Description \var{IncMonth} increases the month number in \var{DateTime} with \var{NumberOfMonths}. It wraps the result as to get a month between 1 and 12, and updates the year accordingly. \var{NumberOfMonths} can be negative, and can be larger than 12 (in absolute value). \Errors None. \SeeAlso \seef{Date}, \seef{Time}, \seef{Now} \end{function} \latex{\inputlisting{sysutex/ex15.pp}} \html{\input{sysutex/ex15.tex}} \begin{function}{IsLeapYear} \Declaration Function IsLeapYear(Year: Word): boolean; \Description \var{IsLeapYear} returns \var{True} if \var{Year} is a leap year, \var{False} otherwise. \Errors None. \SeeAlso \seef{IncMonth}, \seef{Date} \end{function} \latex{\inputlisting{sysutex/ex16.pp}} \html{\input{sysutex/ex16.tex}} \begin{function}{MSecsToTimeStamp} \Declaration Function MSecsToTimeStamp(MSecs: Comp): TTimeStamp; \Description \var{MSecsTiTimeStamp} converts the given number of milliseconds to a \var{TTimeStamp} date/time notation. Use \var{TTimeStamp} variables if you need to keep very precise track of time. \Errors None. \SeeAlso \seef{TimeStampToMSecs}, \seef{DateTimeToTimeStamp}, \end{function} \latex{\inputlisting{sysutex/ex17.pp}} \html{\input{sysutex/ex17.tex}} \begin{function}{Now} \Declaration Function Now: TDateTime; \Description \var{Now} returns the current date and time. It is equivalent to \var{Date+Time}. \Errors None. \SeeAlso \seef{Date}, \seef{Time} \end{function} \latex{\inputlisting{sysutex/ex18.pp}} \html{\input{sysutex/ex18.tex}} \begin{function}{StrToDate} \Declaration Function StrToDate(const S: string): TDateTime; \Description \var{StrToDate} converts the string \var{S} to a \var{TDateTime} date value. The Date must consist of 1 to three digits, separated by the \var{DateSeparator} character. If two numbers are given, they are supposed to form the day and month of the current year. If only one number is given, it is supposed to represent the day of the current month. (This is \em{not} supported in Delphi) The order of the digits (y/m/d, m/d/y, d/m/y) is determined from the \var{ShortDateFormat} variable. \Errors On error (e.g. an invalid date or invalid character), an \var{EConvertError} exception is raised. \SeeAlso \seef{StrToTime}, \seef{DateToStr}n \seef{TimeToStr}. \end{function} \latex{\inputlisting{sysutex/ex19.pp}} \html{\input{sysutex/ex19.tex}} \begin{function}{StrToDateTime} \Declaration Function StrToDateTime(const S: string): TDateTime; \Description \var{StrToDateTime} converts the string \var{S} to a \var{TDateTime} date and time value. The Date must consist of 1 to three digits, separated by the \var{DateSeparator} character. If two numbers are given, they are supposed to form the day and month of the current year. If only one number is given, it is supposed to represent the day of the current month. (This is \em{not} supported in Delphi) The order of the digits (y/m/d, m/d/y, d/m/y) is determined from the \var{ShortDateFormat} variable. \Errors On error (e.g. an invalid date or invalid character), an \var{EConvertError} exception is raised. \SeeAlso \seef{StrToDate}, \seef{StrToTime}, \seef{DateTimeToStr} \end{function} \latex{\inputlisting{sysutex/ex20.pp}} \html{\input{sysutex/ex20.tex}} \begin{function}{StrToTime} \Declaration Function StrToTime(const S: string): TDateTime; \Description \var{StrToTime} converts the string \var{S} to a \var{TDateTime} time value. The time must consist of 1 to 4 digits, separated by the \var{TimeSeparator} character. If two numbers are given, they are supposed to form the hour and minutes. \Errors On error (e.g. an invalid date or invalid character), an \var{EConvertError} exception is raised. \SeeAlso \seef{StrToDate}, \seef{StrToDateTime}, \seef{TimeToStr} \end{function} \latex{\inputlisting{sysutex/ex21.pp}} \html{\input{sysutex/ex21.tex}} \begin{function}{SystemTimeToDateTime} \Declaration Function SystemTimeToDateTime(const SystemTime: TSystemTime): TDateTime; \Description \var{SystemTimeToDateTime} converts a \var{TSystemTime} record to a \var{TDateTime} style date/time indication. \Errors None. \SeeAlso \seep{DateTimeToSystemTime} \end{function} \latex{\inputlisting{sysutex/ex22.pp}} \html{\input{sysutex/ex22.tex}} \begin{function}{Time} \Declaration Function Time: TDateTime; \Description \var{Time} returns the current time in \var{TDateTime} format. The date part of the \var{TDateTimeValue} is set to zero. \Errors None. \SeeAlso \seef{Now}, \seef{Date} \end{function} \latex{\inputlisting{sysutex/ex23.pp}} \html{\input{sysutex/ex23.tex}} \begin{function}{TimeStampToDateTime} \Declaration Function TimeStampToDateTime(const TimeStamp: TTimeStamp): TDateTime; \Description \var{TimeStampToDateTime} converts \var{TimeStamp} to a \var{TDateTime} format variable. It is the inverse operation of \seef{DateTimeToTimeStamp}. \Errors None. \SeeAlso \seef{DateTimeToTimeStamp}, \seef{TimeStampToMSecs} \end{function} \latex{\inputlisting{sysutex/ex24.pp}} \html{\input{sysutex/ex24.tex}} \begin{function}{TimeStampToMSecs} \Declaration Function TimeStampToMSecs(const TimeStamp: TTimeStamp): comp; \Description \var{TimeStampToMSecs} converts {TimeStamp} to the number of seconds since \var{1/1/0001}. Use \var{TTimeStamp} variables if you need to keep very precise track of time. \Errors None. \SeeAlso \seef{MSecsToTimeStamp}, \seef{TimeStampToDateTime} \end{function} For an example, see \seef{MSecsToTimeStamp}. \begin{function}{TimeToStr} \Declaration Function TimeToStr(Time: TDateTime): string; \Description \var{TimeToStr} converts the time in \var{Time} to a string. It uses the \var{ShortTimeFormat} variable to see what formatting needs to be applied. It is therefor entirely equivalent to a \var{FormatDateTime('t',Time)} call. \Errors None. \SeeAlso \end{function} \latex{\inputlisting{sysutex/ex25.pp}} \html{\input{sysutex/ex25.tex}} \section{Disk functions} \begin{functionl}{AddDisk (Linux only)}{AddDisk} \Declaration Function AddDisk (Const PAth : String) : Longint; \Description On Linux both the \seef{Diskfree} and \seef{Disksize} functions need a file on the specified drive, since is required for the statfs system call. These filenames are set in drivestr[0..26], and the first 4 have been preset to : \begin{description} \item[Disk 0] \var{'.'} default drive - hence current directory is used. \item[Disk 1] \var{'/fd0/.'} floppy drive 1. \item[Disk 2] \var{'/fd1/.'} floppy drive 2. \item[Disk 3] \var{'/'} \file{C:} equivalent of DOS is the root partition. \end{description} Drives 4..26 can be set by your own applications with the \var{AddDisk} call. The \var{AddDisk} call adds \var{Path} to the names of drive files, and returns the number of the disk that corresponds to this drive. If you add more than 21 drives, the count is wrapped to 4. \Errors None. \SeeAlso \seef{DiskFree}, \seef{DiskSize} \end{functionl} \begin{function}{CreateDir} \Declaration Function CreateDir(Const NewDir : String) : Boolean; \Description \var{CreateDir} creates a new directory with name \var{NewDir}. If the directory doesn't contain an absolute path, then the directory is created below the current working directory. The function returns \var{True} if the directory was successfully created, \var{False} otherwise. \Errors In case of an error, the function returns \var{False}. \SeeAlso \seef{RemoveDir} \end{function} \latex{\inputlisting{sysutex/ex26.pp}} \html{\input{sysutex/ex26.tex}} \begin{function}{DiskFree} \Declaration Function DiskFree(Drive : Byte) : Longint; \Description \var{DiskFree} returns the free space (in bytes) on disk \var{Drive}. Drive is the number of the disk drive: \begin{description} \item[0] for the current drive. \item[1] for the first floppy drive. \item[2] for the second floppy drive. \item[3] for the first hard-disk parttion. \item[4-26] for all other drives and partitions. \end{description} {\em Remark} Under \linux, and Unix in general, the concept of disk is different than the \dos one, since the filesystem is seen as one big directory tree. For this reason, the \var{DiskFree} and \seef{DiskSize} functions must be mimicked using filenames that reside on the partitions. For more information, see \seef{AddDisk} \Errors On error, \var{-1} is returned. \SeeAlso \seef{DiskSize}, \seef{AddDisk} \end{function} \latex{\inputlisting{sysutex/ex27.pp}} \html{\input{sysutex/ex27.tex}} \begin{function}{DiskSize} \Declaration Function DiskSize(Drive : Byte) : Longint; \Description \var{DiskSize} returns the size (in bytes) of disk \var{Drive}. Drive is the number of the disk drive: \begin{description} \item[0] for the current drive. \item[1] for the first floppy drive. \item[2] for the second floppy drive. \item[3] for the first hard-disk parttion. \item[4-26] for all other drives and partitions. \end{description} {\em Remark} Under \linux, and Unix in general, the concept of disk is different than the \dos one, since the filesystem is seen as one big directory tree. For this reason, the \seef{DiskFree} and \var{DiskSize} functions must be mimicked using filenames that reside on the partitions. For more information, see \seef{AddDisk} \Errors On error, \var{-1} is returned. \SeeAlso \seef{DiskFree}, \seef{AddDisk} \end{function} For an example, see \seef{DiskFree}. \begin{function}{GetCurrentDir} \Declaration Function GetCurrentDir : String; \Description \var{GetCurrentDir} returns the current working directory. \Errors None. \SeeAlso \seef{SetCurrentDir}, \seef{DiskFree}, \seef{DiskSize} \end{function} \latex{\inputlisting{sysutex/ex28.pp}} \html{\input{sysutex/ex28.tex}} \begin{function}{RemoveDir} \Declaration Function RemoveDir(Const Dir : String) : Boolean; \Description \var{RemoveDir} removes directory \var{Dir} from the disk. If the directory is not absolue, it is appended to the current working directory. \Errors In case of error (e.g. the directory isn't empty) the function returns \var{False}. If successful, \var{True} is returned. \SeeAlso \end{function} For an example, see \seef{CreateDir}. \begin{function}{SetCurrentDir} \Declaration Function SetCurrentDir(Const NewDir : String) : Boolean; \Description \var{SetCurrentDir} sets the current working directory of your program to \var{NewDir}. It returns \var{True} if the function was successfull, \var{False} otherwise. \Errors In case of error, \var{False} is returned. \SeeAlso \seef{GetCurrentDir} \end{function} \latex{\inputlisting{sysutex/ex29.pp}} \html{\input{sysutex/ex29.tex}} \section{File handling functions} \begin{function}{ChangeFileExt} \Declaration Function ChangeFileExt(const FileName, Extension: string): string; \Description \var{ChangeFileExt} changes the file extension in \var{FileName} to \var{Extension}. The extension \var{Extension} includes the starting \var{.} (dot). The previous extension of \var{FileName} are all characters after the last \var{.}, the \var{.} character included. If \var{FileName} doesn't have an extension, \var{Extension} is just appended. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExpandFileName} \end{function} \begin{function}{DeleteFile} \Declaration Function DeleteFile(Const FileName : String) : Boolean; \Description \var{DeleteFile} deletes file \var{FileName} from disk. The function returns \var{True} if the file was successfully removed, \var{False} otherwise. \Errors On error, \var{False} is returned. \SeeAlso \seef{CreateFile}, \seef{FileExists} \end{function} \latex{\inputlisting{sysutex/ex31.pp}} \html{\input{sysutex/ex31.tex}} \begin{procedure}{DoDirSeparators} \Declaration Procedure DoDirSeparators(Var FileName : String); \Description This function replaces all directory separators \var{'\' and '/'} to the directory separator character for the current system. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath} \end{procedure} \latex{\inputlisting{sysutex/ex32.pp}} \html{\input{sysutex/ex32.tex}} \begin{function}{ExpandFileName} \Declaration Function ExpandFileName(Const FileName : string): String; \Description \var{ExpandFileName} expands the filename to an absolute filename. It changes all directory separator characters to the one appropriate for the system first. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath} \end{function} \latex{\inputlisting{sysutex/ex33.pp}} \html{\input{sysutex/ex33.tex}} \begin{function}{ExpandUNCFileName} \Declaration Function ExpandUNCFileName(Const FileName : string): String; \Description \var{ExpandUNCFileName} runs \seef{ExpandFileName} on \var{FileName} and then attempts to replace the driveletter by the name of a shared disk. \Errors \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath} \end{function} \begin{function}{ExtractFileDir} \Declaration Function ExtractFileDir(Const FileName : string): string; \Description \var{ExtractFileDir} returns only the directory part of \var{FileName}, not including a driveletter. The directory name has NO ending directory separator, in difference with \seef{ExtractFilePath}. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath} \end{function} \latex{\inputlisting{sysutex/ex34.pp}} \html{\input{sysutex/ex34.tex}} \begin{function}{ExtractFileDrive} \Declaration Function ExtractFileDrive(const FileName: string): string; \Description \var{Extract} \Errors \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath} \end{function} For an example, see \seef{ExtractFileDir}. \begin{function}{ExtractFileExt} \Declaration Function ExtractFileExt(const FileName: string): string; \Description \var{ExtractFileExt} returns the extension (including the \var{.}(dot) character) of \var{FileName}. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath} \end{function} For an example, see \seef{ExtractFileDir}. \begin{function}{ExtractFileName} \Declaration Function ExtractFileName(const FileName: string): string; \Description \var{ExtractFileName} returns the filename part from \var{FileName}. The filename consists of all characters after the last directory separator character ('/' or '\') or drive letter. The full filename can always be reconstucted by concatenating the result of \seef{ExtractFilePath} and \var{ExtractFileName}. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt},\seef{ExtractRelativePath} \end{function} For an example, see \seef{ExtractFileDir}. \begin{function}{ExtractFilePath} \Declaration Function ExtractFilePath(const FileName: string): string; \Description \var{ExtractFilePath} returns the path part (including driveletter) from \var{FileName}. The path consists of all characters before the last directory separator character ('/' or '\'), including the directory separator itself. In case there is only a drive letter, that will be returned. The full filename can always be reconstucted by concatenating the result of \var{ExtractFilePath} and \seef{ExtractFileName}. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \seef{ExtractRelativePath} \end{function} For an example, see \seef{ExtractFileDir}. \begin{function}{ExtractRelativePath} \Declaration Function ExtractRelativePath(Const BaseName,DestNAme : String): String; \Description \var{ExtractRelativePath} constructs a relative path to go from \var{BaseName} to \var{DestName}. If \var{DestName} is on another drive (Not on Linux) then the whole \var{Destname} is returned. {\em Note:} This function does not exist in the Delphi unit. \Errors None. \SeeAlso \seef{ExtractFileName}, \seef{ExtractFilePath}, \seef{ExtractFileDir}, \seef{ExtractFileDrive}, \seef{ExtractFileExt}, \end{function} \latex{\inputlisting{sysutex/ex35.pp}} \html{\input{sysutex/ex35.tex}} \begin{function}{FileAge} \Declaration Function FileAge(Const FileName : String): Longint; \Description \var{FileAge} returns the last modification time of file \var{FileName}. The FileDate format can be transformed to \var{TDateTime} format with the \seef{FileDateToDateTime} function. \Errors In case of errors, \var{-1} is returned. \SeeAlso \seef{FileDateToDateTime}, \seef{FileExists}, \seef{FileGetAttr} \end{function} \latex{\inputlisting{sysutex/ex36.pp}} \html{\input{sysutex/ex36.tex}} \begin{procedure}{FileClose} \Declaration Procedure FileClose(Handle : Longint); \Description \var{FileClose} closes the file handle \var{Handle}. After this call, attempting to read or write from the handle will result in an error. \Errors None. \SeeAlso \seef{FileCreate}, \seef{FileWrite}, \seef{FileOpen}, \seef{FileRead}, \seef{FileTruncate}, \seef{FileSeek} \end{procedure} \begin{function}{FileCreate} \Declaration Function FileCreate(Const FileName : String) : Longint; \Description \var{FileCreate} creates a new file with name \var{FileName} on the disk and returns a file handle which can be used to read or write from the file with the \seef{FileRead} and \seef{FileWrite} functions. If a file with name \var{FileName} already existed on the disk, it is overwritten. \Errors If an error occurs (e.g. disk full or non-existent path), the function returns \var{-1}. \SeeAlso \seef{FileClose}, \seef{FileWrite}, \seef{FileOpen}, \seef{FileRead}, \seef{FileTruncate}, \seef{FileSeek} \end{function} \begin{function}{FileExists} \Declaration Function FileExists(Const FileName : String) : Boolean; \Description \var{FileExists} returns \var{True} if a file with name \var{FileName} exists on the disk, \var{False} otherwise. \Errors None. \SeeAlso \seef{FileAge}, \seef{FileGetAttr}, \seef{FileSetAttr} \end{function} \begin{function}{FileGetAttr} \Declaration Function FileGetAttr(Const FileName : String) : Longint; \Description \var{FileGetAttr} returns the attribute settings of file \var{FileName}. The attribute is a \var{OR}-ed combination of the following constants: \begin{description} \item[faReadOnly] The file is read-only. \item[faHidden] The file is hidden. (On \linux, this means that the filename starts with a dot) \item[faSysFile] The file is a system file (On \linux, this means that the file is a character, block or FIFO file). \item[faVolumeId] Volume Label. Not possible under \linux. \item[faDirectory] File is a directory. \item[faArchive] file is an archive. Not possible on \linux. \end{description} \Errors In case of error, -1 is returned. \SeeAlso \seef{FileSetAttr}, \seef{FileAge}, \seef{FileGetDate}. \end{function} \begin{function}{FileGetDate} \Declaration Function FileGetDate(Handle : Longint) : Longint; \Description \Errors \SeeAlso \end{function} \begin{function}{FileOpen} \Declaration Function FileOpen(Const FileName : string; Mode : Integer) : Longint; \Description \Errors \SeeAlso \seef{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileRead}, \seef{FileTruncate}, \seef{FileSeek} \end{function} \begin{function}{FileRead} \Declaration Function FileRead(Handle : Longint; Var Buffer; Count : longint) : Longint; \Description \Errors \SeeAlso \seef{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileOpen}, \seef{FileTruncate}, \seef{FileSeek} \end{function} \begin{function}{FileSearch} \Declaration Function FileSearch(Const Name, DirList : String) : String; \Description \Errors \SeeAlso \end{function} \begin{function}{FileSeek} \Declaration Function FileSeek(Handle,Offset,Origin : Longint) : Longint; \Description \Errors \SeeAlso \seef{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileOpen} \seef{FileRead}, \seef{FileTruncate} \end{function} \begin{function}{FileSetAttr} \Declaration Function FileSetAttr(Const Filename : String; Attr: longint) : Longint; \Description \Errors \SeeAlso \end{function} \begin{function}{FileSetDate} \Declaration Function FileSetDate(Handle,Age : Longint) : Longint; \Description \Errors \SeeAlso \end{function} \begin{function}{FileTruncate} \Declaration Function FileTruncate(Handle,Size: Longint) : boolean; \Description \Errors \SeeAlso \seef{FileClose}, \seef{FileWrite}, \seef{FileCreate}, \seef{FileOpen} \seef{FileRead}, \seef{FileSeek} \end{function} \begin{function}{FileWrite} \Declaration Function FileWrite(Handle : Longint; Var Buffer; Count : Longint) : Longint; \Description \Errors \SeeAlso \seef{FileClose}, \seef{FileCreate}, \seef{FileOpen} \seef{FileRead}, \seef{FileTruncate}, \seef{FileSeek} \end{function} \begin{procedure}{FindClose} \Declaration Procedure FindClose(Var F : TSearchrec); \Description \Errors \SeeAlso \end{procedure} \begin{function}{FindFirst} \Declaration Function FindFirst(Const Path : String; Attr : Longint; Var Rslt : TSearchRec) : Longint; \Description \Errors \SeeAlso \end{function} \begin{function}{FindNext} \Declaration Function FindNext(Var Rslt : TSearchRec) : Longint; \Description \Errors \SeeAlso \end{function} \begin{function}{GetDirs} \Declaration Function GetDirs(Var DirName : String; Var Dirs : Array of pchar) : Longint; \Description \Errors \SeeAlso \end{function} \begin{function}{RenameFile} \Declaration Function RenameFile(Const OldName, NewName : String) : Boolean; \Description \Errors \SeeAlso \end{function} \begin{function}{SetDirSeparators} \Declaration Function SetDirSeparators(Const FileName : String) : String; \Description \Errors \SeeAlso \end{function} \section{PChar functions} \begin{function}{StrAlloc} \Declaration Function StrAlloc(Size: cardinal): PChar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrBufSize} \Declaration Function StrBufSize(var Str: PChar): cardinal; \Description \Errors \SeeAlso \end{function} \begin{procedure}{StrDispose} \Declaration Procedure StrDispose(var Str: PChar); \Description \Errors \SeeAlso \end{procedure} \begin{function}{StrPCopy} \Declaration Function StrPCopy(Dest: PChar; Source: string): PChar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrPLCopy} \Declaration Function StrPLCopy(Dest: PChar; Source: string; MaxLen: cardinal): PChar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrPas} \Declaration Function StrPas(Str: PChar): string; \Description \Errors \SeeAlso \end{function} \begin{function}{StrCat} \Declaration Function StrCat(dest,source : pchar) : pchar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrComp} \Declaration Function StrComp(str1,str2 : pchar) : longint; \Description \Errors \SeeAlso \end{function} \begin{function}{StrCopy} \Declaration Function StrCopy(dest,source : pchar) : pchar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrECopy} \Declaration Function StrECopy(dest,source : pchar) : pchar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrEnd} \Declaration Function StrEnd(p : pchar) : pchar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrIComp} \Declaration Function StrIComp(str1,str2 : pchar) : longint; \Description \Errors \SeeAlso \end{function} \begin{function}{StrLCat} \Declaration Function StrLCat(dest,source : pchar;l : longint) : pchar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrLComp} \Declaration Function StrLComp(str1,str2 : pchar;l : longint) : longint; \Description \Errors \SeeAlso \end{function} \begin{function}{StrLCopy} \Declaration Function StrLCopy(dest,source : pchar;maxlen : longint) : pchar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrLen} \Declaration Function StrLen(p : pchar) : longint; \Description \Errors \SeeAlso \end{function} \begin{function}{StrLIComp} \Declaration Function StrLIComp(str1,str2 : pchar;l : longint) : longint; \Description \Errors \SeeAlso \end{function} \begin{function}{StrLower} \Declaration Function strlower(p : pchar) : pchar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrMove} \Declaration Function StrMove(dest,source : pchar;l : longint) : pchar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrNew} \Declaration Function StrNew(p : pchar) : pchar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrPos} \Declaration Function StrPos(str1,str2 : pchar) : pchar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrRScan} \Declaration Function StrRScan(p : pchar;c : char) : pchar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrScan} \Declaration Function StrScan(p : pchar;c : char) : pchar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrUpper} \Declaration Function StrUpper(p : pchar) : pchar; \Description \Errors \SeeAlso \end{function} \section{String functions} \begin{function}{AdjustLineBreaks} \Declaration Function AdjustLineBreaks(const S: string): string; \Description \Errors \SeeAlso \end{function} \begin{function}{AnsiCompareStr} \Declaration Function AnsiCompareStr(const S1, S2: string): integer; \Description \Errors \SeeAlso \end{function} \begin{function}{AnsiCompareText} \Declaration Function AnsiCompareText(const S1, S2: string): integer; \Description \Errors \SeeAlso \end{function} \begin{function}{AnsiExtractQuotedStr} \Declaration Function AnsiExtractQuotedStr(var Src: PChar; Quote: Char): string; \Description \Errors \SeeAlso \end{function} \begin{function}{AnsiLastChar} \Declaration Function AnsiLastChar(const S: string): PChar; \Description \Errors \SeeAlso \end{function} \begin{function}{AnsiLowerCase} \Declaration Function AnsiLowerCase(const s: string): string; \Description \Errors \SeeAlso \end{function} \begin{function}{AnsiQuotedStr} \Declaration Function AnsiQuotedStr(const S: string; Quote: char): string; \Description \Errors \SeeAlso \end{function} \begin{function}{AnsiStrComp} \Declaration Function AnsiStrComp(S1, S2: PChar): integer; \Description \Errors \SeeAlso \end{function} \begin{function}{AnsiStrIComp} \Declaration Function AnsiStrIComp(S1, S2: PChar): integer; \Description \Errors \SeeAlso \end{function} \begin{function}{AnsiStrLComp} \Declaration Function AnsiStrLComp(S1, S2: PChar; MaxLen: cardinal): integer; \Description \Errors \SeeAlso \end{function} \begin{function}{AnsiStrLIComp} \Declaration Function AnsiStrLIComp(S1, S2: PChar; MaxLen: cardinal): integer; \Description \Errors \SeeAlso \end{function} \begin{function}{AnsiStrLast} \Declaration Function AnsiStrLast(Str: PChar): PChar; \Description \Errors \SeeAlso \end{function} \begin{function}{CharAnsiStrLower} \Declaration Function AnsiStrLower(Str: PChar): PChar; \Description \Errors \SeeAlso \end{function} \begin{function}{AnsiStrUpper} \Declaration Function AnsiStrUpper(Str: PChar): PChar; \Description \Errors \SeeAlso \end{function} \begin{function}{AnsiUpperCase} \Declaration Function AnsiUpperCase(const s: string): string; \Description \Errors \SeeAlso \end{function} \begin{procedure}{AppendStr} \Declaration Procedure AppendStr(var Dest: PString; const S: string); \Description \Errors \SeeAlso \end{procedure} \begin{procedure}{AssignStr} \Declaration Procedure AssignStr(var P: PString; const S: string); \Description \Errors \SeeAlso \end{procedure} \begin{function}{BCDToInt} \Declaration Function BCDToInt(Value: integer): integer; \Description \Errors \SeeAlso \end{function} \begin{function}{CompareMem} \Declaration Function CompareMem(P1, P2: Pointer; Length: cardinal): integer; \Description \Errors \SeeAlso \end{function} \begin{function}{CompareStr} \Declaration Function CompareStr(const S1, S2: string): Integer; \Description \Errors \SeeAlso \end{function} \begin{function}{CompareText} \Declaration Function CompareText(const S1, S2: string): integer; \Description \Errors \SeeAlso \end{function} \begin{procedure}{DisposeStr} \Declaration Procedure DisposeStr(S: PString); \Description \Errors \SeeAlso \end{procedure} \begin{function}{FloatToStr} \Declaration Function FloatToStr(Value: Extended): String; \Description \Errors \SeeAlso \end{function} \begin{function}{FloatToStrF} \Declaration Function FloatToStrF(Value: Extended; format: TFloatFormat; Precision, Digits: Integer): String; \Description \Errors \SeeAlso \end{function} \begin{procedure}{FmtStr} \Declaration Procedure (Var Res: String; Const Fmt : String; Const args: Array of const); \Description \Errors \SeeAlso \end{procedure} \begin{function}{Format} \Declaration Function Format(Const Fmt : String; const Args : Array of const) : String; \Description \Errors \SeeAlso \end{function} \begin{function}{FormatBuf} \Declaration Function FormatBuf(Var Buffer; BufLen : Cardinal; Const Fmt; fmtLen : Cardinal; Const Args : Array of const) : Cardinal; \Description \Errors \SeeAlso \end{function} \begin{function}{IntToHex} \Declaration Function IntToHex(Value: integer; Digits: integer): string; \Description \Errors \SeeAlso \end{function} \begin{function}{IntToStr} \Declaration Function IntToStr(Value: integer): string; \Description \Errors \SeeAlso \end{function} \begin{function}{IsValidIdent} \Declaration Function IsValidIdent(const Ident: string): boolean; \Description \Errors \SeeAlso \end{function} \begin{function}{LeftStr} \Declaration Function LeftStr(const S: string; Count: integer): string; \Description \Errors \SeeAlso \end{function} \begin{function}{LoadStr} \Declaration Function LoadStr(Ident: integer): string; \Description \Errors \SeeAlso \end{function} \begin{function}{LowerCase} \Declaration Function LowerCase(const s: string): string; \Description \Errors \SeeAlso \end{function} \begin{function}{NewStr} \Declaration Function NewStr(const S: string): PString; \Description \Errors \SeeAlso \end{function} \begin{function}{QuotedStr} \Declaration Function QuotedStr(const S: string): string; \Description \Errors \SeeAlso \end{function} \begin{function}{RightStr} \Declaration Function RightStr(const S: string; Count: integer): string; \Description \Errors \SeeAlso \end{function} \begin{function}{StrFmt} \Declaration Function StrFmt(Buffer,Fmt : PChar; Const args: Array of const) : Pchar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrLFmt} \Declaration Function StrLFmt(Buffer : PCHar; Maxlen : Cardinal;Fmt : PChar; Const args: Array of const) : Pchar; \Description \Errors \SeeAlso \end{function} \begin{function}{StrToInt} \Declaration Function StrToInt(const s: string): integer; \Description \Errors \SeeAlso \end{function} \begin{function}{StrToIntDef} \Declaration Function StrToIntDef(const S: string; Default: integer): integer; \Description \Errors \SeeAlso \end{function} \begin{function}{Trim} \Declaration Function Trim(const S: string): string; \Description \Errors \SeeAlso \end{function} \begin{function}{TrimLeft} \Declaration Function TrimLeft(const S: string): string; \Description \Errors \SeeAlso \end{function} \begin{function}{TrimRight} \Declaration Function TrimRight(const S: string): string; \Description \Errors \SeeAlso \end{function} \begin{function}{UpperCase} \Declaration Function UpperCase(const s: string): string; \Description \Errors \SeeAlso \end{function}