The following functions from the C library are made available as GAP functions:
accept, bind, chdir, chmod, chown, close, closedir, connect, creat, dup, dup2, execv, execve, execvp, exit fchmod, fchown, fcntl, fork, fstat, gethostbyname, getsockopt, lchown, link, listen, lseek, lstat, mkdir, mkfifo, mknod, open, opendir, pipe, read, readdir, readlink, recv, recvfrom, rename, rewinddir, rmdir, seekdir, select, send, sendto, setsockopt, socket, stat, symlink, telldir, unlink, write .
Use the man command in your shell to get information about these functions.
For each of these functions there is a corresponding GAP function in the global record IO bound to its name. Apart from minor differences (see below) they take exactly the same arguments as their C counterparts. Strings must be specified as GAP strings and integers as GAP immediate integers. Return values are in general the same as for the C counterparts. However, an error condition is indicated by the value fail instead of -1, and if the result can only be success or failure, true indicates success.
All errors are reported via the LastSystemError function.
In the C library a lot of integers are defined as macros in header files. All the necessary values for the above functions are bound to their name in the global IO record.
The open function has to be called with three arguments. The version with two arguments is not available on the GAP level.
The read function takes four arguments: fd is an integer file descriptor, st is a GAP string, offset is an offset within this string (zero based), and count is the maximal number of bytes to read. The data is read and stored into the string st, starting at position offset+1. The string st is made long enough, such that count bytes would fit into it, beginning at position offset+1. The number of bytes read is returned or fail in case of an error.
The write function is similar, it also takes four arguments: fd is an integer file descriptor, st is a GAP string, offset is an offset within this string (zero based), and count is the number of bytes to write, starting from position offset+1 in the string st. The number of bytes written is returned, or an fail in case of an error.
The opendir function only returns true or fail.
The readdir function takes no argument. It reads the directory that was specified in the last call to opendir. It just returns a string, which is the name of a file or subdirectory in the corresponding directory. It returns false after the last file name in the directory or fail in case of an error.
The closedir function takes no argument. It should be called after readdir returned false or fail to avoid excessive use of file descriptors.
The functions stat, fstat, and lstat only take one argument and return a GAP record that has the same entries as a struct stat.
The function socket can optionally take a string as third argument. In that case it automatically calls getprotobyname to look up the protocol name.
The functions bind and connect take only one string argument as address field, because the string already encodes the length.
There are two convenience functions IO_make_sockaddr_in (3.3-1) and IO_MakeIPAddressPort (4.3-5) to create such addresses. The first takes two arguments addr and port, where addr is a string of length 4, containing the 4 bytes of the IP address and port is a port number as GAP integer. The function IO_MakeIPAddressPort (4.3-5) takes the same arguments, but the first can be a string containing an IP address in dot notation like "137.226.152.77".
The setsockopt function has no argument optlen. The length of the string optval is taken.
The select function works as the function UNIXSelect in the GAP library.
As of now, the file locking mechanisms of fcntl using struct flock are not yet implemented on the GAP level.
> IO_accept( fd, addr ) | ( function ) |
Accepts an incoming network connection. For details see "man 2 accept". The argument addr can be made with IO_make_sockaddr_in (3.3-1) and contains its length such that no third argument is necessary.
> IO_bind( fd, my_addr ) | ( function ) |
Binds a local address to a socket. For details see "man 2 bind". The argument my_addr can be made with IO_make_sockaddr_in (3.3-1) and contains its length such that no third argument is necessary.
> IO_chdir( path ) | ( function ) |
Changes the current working directory. For details see "man 2 chdir".
> IO_chmod( pathname, mode ) | ( function ) |
Changes the mode of a file. For details see "man 2 chmod".
> IO_chown( path, owner, group ) | ( function ) |
Sets owner and/or group of file. For details see "man 2 chown".
> IO_close( fd ) | ( function ) |
Closes a file descriptor. For details see "man 2 close".
> IO_closedir( ) | ( function ) |
Closes a directory. For details see "man 3 closedir". Has no arguments, because we only have one DIR struct in the C part.
> IO_connect( fd, serv_addr ) | ( function ) |
Connects to a remote socket. For details see "man 2 connect". The argument serv_addr can be made with IO_make_sockaddr_in (3.3-1) and contains its length such that no third argument is necessary.
> IO_creat( pathname, mode ) | ( function ) |
Creates a new file. For details see "man 2 creat".
> IO_dup( oldfd ) | ( function ) |
Duplicates a file descriptor. For details see "man 2 dup".
> IO_dup2( oldfd, newfd ) | ( function ) |
Duplicates a file descriptor to a new one. For details see "man 2 dup2".
> IO_execv( path, argv ) | ( function ) |
Replaces the process with another process. For details see "man 3 execv". The argument argv is a list of strings. The called program does not have to be the first argument in this list.
> IO_execve( path, argv, envp ) | ( function ) |
Replaces the process with another process. For details see "man 3 execve". The arguments argv and envp are both lists of strings. The called program does not have to be the first argument in argv. The list envp can be made with IO_MakeEnvList (4.3-7) from a record acquired from IO_Environment (4.3-6) and modified later.
> IO_execvp( path, argv ) | ( function ) |
Replaces the process with another process. For details see "man 3 execvp". The argument argv is a list of strings. The called program does not have to be the first argument in this list.
> IO_exit( status ) | ( function ) |
Stops process immediately with return code status. For details see "man 2 exit". The argument status must be an integer. Does not return.
> IO_fchmod( fd, mode ) | ( function ) |
Changes mode of an opened file. For details see "man 2 fchmod".
> IO_fchown( fd, owner, group ) | ( function ) |
Changes owner and/or group of an opened file. For details see "man 2 fchown".
> IO_fcntl( fd, cmd, arg ) | ( function ) |
Does various things to control the behaviour of a file descriptor. For details see "man 2 fcntl".
> IO_fork( ) | ( function ) |
Forks off a child process, which is an identical copy. For details see "man 2 fork". Note that if you want to use the IO_WaitPid (3.2-52) function to wait or check for the termination of child processes, you have to activate the SIGCHLD handler for this package beforehand by using the function IO_InstallSIGCHLDHandler (3.3-3). Note further that after that you cannot use the function InputOutputLocalProcess (Reference: InputOutputLocalProcess) any more, since its SIGCHLD handler does not work any more. To switch back to that functionality use the function IO_RestoreSIGCHLDHandler (3.3-4).
> IO_fstat( fd ) | ( function ) |
Returns the file meta data for an opened file. For details see "man 2 fstat". A GAP record is returned with the same entries than a struct stat.
> IO_gethostbyname( name ) | ( function ) |
Return host information by name. For details see "man 3 gethostbyname". A GAP record is returned with all the relevant information about the host.
> IO_getsockopt( fd, level, optname, optval ) | ( function ) |
Get a socket option. For details see "man 2 getsockopt". Note that the argument optval carries its length around, such that no 5th argument is necessary.
> IO_lchown( path, owner, group ) | ( function ) |
Changes owner and/or group of a file not following links. For details see "man 2 lchown".
> IO_link( oldpath, newpath ) | ( function ) |
Create a hard link. For details see "man 2 link".
> IO_listen( fd, backlog ) | ( function ) |
Switch a socket to listening. For details see "man 2 listen".
> IO_lseek( fd, offset, whence ) | ( function ) |
Seeks with in an open file. For details see "man 2 lseek".
> IO_lstat( name ) | ( function ) |
Returns the file meta data for a file not following links. For details see "man 2 lstat". A GAP record is returned with the same entries than a struct stat.
> IO_mkdir( pathname, mode ) | ( function ) |
Creates a directory. For details see "man 2 mkdir".
> IO_mkfifo( pathname, mode ) | ( function ) |
Makes a FIFO special file (a named pipe). For details see "man 3 mkfifo".
> IO_mknod( pathname, mode, dev ) | ( function ) |
Create a special or ordinary file. For details see "man 2 mknod".
> IO_open( pathname, flags, mode ) | ( function ) |
Open and possibly create a file or device. For details see "man 2 open". Only the variant with 3 arguments can be used.
> IO_opendir( name ) | ( function ) |
Opens a directory. For details see "man 3 opendir". Note that only true is returned if everything is OK, since only one DIR struct is stored on the C level and thus only one directory can be open at any time.
> IO_pipe( ) | ( function ) |
Create a pair of file descriptors with a pipe between them. For details see "man 2 pipe". Note that no arguments are needed. The result is either fail in case of an error or a record with two components toread and towrite bound to the two filedescriptors for reading and writing repectively.
> IO_read( fd, st, offset, count ) | ( function ) |
Reads from file descriptor. For details see "man 2 read". Note that there is one more argument offset to specify at which position in the string st the read data should be stored. Note that offset zero means at the beginning of the string, which is position 1 in GAP.
> IO_readdir( ) | ( function ) |
Reads from a directory. For details see "man 2 readdir". Note that no argument is required as we have only one DIR struct on the C level.
> IO_readlink( path, buf, bufsize ) | ( function ) |
Reads the value of a symbolic link. For details see "man 2 readlink".
> IO_recv( fd, st, offset, len, flags ) | ( function ) |
Receives data from a socket. For details see "man 2 recv". Note the additional argument offset which plays the same role as for the IO_read (3.2-34) function.
> IO_recvfrom( fd, st, offset, len, flags, addr ) | ( function ) |
Receives data from a socket with given address. For details see "man 2 recvfrom". Note the additional argument offset which plays the same role as for the IO_read (3.2-34) function. The argument addr can be made with IO_make_sockaddr_in (3.3-1) and contains its length such that no 7th argument is necessary.
> IO_rename( oldpath, newpath ) | ( function ) |
Renames a file or moves it. For details see "man 2 rename".
> IO_rewinddir( ) | ( function ) |
Rewinds a directory. For details see "man 2 rewinddir". Note that no argument is required as we have only one DIR struct on the C level.
> IO_rmdir( name ) | ( function ) |
Removes an empty directory. For details see "man 2 rmdir".
> IO_seekdir( offset ) | ( function ) |
Sets the position of the next readdir call. For details see "man 3 seekdir". Note that no second argument is required as we have only one DIR struct on the C level.
> IO_select( inlist, outlist, exclist, timeoutsec, timeoutusec ) | ( function ) |
Used for I/O multiplexing. For details see "man 2 select". inlist, outlist and exclist are lists of filedescriptors, which are modified. If the corresponding file descriptor is not yet ready, it is replaced by fail.
> IO_send( fd, st, offset, len, flags ) | ( function ) |
Sends data to a socket. For details see "man 2 send". Note that the additional argument offset specifies the position of the data to send within the string st. It is zero based, meaning that zero indicates the start of the string, which is position 1 in GAP.
> IO_sendto( fd, st, offset, len, flags, addr ) | ( function ) |
Sends data to a socket. For details see "man 2 sendto". Note that the additional argument offset specifies the position of the data to send within the string st. It is zero based, meaning that zero indicates the start of the string, which is position 1 in GAP. The argument addr can be made with IO_make_sockaddr_in (3.3-1) and contains its length such that no 7th argument is necessary.
> IO_setsockopt( fd, level, optname, optval ) | ( function ) |
Sets a socket option. For details see "man 2 setsockopt". Note that the argument optval carries its length around, such that no 5th argument is necessary.
> IO_socket( domain, type, protocol ) | ( function ) |
Creates a socket, an endpoint for communication. For details see "man 2 socket". There is one little special: On systems that have getprotobyname you can pass a string as third argument protocol which is automatically looked up by getprotobyname.
> IO_stat( pathname ) | ( function ) |
Returns the file metadata for the file pathname. For details see "man 2 stat". A GAP record is returned with the same entries than a struct stat.
> IO_symlink( oldpath, newpath ) | ( function ) |
Creates a symbolic link. For details see "man 2 symlink".
> IO_telldir( ) | ( function ) |
Return current location in directory. For details see "man 3 telldir". Note that no second argument is required as we have only one DIR struct on the C level.
> IO_unlink( pathname ) | ( function ) |
Delete a name and possibly the file it refers to. For details see "man 2 unlink".
> IO_WaitPid( pid, wait ) | ( function ) |
Waits for the termination of a child process. For details see "man 2 waitpid". Returns a GAP record describing PID and exit status. The second argument wait must be either true or false. In the first case, the call blocks until new information about a terminated child process is available. In the second case no such waiting is performed, the call returns immediately. See IO_fork (3.2-19).
> IO_write( fd, st, offset, count ) | ( function ) |
Writes to a file descriptor. For details see "man 2 write". Note that the additional argument offset specifies the position of the data to send within the string st. It is zero based, meaning that zero indicates the start of the string, which is position 1 in GAP.
The following functions do not correspond to functions in the C library, but are there to provide convenience to use other functions:
> IO_make_sockaddr_in( ip, port ) | ( function ) |
Makes a struct sockaddr_in from IP address and port. The IP address must be given as a string of length four, containing the four bytes of an IPv4 address in natural order. The port must be a port number. Returns a string containing the struct, which can be given to all functions above having an address argument.
> IO_environ( ) | ( function ) |
For details see "man environ". Returns the current environment as a list of strings of the form "key=value".
> IO_InstallSIGCHLDHandler( ) | ( function ) |
Installs our SIGCHLD handler. See IO_fork (3.2-19).
> IO_RestoreSIGCHLDHandler( ) | ( function ) |
Restores the original SIGCHLD handler. See IO_fork (3.2-19).
generated by GAPDoc2HTML