next up previous contents index
Next: Socket and Xic Client/Server Up: Main Functions 2 Previous: Date and Time   Contents   Index

File System Interface

(string) Glob(pattern)
This function returns a string which is a filename expansion of the pattern string, in the manner of the C-shell. The pattern can contain the usual substitution characters *, ?, [ ], { }.

Example: Return a list of ``.gds'' files in the current directory.

list = Glob("*.gds")

(file_handle) Open(file, mode)
This function opens the file given as a string argument according to the string mode, and returns a file descriptor. The mode string should consist of a single character: `r' for reading, `w' to write, or `a' to append. If the returned value is negative, an error occurred.

(file_handle) Popen(command, mode)
This command opens a pipe to the shell command given as the first argument, and returns a file handle that can be used to read and/or write to the process. The handle should be closed with the Close function. This is a wrapper around the C library popen command so has the same limitations as the local version of that command. In particular, on some systems the mode may be reading or writing, but not both. The function will fail if either argument is null or if the popen call fails.

(file_handle) Sopen(host, port)
This function opens a ``socket'' which is a communications channel to the given host and port. If the host string is null or empty, the local host is assumed. The port number must be provided, there is no default. If the open is successful, the return value is an integer larger than zero and is a handle that can be used in any of the read/write functions that accept a file handle. The Close function should be called on the handle when the interaction is complete. If the connection fails, a negative number is returned. The function fails if there is a major error, such as no BSD sockets support.

(string) ReadLine(maxlen, file_handle)
The ReadLine function returns a string with length up to maxlen filled with characters read from file_handle. The file_handle must have been successfully opened for reading with a call to Open, Popen, or Sopen. The read is terminated by end of file, a return character, or a null byte. The terminating character is not included in the string. A null string is returned when the end of file is reached, or if the handle is not found. The function will fail if the handle is not a file handle, or maxlen is less than 1.

(int) ReadChar(file_handle)
The ReadChar function returns a single character read from file_handle, which must have been successfully opened for reading with an Open, Popen, or Sopen call. The function returns EOF (-1) when the end of file is reached, or if the handle is not found. The function will fail if the handle is not a file handle.

(int) WriteLine(string, file_handle)
The WriteLine function writes the content of string to file_handle, which must have been successfully opened for writing or appending with an Open, Popen, or Sopen call. The number of characters written is returned. The function will fail if the handle is not a file handle, or the string is null.

This function has the unusual property that it will accept the arguments in reverse order.

WriteLine does not append a carriage return character to the string. See the PrintLog function for a variable argument list alternative that does append a return character.

(int) WriteChar(c, file_handle)
This function writes a single character c to file_handle, which must have been successfully opened for writing or appending with a call to Open, Popen, or Sopen. The function returns 1 on success. The function will fail if the handle is not a file handle, or the integer value of c is not in the range 0-255.

This function has the unusual property that it will accept the arguments in reverse order.

(string) TempFile(prefix)
This function creates a unique temporary file name using the prefix string given, and arranges for the file of that name to be deleted when the program terminates. The file is not actually created. The return from this command is passed to the Open command to actually open the file for writing.

(stringlist_handle) ListDirectory(path, filter)
This function returns a handle to a list of names of files and/or directories in the given directory. If the path argument is null or empty, the current directory is understood. If the filter string is null or empty, all files and subdirectories will be listed. Otherwise the filter string can be ``f'' in which case only regular files will be listed, or ``d'' in which case only directories will be listed. If the directory does not exist or can't be read, 0 is returned, otherwise the return value is a handle to a list of strings.

(int) MakeDir(path)
This function will create a directory, if it doesn't already exist. If the path specifies a multi-component path, all parent directories needed will be created. The function will fail if a null or empty path is passed, otherwise the return value is 1 if no errors, 0 otherwise, with a message available from GetError. Passing the name of an existing directory is not an error.

(int) FileStat(path, array)
This function returns 1 if the file in path exists, and fills in some data about the file (or directory). If the file does not exist, 0 is returned, and the array is untouched.

The array must have size 7 or larger, or a value 0 can be passed for this argument. In this case, no statistics are returned, but the function return still indicates file existence.

If an array is passed and the path points to an existing file or directory, the array is filled in as follows:

array[0]
Set to 0 if path is a regular file. Set to 1 if path is a directory. Set to 2 if path is some other type of object.

array[1]
The size of the regular file in bytes, undefined if not a regular file.

array[2]
Set to 1 if the present process has read access to the file, 0 otherwise.

array[3]
Set to 1 if the present process has write access to the file, 0 otherwise.

array[4]
Set to 1 if the present process has execute permission to the file, 0 otherwise.

array[5]
Set to the user id of the file owner.

array[6]
Set to the last modification time. This is in a system-encoded form, use TimeToString or TimeToVals to convert.

(int) DeleteFile(path)
Delete the file or directory given in path. If a directory, it must be empty. If the file or directory does not exist or was successfully deleted, 1 is returned, otherwise 0 is returned with an error message available from GetError.

(int) MoveFile(from_path, to_path)
Move (rename) the file from_path to a new file to_path. On success, 1 is returned, otherwise 0 is returned with an error message available from GetError.

Except under Windows, directories can be moved as well, but only within the same file system.

(int) CopyFile(from_path, to_path)
Copy the file from_path to a new file to_path. On success, 1 is returned, otherwise 0 is returned with an error message available from GetError.

(int) CreateBak(path)
If the path file exists, rename it, suffixing the name with a ``.bak'' extension. If a file with this name already exists, it will be overwritten. The function returns 1 if the file was moved or doesn't exist, 0 otherwise, with an error message available from GetError.

(string) Md5Digest(path)
Return a string containing an MD5 digest for the file whose path is passed as the argument. This is the same digest as returned from the !md5 command, and from the command
openssl dgst -md5 filepath
available on many Linux-like systems.

If the file can not be opened, an empty string is returned, and an error message is available from GetError.


next up previous contents index
Next: Socket and Xic Client/Server Up: Main Functions 2 Previous: Date and Time   Contents   Index
Stephen R. Whiteley 2022-05-28