From cd861f2efc72f2918f247aa78a72f7ff9ac702aa Mon Sep 17 00:00:00 2001 From: michael Date: Fri, 22 Oct 2004 20:45:36 +0000 Subject: [PATCH] + Finished units --- docs/baseunix.xml | 2 +- docs/dynlibs.xml | 153 ++++++++++++++++ docs/linux.xml | 237 +++++++++++++++++++++++++ docs/unix.xml | 443 +++++++++++++++++++++++++++++++++++++--------- docs/unixutil.xml | 290 ++++++++++++++++++++++++++++++ docs/x86.xml | 312 ++++++++++++++++++++++++++++++++ 6 files changed, 1350 insertions(+), 87 deletions(-) create mode 100644 docs/dynlibs.xml create mode 100644 docs/linux.xml create mode 100644 docs/unixutil.xml create mode 100644 docs/x86.xml diff --git a/docs/baseunix.xml b/docs/baseunix.xml index 33a27dabf0..82ce0acecc 100644 --- a/docs/baseunix.xml +++ b/docs/baseunix.xml @@ -4111,7 +4111,7 @@ socket. If so it returns True. -Extract the exit status from the result. +Extract the exit status from the fpWaitPID result. WEXITSTATUS can be used to extract the exit status from Status, the result of the call. diff --git a/docs/dynlibs.xml b/docs/dynlibs.xml new file mode 100644 index 0000000000..5346261e6a --- /dev/null +++ b/docs/dynlibs.xml @@ -0,0 +1,153 @@ + + + + + +Cross-platform support for dynamically loadable libraries + +

+The Dynlibs unit provides support for dynamically loading +shared libraries. It is available only on those platforms that support +shared libraries. The functionality available here may only be a part of +the functionality available on each separate platform, in the interest of +portability. +

+

+On unix platforms, using this unit will cause the program to be linked to +the C library, as most shared libraries are implemented in C and the +dynamical linker too. +

+ + + + +Library handle type + +TLibHandle should be considered an opaque type. It is defined +differently on various platforms. The definition shown here depends on the +platform for which the documentation was generated. + + + + + + + + + +Correctly typed Nil handle - returned on error by + + + + +Load a dynamic library and return a handle to it. + +

+LoadLibrary loads a dynamic library in file Name +and returns a handle to it. If the library cannot be loaded, + is returned. +

+

+No assumptions should be made about the location of the loaded library if a +relative pathname is specified. The behaviour is dependent on the platform. +Therefore it is best to specify an absolute pathname if possible. +

+ + +On error, is returned. + + + + + + + + + +Get the address of a procedure or symbol in a dynamic library. + +

+GetProcedureAddress returns a pointer to the location in memory +of the symbol ProcName in the dynamically loaded library +specified by it's handle lib. If the symbol cannot be found or +the handle is invalid, Nil is returned. +

+

+On Windows, only an exported procedure or +function can be searched this way. On Unix platforms the location of any +exported symbol can be retrieved this way. +

+ + +If the symbol cannot be found, Nil is returned. + + + + + + + + + +Unload a previously loaded library + +UnloadLibrary unloads a previously loaded library (specified by +the handle lib). The call returns True if succesful, +False otherwisa. + + +On error, False is returned. + + + + + + + + + +For compatibility with Delphi/Windows: Unload a library + +FreeLibrary provides the same functionality as , and is provided for compatibility with Delphi. + + + + + + + + +For compatibility with Delphi/Windows: Get the address of a procedure + +GetProcAddress provides the same functionality as , and is provided for compatibility with Delphi. + + + + + + + + + diff --git a/docs/linux.xml b/docs/linux.xml new file mode 100644 index 0000000000..412114bc38 --- /dev/null +++ b/docs/linux.xml @@ -0,0 +1,237 @@ + + + + + +Linux-specific operating system calls. + +

+The linux unit contains linux specific operating system calls. +

+

+The platform independent functionality of the FPC 1.0.X version of the +linux unit has been split out over the +unix, baseunix and +unixutil units. +

+

+The X86-specific parts have been moved to the X86 +unit. +

+

+People wanting to use the old version (FPC 1.0.X and before) of the +linux can use the oldlinux unit +instead. +

+ + + + +Record with system information, used by the call. + + + + +Number of seconds since boot. + + + + +1, 5 and 15 minute load averages. + + + + +total amount of main memory. + + + + +amount of free memory. + + + + +amount of shared memory. + + + + +amount of memory used by buffers. + + + + +total amount of swapspace. + + + + +amount of free swapspace. + + + + +number of current processes. + + + + +? + + + + +Pointer to record. + + + + +Return kernel system information + +

+SysInfo returns system information in Info. Returned information +in Info includes: +

+
+
uptime
Number of seconds since boot.
+
loads
1, 5 and 15 minute load averages.
+
totalram
total amount of main memory.
+
freeram
amount of free memory.
+
sharedram
amount of shared memory.
+
bufferram
amount of memory used by buffers.
+
totalswap
total amount of swapspace.
+
freeswap
amount of free swapspace.
+
procs
number of current processes.
+
+ + +None. + + + + + + + + + + option: Signal mask to be sent at exit + + + + + option: VM shared between processes + + + + + option: fs info shared between processes + + + + + option: open files shared between processes + + + + + option: signal handlers shared between processes + + + + + option: PID shared between processes + + + + +Clone function prototype. + + + + +Clone current process (create new thread) + +

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

+

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

+

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

+

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

+
+
CLONE_VM
+
Parent and child share the same memory space, including +memory (un)mapped with subsequent mmap calls.
+
CLONE_FS
+
Parent and child have the same view of the filesystem; +the chroot, chdir and umask calls affect both processes.
+
CLONE_FILES
+
the file descriptor table of parent and child is shared.
+
CLONE_SIGHAND
+
the parent and child share the same table of signal +handlers. The signal masks are different, though.
+
CLONE_PID
+
PArent and child have the same process ID.
+
+

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

+ + +

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

+
+
sys_eagain
Too many processes are running.
+
sys_enomem
Not enough memory to create child process.
+
+ + + + + + + + + diff --git a/docs/unix.xml b/docs/unix.xml index 4b4f263f70..919c70bffb 100644 --- a/docs/unix.xml +++ b/docs/unix.xml @@ -2125,7 +2125,7 @@ Extended error information is returned by the + @@ -2255,8 +2255,8 @@ with . The result is the same, but PClose returns exit status of the command Prog. -Extended error information is returned by the FpGetErrno -function. Errors are essentially those of the Execve, Dup and AssignPipe commands. +Extended error information is returned by the FpGetErrno function. +Errors are essentially those of the Execve, Dup and AssignPipe commands. @@ -2299,8 +2299,7 @@ error.

-In case of error (return value -1) LinuxError is used to report -errors: +Extended error information is returned by the FpGetErrno function.

sys_emfile
@@ -2354,234 +2353,506 @@ None. - +Expand filename to fully qualified path +FExpand expands Path to a full path, starting from root, +eliminating directory references such as . and .. from the result. +None - - + - - - - - - - - - - - - - - - - - - - - - - - +Search for file in search path. +

+FSearch searches in DirList, a colon separated list of directories, +for a file named Path. It then returns a path to the found file. +

+

+The CurrentDirStrategy determines how the current directory is treated +when searching: +

+
+
NoCurrentDirectory
+
CurrentDirectoryFirst
+
CurrentDirectoryLast
+
+

+It is mainly provided to mimic DOS search path behaviour. Default behaviour +is to search the current directory first. +

 +An empty string if no such file was found. + + + - +Find filenames matching a wildcard pattern +

Glob returns a pointer to a glob structure which contains all filenames which +exist and match the pattern in Path. +The pattern can contain wildcard characters, which have their +usual meaning. +

 +

+Returns nil on error, and extended error information is returned by the FpGetErrno function. + +

+
+
sys_enomem
No memory on heap for glob structure.
+
others
As returned by the opendir call, and sys_readdir.
+
 + + - +Free result of call +

+Releases the memory, occupied by a pglob structure. P is set to nil. +

+

+For an example, see . +

 +None + - +Raise a signal (send to current process) +SigRaise sends a Sig signal to the current process. +None. + + + - +Create memory map of a file +

+FpMMap maps or unmaps files or devices into memory. The different +arguments determine what and how the file is mapped: +

+
+
adr
+
Address where to mmap the device. This address is a hint, +and may not be followed.
+
len
Size (in bytes) of area to be mapped.
+
prot
+
+

Protection of mapped memory. This is a OR-ed combination of the +following constants:

+
+
PROT_EXEC
The memory can be executed.
+
PROT_READ
The memory can be read.
+
PROT_WRITE
The memory can be written.
+
PROT_NONE
The memory can not be accessed.
+
+
+
flags

Contains some options for the mmap call. It is an OR-ed +combination of the following constants:

+
+
MAP_FIXED
+
Do not map at another address than the given address. If the +address cannot be used, MMap will fail.
+
MAP_SHARED
+
Share this map with other processes that map this object.
+
MAP_PRIVATE
+
Create a private map with copy-on-write semantics.
+
MAP_ANONYMOUS
+
fd does not have to be a file descriptor.
+
+

+One of the options MAP_SHARED and MAP_PRIVATE must be present, +but not both at the same time. +

+
+
fd
File descriptor from which to map.
+
off
Offset to be used in file descriptor fd.
+
+

+The function returns a pointer to the mapped memory, or a -1 in case of en +error. +

 +

+On error, -1 is returned and extended error information is returned by the FpGetErrno function. +

+
+
Sys_EBADF
+
fd is not a valid file descriptor and +MAP_ANONYMOUS was not specified.
+
Sys_EACCES
+
MAP_PRIVATE was specified, but fd is not open for +reading. Or MAP_SHARED was asked and PROT_WRITE is set, fd +is not open for writing
+
Sys_EINVAL
+
One of the record fields Start, length or +offset is invalid.
+
Sys_ETXTBUSY
+
MAP_DENYWRITE was set but the object specified +by fd is open for writing.
+
Sys_EAGAIN
+
fd is locked, or too much memory is locked.
+
Sys_ENOMEM
+
Not enough memory for this operation.
+
 + + - +Unmap previously mapped memory block +

+FpMUnMap unmaps the memory block of size Len, pointed to by +Adr, which was previously allocated with . +

+

+The function returns True if successful, False otherwise. +

+

+For an example, see . +

 +In case of error the function returns a nonzero value, +extended error information is returned by the FpGetErrno function. +See for possible error values. + - +Return kernel time of day in GMT +

+FpGetTimeOfDay returns the number of seconds since 00:00, January 1 +1970, GMT in a timeval record. This time NOT corrected any way, +not taking into account timezones, daylight savings time and so on. +

+

+It is simply a wrapper to the kernel system call. To get the local time, +. +

 +None. + + - +Set process priority +

+Nice adds -N to the priority of the running process. The lower the +priority numerically, the less the process is favored. +Only the superuser can specify a negative N, i.e. increase the rate at +which the process is run. +

+

+If the function is succesful, zero is returned. On error, a nonzero value is returned. +

 +

+Extended error information is returned by the FpGetErrno function. +

+
+
sys_eperm
A non-superuser tried to specify a negative N, i.e. +do a priority increase.
+
 + + + - +Return process priority +

+GetPriority returns the priority with which a process is running. +Which process(es) is determined by the Which and Who variables. +Which can be one of the pre-defined Prio_Process, +Prio_PGrp, Prio_User, in which case Who is the process ID, Process group ID or +User ID, respectively. +

+

+For an example, see . +

 +

+Error information is returned solely by the FpGetErrno +function: a priority can be a positive or negative value. +

+
+
sys_esrch
+
No process found using which and who.
+
sys_einval
+
Which was not one of Prio_Process, +Prio_Grp or Prio_User.
+
 + + - +Set process priority +

+fpSetPriority sets the priority with which a process is running. +Which process(es) is determined by the Which and Who variables. +Which can be one of the pre-defined constants: +

+
+
Prio_Process
Who is interpreted as process ID
+
Prio_PGrp
Who is interpreted as process group ID
+
Prio_User
Who is interpreted as user ID
+
+

+Prio is a value in the range -20 to 20. +

+

+For an example, see . +

+

+The function returns zero on success, -1 on failure +

 +

+Extended error information is returned by the FpGetErrno +function. +

+
+
sys_esrch
+
No process found using which and who.
+
sys_einval
+
Which was not one of Prio_Process, +Prio_Grp or Prio_User.
+
sys_eperm
+
A process was found, but neither its effective or real +user ID match the effective user ID of the caller.
+
sys_eacces
+
A non-superuser tried to a priority increase.
+
 + + - +Return information about symbolic link. Do not follow the link +FpLstat gets information about the link specified in Path +(or FileName, and stores it in Info, which points to a +record of type TStat. Contrary to FpFstat, it stores +information about the link, not about the file the link points to. +The function returns zero if the call was succesful, a nonzero return value +indicates failure. +failed. +

+Extended error information is returned by the FpGetErrno +function. +

+
+
sys_enoent
Path does not exist.
+
 + + + - - - - - - - - - - - +Create a symbolic link +

+SymLink makes NewName point to the file in +OldName, which doesn't necessarily exist. The two files +DO NOT have the same inode number. This is known as a 'soft' link. +

+

The permissions of the link are irrelevant, as they are not used when +following the link. Ownership of the file is only checked in case of removal +or renaming of the link. +

+

+The function returns zero if the call was succesful, a nonzero value if the call +failed. +

 +

+Extended error information is returned by the FpGetErrno +function. +

+
+
sys_eperm
+
The filesystem containing oldpath and newpath does not +support linking files.
+
sys_eaccess
+
Write access for the directory containing Newpath +is disallowed, or one of the directories in OldPath or +NewPath has no search (=execute) permission.
+
sys_enoent
+
A directory entry in OldPath or NewPath does +not exist or is a symbolic link pointing to a non-existent directory.
+
sys_enotdir
+
A directory entry in OldPath or NewPath is +nor a directory.
+
sys_enomem
Insufficient kernel memory.
+
sys_erofs
The files are on a read-only filesystem.
+
sys_eexist
NewPath already exists.
+
sys_eloop
+
OldPath or NewPath has a reference to a circular +symbolic link, i.e. a symbolic link, whose expansion points to itself. +
+
sys_enospc
+
The device containing NewPath has no room for another entry.
+
 + + + + - +Read destination of symbolic link +

+FpReadLink returns the file the symbolic link name is pointing +to. The first form of this function accepts a buffer linkname of +length maxlen where the filename will be stored. It returns the +actual number of characters stored in the buffer. +

+

+The second form of the function returns simply the name of the file. +

 +

+On error, the first form of the function returns -1; the second one returns +an empty string. +Extended error information is returned by the FpGetErrno +function. +

+
+
SYS_ENOTDIR
+
A part of the path in Name is not a directory.
+
SYS_EINVAL
+
maxlen is not positive, or the file is not a symbolic link.
+
SYS_ENAMETOOLONG
+
A pathname, or a component of a pathname, was too long.
+
SYS_ENOENT
+
the link name does not exist.
+
SYS_EACCES
+
No permission to search a directory in the path
+
SYS_ELOOP
+
Too many symbolic links were encountered in translating the pathname.
+
SYS_EIO
+
An I/O error occurred while reading from the file system.
+
SYS_EFAULT
+
The buffer is not part of the the process's memory space.
+
SYS_ENOMEM
+
Not enough kernel memory was available.
+
 + + - +Close file opened with +

+PClose closes a file opened with . +It waits for the command to complete, and then returns the exit status of the command. +

+

+For an example, see +

 +Extended error information is returned by the FpGetErrno +function. + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/unixutil.xml b/docs/unixutil.xml new file mode 100644 index 0000000000..592b36a2d5 --- /dev/null +++ b/docs/unixutil.xml @@ -0,0 +1,290 @@ + + + + + + + +Unix utility routines. + +

+The UnixUtil unit contains some of the routines that were +present in the old Linux unit, but which do not really belong +in the unix or baseunix +units. +

+

+Most of the functions described here have cross-platform counterparts in the +SysUtils unit. It is therefore recommended +to use that unit. +

+ + + + +Seconds west of GMT + + + +Command-line string type. + + + +Filename full path string type. + + + +Filename directory part string type. + + + +Filename name part string type. + + + +Filename extension part string type. + + + + +Extract directory part from filename + +

+Returns the directory part of Path. +The directory is the part of Path before the last slash, +or empty if there is no slash. +The last character of the result is not a slash, unless the directory is the +root directory. +

+ + +None. + + + + + + + + + + +Split string in list of null-terminated strings + +

+StringToPPChar splits the string S in words, replacing any +whitespace with zero characters. It returns a pointer to an array of pchars +that point to the first letters of the words in S. This array is terminated +by a Nil pointer. +

+

+The function does not add a zero character to the end of the string +unless it ends on whitespace. +

+

+The function reserves memory on the heap to store the array of PChar; +The caller is responsible for freeing this memory. +

+

+This function can be called to create arguments for the various Exec +calls. +

+ + +None. + + + + + + + + + + + + +Concert an array of string to an array of null-terminated strings + +

+ArrayStringToPPchar creates an array of null-terminated strings +that point to strings which are the same as the strings in the array +S. The function returns a pointer to this array. The array and +the strings it contains must be disposed of after being used, because it +they are allocated on the heap. +

+

+The ReserveEntries parameter tells ArrayStringToPPchar +to allocate room at the end of the array for another ReserveEntries +entries. +

+ + +If not enough memory is available, an error may occur. + + + + + + + + +Return basename of a file + +

+Returns the filename part of Path, stripping off Suf if it +exists. +The filename part is the whole name if Path contains no slash, +or the part of Path after the last slash. +The last character of the result is not a slash, unless the directory is the +root directory. +

+ + +None. + + + + + + + + + + +Check whether filename matches wildcard specification + +

+FNMatch returns True if the filename in Name +matches the wildcard pattern in Pattern, False otherwise. +

+

+Pattern can contain the wildcards * (match zero or more +arbitrary characters) or ? (match a single character). +

+ + +None. + + + + + + + + + + +Return file selector + +GetFS returns the file selector that the kernel provided for your +file. In principle you don' need this file selector. Only for some calls +it is needed, such as the call or so. + + +In case the file was not opened, then -1 is returned. + + + + + + + + + +Split filename into path, name and extension + +FSplit splits a full file name into 3 parts : A Path, a +Name and an extension (in ext). +The extension is taken to be all letters after the last dot (.). + + +None. + + + + + + + + + +Convert local time to epoch (unix) time + +Converts the Local time to epoch time (=Number of seconds since 00:00:00 , January 1, +1970 ). + + +None + + + + + + + + + + + + +Convert epoch time to local time + +

+Converts the epoch time (=Number of seconds since 00:00:00 , January 1, +1970, corrected for your time zone ) to local date and time. +

+

+This function takes into account the timzeone settings of your system. +

+ + +None + + + + + + + + + + + + +Converts a julian date to a gregorian date + +JulianToGregorian takes a julian day and converts it to a +gregorian date. (Start of the Julian Date count is from 0 at 12 noon 1 JAN -4712 +(4713 BC),) + + +None. + + + + + + + + +Converts a gregorian date to a julian date + +GregorianToJulian takes a gregorian date and converts it to a +Julian day. + + +None. + + + + + + + + + diff --git a/docs/x86.xml b/docs/x86.xml new file mode 100644 index 0000000000..111ade1283 --- /dev/null +++ b/docs/x86.xml @@ -0,0 +1,312 @@ + + + + + +Intel X86 specific routines for unix platforms. + + +

+The x86 unit contains some of the routines that were present in +the 1.0.X Linux unit, and which were Intel (PC) architecture specific. +

+

+These calls have been preserved for compatibility, but should be considered +deprecated: they are not portable and may not even work on future linux +versions. +

+ + + +Read data from a PC port + +

+ReadPort reads one Byte, Word or Longint from port Port into +Value. +

+

+Note that you need permission to read a port. This permission can be set by +the root user with the call. +

+ + +In case of an error (not enough permissions read this port), runtime 216 +( Access Violation) will occur. + + + + + + +, + + + + + + + +Read bytes from a PC port + +

+The procedural form of ReadPortB reads Count bytes from port +Port and stores them in Buf. There must be enough memory +allocated at Buf to store Count bytes. +

+

+The functional form of ReadPortB reads 1 byte from port B +and returns the byte that was read. +

+

+Note that you need permission to read a port. This permission can be set by +the root user with the call. +

+ + +In case of an error (not enough permissions read this port), runtime 216 +( Access Violation) will occur. + + + + + + +, + + + + + + + +Read longints from a PC port + +

+The procedural form of ReadPortL reads Count longints from port +Port and stores them in Buf. There must be enough memory +allocated at Buf to store Count Longints. +

+

+The functional form of ReadPortL reads 1 longint from port B +and returns the longint that was read. +

+

+Note that you need permission to read a port. This permission can be set by +the root user with the call. +

+ + +In case of an error (not enough permissions read this port), runtime 216 +( Access Violation) will occur. + + + + + + +, + + + + + + + +Read Words from a PC port + +

+The procedural form of ReadPortW reads Count words from port +Port and stores them in Buf. There must be enough memory +allocated at Buf to store Count words. +

+

+The functional form of ReadPortW reads 1 word from port B +and returns the word that was read. +

+

+Note that you need permission to read a port. This permission can be set by +the root user with the call. +

+ + +In case of an error (not enough permissions read this port), runtime 216 +( Access Violation) will occur. + + + + + + +, + + + + + + + +Write data to PC port + +

+WritePort writes Value -- 1 byte, Word or longint -- +to port Port. +

+ +You need permission to write to a port. This permission can be set with root +permission with the call. + + + +In case of an error (not enough permissions to write to this port), runtime 216 +( Access Violation) will occur. + + + + + + + + + + + + + + +Write byte to PC port + +

+The first form of WritePortB writes 1 byte to port Port. +The second form writes Count bytes from Buf to port Port. +

+ +You need permission to write to a port. This permission can be set with root +permission with the call. + + + +In case of an error (not enough permissions to write to this port), runtime 216 +( Access Violation) will occur. + + + + + + + + + + + + + + +Write longint to PC port. + +

+The first form of WritePortB writes 1 byte to port Port. +The second form writes Count bytes from Buf to port Port. +

+ +You need permission to write to a port. This permission can be set with root +permission with the call. + + + +In case of an error (not enough permissions to write to this port), runtime 216 +( Access Violation) will occur. + + + + + + + + + + + + + + +Write Word to PC port + +

+The first form of WritePortB writes 1 byte to port Port. +The second form writes Count bytes from Buf to port Port. +

+ +You need permission to write to a port. This permission can be set with root +permission with the call. + + + +In case of an error (not enough permissions to write to this port), runtime 216 +( Access Violation) will occur. + + + + + + + + + + + + + +Set permission on IO ports + +

+FpIOperm +sets permissions on Num ports starting with port From to +Value. The function returns zero if the call was successfull, +a nonzero value otherwise. +

+

+Note: +

+
    +
  • This works ONLY as root.
    • +
  • Only the first 0x03ff ports can be set.
    • +
  • When doing a FpFork, the permissions are reset. +When doing a FpExecVE they are kept.
    • +
+ + +Extended error information can be retrieved with FpGetErrno + + + + +Set I/O privilege level + +FpIoPL sets the I/O privilige level. It is intended for +completeness only, one should normally not use it. + + + + + +