Files and Filenames

Files are identified by filenames, which are represented in &GAP; as strings. Filenames can be created directly by the user or a program, but of course this is operating system dependent.

Filenames for some files can be constructed in a system independent way using the following functions. This is done by first getting a directory object for the directory the file shall reside in, and then constructing the filename. However, it is sometimes necessary to construct filenames of files in subdirectories relative to a given directory object. In this case the directory separator is always / even under DOS or MacOS.

Section describes how to construct directory objects for the common &GAP; and system directories. Using the command it is possible to construct a filename pointing to a file in these directories. There are also functions to test for accessibility of files, see .

Portability

For portability filenames and directory names should be restricted to at most 8 alphanumerical characters optionally followed by a dot . and between 1 and 3 alphanumerical characters. Upper case letters should be avoided because some operating systems do not make any distinction between case, so that NaMe, Name and name all refer to the same file whereas some operating systems are case sensitive. To avoid problems only lower case characters should be used.

Another function which is system-dependent is .

returns a record describing the last system error that has occurred. This record contains at least the component message which is a string. This message is, however, highly operating system dependent and should only be used as an informational message for the user.
GAP Root Directories
GAPInfo.RootPaths
GAPInfo.UserGapRoot

When &GAP; is started it determines a list of directories which we call the &GAP; root directories. In a running &GAP; session this list can be found in GAPInfo.RootPaths.

The core part of &GAP; knows which files to read relative to its root directories. For example when &GAP; wants to read its library file lib/group.gd, it appends this path to each path in GAPInfo.RootPaths until it finds the path of an existing file. The first file found this way is read.

Furthermore, &GAP; looks for available packages by examining the subdirectories pkg/ in each of the directories in GAPInfo.RootPaths.

The root directories are specified via one or several of the -l paths command line options, see . Furthermore, by default &GAP; automatically prepends a user specific &GAP; root directory to the list; this can be avoided by calling &GAP; with the -r option. The name of this user specific directory depends on your operating system, it can be found in GAPInfo.UserGapRoot. This directory can be used to tell &GAP; about personal preferences, to always load some additional code, to install additional packages, or to overwrite some &GAP; files. See for more information how to do this.

Directories
<#Include Label="IsDirectory"> <#Include Label="Directory"> <#Include Label="DirectoryTemporary"> <#Include Label="DirectoryCurrent"> <#Include Label="DirectoriesLibrary"> <#Include Label="DirectoriesSystemPrograms"> <#Include Label="DirectoryContents"> <#Include Label="DirectoryDesktop"> <#Include Label="DirectoryHome">

File Names
<#Include Label="Filename">

Special Filenames

The special filename "*stdin*" denotes the standard input, i.e., the stream through which the user enters commands to &GAP;. The exact behaviour of reading from "*stdin*" is operating system dependent, but usually the following happens. If &GAP; was started with no input redirection, statements are read from the terminal stream until the user enters the end of file character, which is usually Ctrl-D. Note that terminal streams are special, in that they may yield ordinary input after an end of file. Thus when control returns to the main read-eval-print loop the user can continue with &GAP;. If &GAP; was started with an input redirection, statements are read from the current position in the input file up to the end of the file. When control returns to the main read eval view loop the input stream will still return end of file, and &GAP; will terminate.

The special filename "*errin*" denotes the stream connected to the UNIX stderr output. This stream is usually connected to the terminal, even if the standard input was redirected, unless the standard error stream was also redirected, in which case opening of "*errin*" fails.

The special filename "*stdout*" can be used to print to the standard output.

The special filename "*errout*" can be used to print to the standard error output file, which is usually connected to the terminal, even if the standard output was redirected.

File Access

When the following functions return false one can use to find out the reason (as provided by the operating system), see the examples.

returns true if a file with the filename name-file exists and can be seen by the &GAP; process. Otherwise false is returned.

gap> IsExistingFile( "/bin/date" ); # file `/bin/date' exists true gap> IsExistingFile( "/bin/date.new" ); # non existing `/bin/date.new' false gap> IsExistingFile( "/bin/date/new" ); # `/bin/date' is not a directory false gap> LastSystemError().message; "Not a directory"
returns true if a file with the filename name-file exists and the &GAP; process has read permissions for the file, or false if this is not the case.

gap> IsReadableFile( "/bin/date" ); # file `/bin/date' is readable true gap> IsReadableFile( "/bin/date.new" ); # non-existing `/bin/date.new' false gap> LastSystemError().message; "No such file or directory"
returns true if a file with the filename name-file exists and the &GAP; process has write permissions for the file, or false if this is not the case.

gap> IsWritableFile( "/bin/date" ); # file `/bin/date' is not writable false

returns true if a file with the filename name-file exists and the &GAP; process has execute permissions for the file, or false if this is not the case. Note that execute permissions do not imply that it is possible to execute the file, e.g., it may only be executable on a different machine.

gap> IsExecutableFile( "/bin/date" ); # ... but executable true
returns true if the file with the filename name-file exists and is a directory, and false otherwise. Note that this function does not check if the &GAP; process actually has write or execute permissions for the directory. You can use , resp. to check such permissions.
File Operations
<#Include Label="Read"> <#Include Label="ReadAsFunction">

PrintTo and AppendTo
works like , except that the arguments obj1, \ldots (if present) are printed to the file with the name name-file instead of the standard output. This file must of course be writable by &GAP;. Otherwise an error is signalled. Note that will overwrite the previous contents of this file if it already existed; in particular, with just the name-file argument empties that file.

works like , except that the output does not overwrite the previous contents of the file, but is appended to the file.

There is an upper limit of 15 on the number of output files that may be open simultaneously.

Note
that one should be careful not to write to a logfile (see ) with or .
LogTo
Calling with a string name-file causes the subsequent interaction to be logged to the file with the name name-file, i.e., everything you see on your terminal will also appear in this file. ( may also be used to log to a stream.) This file must of course be writable by &GAP;, otherwise an error is signalled. Note that will overwrite the previous contents of this file if it already existed.

Called without arguments, stops logging to a file or stream.
InputLogTo
Calling with a string name-file causes the subsequent input to be logged to the file with the name name-file, i.e., everything you type on your terminal will also appear in this file. Note that and cannot be used at the same time while and can. Note that will overwrite the previous contents of this file if it already existed.

Called without arguments, stops logging to a file or stream.
OutputLogTo
Calling with a string name-file causes the subsequent output to be logged to the file with the name name-file, i.e., everything &GAP; prints on your terminal will also appear in this file. Note that and cannot be used at the same time while and can. Note that will overwrite the previous contents of this file if it already existed.

Called without arguments, stops logging to a file or stream.
<#Include Label="CrcFile">

will remove the file with filename name-file and returns true in case of success. The function returns fail if a system error occurred, for example, if your permissions do not allow the removal of name-file. In this case the function can be used to get information about the error.
<#Include Label="Reread">