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, getcwd, getenv, gethostbyname, gethostname, getpid, getppid, getsockname, getsockopt, gettimeofday, gmtime, kill, lchown, link, listen, localtime, lseek, lstat, mkdir, mkfifo, mknod, mkstemp, mkdtemp, open, opendir, pipe, read, readdir, readlink, recv, recvfrom, rename, rewinddir, rmdir, seekdir, select, send, sendto, setenv, setsockopt, socket, stat, symlink, telldir, unlink, unsetenv, write.
Use the man command in your shell to get information about these functions.
For each of these functions there is a corresponding GAP global function with the prefix IO_ before 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 (Reference: 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.
Warning: Existence of many of these functions and constants is platform dependent. The compilation process checks existence and this leads to the situation that on the GAP levels the functions and constants are there or not. If you want to develop platform independent GAP code using this package, then you have to check for existence of the functions and constants you need.
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 \(\textit{offset}+1\). The string st is made long enough, such that count bytes would fit into it, beginning at position \(\textit{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 \(\textit{offset}+1\) in the string st. The number of bytes written is returned, or a 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-6) 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-6) takes the same arguments, but the first can be a string containing an IP address in dot notation like 137.226.152.77
or a hostname to be looked up.
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.
Nearly all of this functions return an integer result in the C library. On the GAP level this is either returned as a non-negative integer in case of success or as fail in case of an error (where on the C level \(-1\) would be returned). If the integer can only be \(0\) for no error
this is changed to true on the GAP level.
‣ IO_accept( fd, addr ) | ( function ) |
Returns: an integer or fail
Accepts an incoming network connection. For details see
. The argument addr can be made with man 2 acceptIO_make_sockaddr_in (3.3-1) and contains its length such that no third argument is necessary.
‣ IO_bind( fd, my_addr ) | ( function ) |
Returns: an integer or fail
Binds a local address to a socket. For details see
. The argument my_addr can be made with man 2 bindIO_make_sockaddr_in (3.3-1) and contains its length such that no third argument is necessary.
‣ IO_chdir( path ) | ( function ) |
Returns: true or fail
Changes the current working directory. For details see
.man 2 chdir
‣ IO_chmod( pathname, mode ) | ( function ) |
Returns: true or fail
Changes the mode of a file. For details see
.man 2 chmod
‣ IO_chown( path, owner, group ) | ( function ) |
Returns: true or fail
Sets owner and/or group of file. For details see
.man 2 chown
‣ IO_close( fd ) | ( function ) |
Returns: true or fail
Closes a file descriptor. For details see
.man 2 close
‣ IO_closedir( ) | ( function ) |
Returns: true or fail
Closes a directory. For details see
. Has no arguments, because we only have one man 3 closedirDIR struct in the C part.
‣ IO_connect( fd, serv_addr ) | ( function ) |
Returns: true or fail
Connects to a remote socket. For details see
. The argument serv_addr can be made with man 2 connectIO_make_sockaddr_in (3.3-1) and contains its length such that no third argument is necessary.
‣ IO_creat( pathname, mode ) | ( function ) |
Returns: an integer or fail
Creates a new file. For details see
.man 2 creat
‣ IO_dup( oldfd ) | ( function ) |
Returns: an integer or fail
Duplicates a file descriptor. For details see
.man 2 dup
‣ IO_dup2( oldfd, newfd ) | ( function ) |
Returns: true or fail
Duplicates a file descriptor to a new one. For details see
.man 2 dup2
‣ IO_execv( path, argv ) | ( function ) |
Returns: fail or does not return
Replaces the process with another process. For details see
. The argument argv is a list of strings. The called program does not have to be the first argument in this list.man 3 execv
‣ IO_execve( path, argv, envp ) | ( function ) |
Returns: fail or does not return
Replaces the process with another process. For details see
. 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 man 3 execveIO_MakeEnvList (4.3-8) from a record acquired from IO_Environment (4.3-7) and modified later.
‣ IO_execvp( path, argv ) | ( function ) |
Returns: fail or does not return
Replaces the process with another process. For details see
. The argument argv is a list of strings. The called program does not have to be the first argument in this list.man 3 execvp
‣ IO_exit( status ) | ( function ) |
Stops process immediately with return code status. For details see
. The argument status must be an integer. Does not return.man 2 exit
‣ IO_fchmod( fd, mode ) | ( function ) |
Returns: true or fail
Changes mode of an opened file. For details see
.man 2 fchmod
‣ IO_fchown( fd, owner, group ) | ( function ) |
Returns: true or fail
Changes owner and/or group of an opened file. For details see
.man 2 fchown
‣ IO_fcntl( fd, cmd, arg ) | ( function ) |
Returns: an integer or fail
Does various things to control the behaviour of a file descriptor. For details see
.man 2 fcntl
‣ IO_fork( ) | ( function ) |
Returns: an integer or fail
Forks off a child process, which is an identical copy. For details see
. Note that man 2 forkIO_fork activates our SIGCHLD handler (see IO_InstallSIGCHLDHandler (3.3-3)). Note that you must use the IO_WaitPid (3.2-66) function to wait or check for the termination of child processes, or call IO_IgnorePid (3.2-67) to ignore the child.
‣ IO_fstat( fd ) | ( function ) |
Returns: a record or fail
Returns the file meta data for an opened file. For details see
. A GAP record is returned with the same entries than a man 2 fstatstruct stat.
‣ IO_getcwd( ) | ( function ) |
Returns: a string or fail
Returns the current working directory. For details see
.man 3 getcwd
‣ IO_getenv( name ) | ( function ) |
Returns: a string or fail
Return the current value of the environment variable name. If the variable is not in the current environment, fail is returned. For details see
.man 3 getenv
‣ IO_gethostbyname( name ) | ( function ) |
Returns: a record or fail
Return host information by name. For details see
. A GAP record is returned with all the relevant information about the host.man 3 gethostbyname
‣ IO_gethostname( ) | ( function ) |
Returns: a string or fail
Return host name. For details see
.man 3 gethostname
‣ IO_getpid( ) | ( function ) |
Returns: an integer
Returns the process ID of the current process as an integer. For details see
.man 2 getpid
‣ IO_getppid( ) | ( function ) |
Returns: an integer
Returns the process ID of the parent of the current process as an integer. For details see
.man 2 getppid
‣ IO_getsockname( fd ) | ( function ) |
Returns: a string or fail
Get a socket name. For details see
.man 2 getsockname
‣ IO_getsockopt( fd, level, optname, optval ) | ( function ) |
Returns: true or false
Get a socket option. For details see
. Note that the argument optval carries its length around, such that no 5th argument is necessary.man 2 getsockopt
‣ IO_gettimeofday( ) | ( function ) |
Returns: A record with components tv_sec and tv_usec
This returns the time elapsed since 1.1.1970, 0:00 GMT. The component tv_sec contains the number of full seconds and the number tv_usec the additional microseconds.
‣ IO_gmtime( seconds ) | ( function ) |
Returns: A record
The argument is the number of seconds that have elapsed since 1.1.1970, 0:00 GMT. The result is a record with the current Greenwich mean time broken down into date and time as in the C-library function gmtime.
‣ IO_kill( pid, sig ) | ( function ) |
Returns: true or fail
Sends the signal sig to the process with process ID pid. For details see
. The signal numbers available can be found in the global man 2 killIO record with names like SIGTERM.
‣ IO_lchown( path, owner, group ) | ( function ) |
Returns: true or false
Changes owner and/or group of a file not following links. For details see
.man 2 lchown
‣ IO_link( oldpath, newpath ) | ( function ) |
Returns: true or false
Create a hard link. For details see
.man 2 link
‣ IO_listen( fd, backlog ) | ( function ) |
Returns: true or false
Switch a socket to listening. For details see
.man 2 listen
‣ IO_localtime( seconds ) | ( function ) |
Returns: A record
The argument is the number of seconds that have elapsed since 1.1.1970, 0:00 GMT. The result is a record with the current local time broken down into date and time as in the C-library function localtime.
‣ IO_lseek( fd, offset, whence ) | ( function ) |
Returns: an integer or fail
Seeks within an open file. For details see
.man 2 lseek
‣ IO_lstat( name ) | ( function ) |
Returns: a record or fail
Returns the file meta data for a file not following links. For details see
. A GAP record is returned with the same entries than a man 2 lstatstruct stat.
‣ IO_mkdir( pathname, mode ) | ( function ) |
Returns: true or false
Creates a directory. For details see
.man 2 mkdir
‣ IO_mkfifo( pathname, mode ) | ( function ) |
Returns: true or false
Creates a FIFO special file (a named pipe). For details see
.man 3 mkfifo
‣ IO_mknod( pathname, mode, dev ) | ( function ) |
Returns: true or false
Create a special or ordinary file. For details see
.man 2 mknod
‣ IO_mkstemp( template ) | ( function ) |
Returns: an integer or fail
Create a special or ordinary file. For details see
.man 3 mkstemp
‣ IO_mkdtemp( template ) | ( function ) |
Returns: a string or fail
Create a temporary directory. For details see
.man 3 mkdtemp
‣ IO_open( pathname, flags, mode ) | ( function ) |
Returns: an integer or fail
Open and possibly create a file or device. For details see
. Only the variant with 3 arguments can be used.man 2 open
‣ IO_opendir( name ) | ( function ) |
Returns: true or false
Opens a directory. For details see
. Note that only man 3 opendirtrue 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 ) |
Returns: a record or fail
Create a pair of file descriptors with a pipe between them. For details see
. Note that no arguments are needed. The result is either man 2 pipefail in case of an error or a record with two components toread and towrite bound to the two filedescriptors for reading and writing respectively.
‣ IO_read( fd, st, offset, count ) | ( function ) |
Returns: an integer or fail
Reads from file descriptor. For details see
. 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. The number of bytes read or man 2 readfail in case of an error is returned.
‣ IO_readdir( ) | ( function ) |
Returns: a string or fail or false
Reads from a directory. For details see
. Note that no argument is required as we have only one man 2 readdirDIR struct on the C level. If the directory is read completely false is returned, and otherwise a string. An error is indicated by fail.
‣ IO_readlink( path, buf, bufsize ) | ( function ) |
Returns: an integer or fail
Reads the value of a symbolic link. For details see
. buf is modified. The new length of buf is returned or man 2 readlinkfail in case of an error.
‣ IO_recv( fd, st, offset, len, flags ) | ( function ) |
Returns: an integer or fail
Receives data from a socket. For details see
. Note the additional argument offset which plays the same role as for the man 2 recvIO_read (3.2-46) function.
‣ IO_recvfrom( fd, st, offset, len, flags, addr ) | ( function ) |
Returns: an integer or fail
Receives data from a socket with given address. For details see
. Note the additional argument offset which plays the same role as for the man 2 recvfromIO_read (3.2-46) 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 ) |
Returns: true or false
Renames a file or moves it. For details see
.man 2 rename
‣ IO_rewinddir( ) | ( function ) |
Returns: true or fail
Rewinds a directory. For details see
. Note that no argument is required as we have only one man 2 rewinddirDIR struct on the C level. Returns fail only, if no prior IO_opendir (3.2-44) command has been called.
‣ IO_rmdir( name ) | ( function ) |
Returns: true or fail
Removes an empty directory. For details see
.man 2 rmdir
‣ IO_seekdir( offset ) | ( function ) |
Returns: true or fail
Sets the position of the next readdir call. For details see
. Note that no second argument is required as we have only one man 3 seekdirDIR struct on the C level.
‣ IO_select( inlist, outlist, exclist, timeoutsec, timeoutusec ) | ( function ) |
Returns: an integer or fail
Used for I/O multiplexing. For details see
. inlist, outlist and exclist are lists of filedescriptors, which are modified. If the corresponding file descriptor is not yet ready, it is replaced by man 2 selectfail. The timeout values timeoutsec and timeoutusec correspond to the usual arguments of select, if both are immediate integers, they are set, otherwise select is called with no timeout value.
‣ IO_send( fd, st, offset, len, flags ) | ( function ) |
Returns: an integer or fail
Sends data to a socket. For details see
. 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.man 2 send
‣ IO_sendto( fd, st, offset, len, flags, addr ) | ( function ) |
Returns: an integer or fail
Sends data to a socket. For details see
. 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 man 2 sendtoIO_make_sockaddr_in (3.3-1) and contains its length such that no 7th argument is necessary.
‣ IO_setenv( name, value, overvwrite ) | ( function ) |
Returns: true or fail
Set the current value of the environment variable name to value if it has either not been set before, or overwrite is true. For details see
.man 3 setenv
‣ IO_setsockopt( fd, level, optname, optval ) | ( function ) |
Returns: true or fail
Sets a socket option. For details see
. Note that the argument optval carries its length around, such that no 5th argument is necessary.man 2 setsockopt
‣ IO_socket( domain, type, protocol ) | ( function ) |
Returns: an integer or fail
Creates a socket, an endpoint for communication. For details see
. There is one little special: On systems that have man 2 socketgetprotobyname you can pass a string as third argument protocol which is automatically looked up by getprotobyname.
‣ IO_stat( pathname ) | ( function ) |
Returns: a record or fail
Returns the file metadata for the file pathname. For details see
. A GAP record is returned with the same entries than a man 2 statstruct stat.
‣ IO_symlink( oldpath, newpath ) | ( function ) |
Returns: true or fail
Creates a symbolic link. For details see
.man 2 symlink
‣ IO_telldir( ) | ( function ) |
Returns: an integer or fail
Return current location in directory. For details see
. Note that no second argument is required as we have only one man 3 telldirDIR struct on the C level.
‣ IO_unlink( pathname ) | ( function ) |
Returns: true or fail
Delete a name and possibly the file it refers to. For details see
.man 2 unlink
‣ IO_unsetenv( name ) | ( function ) |
Returns: true or fail
Remove the environment variable name. For details see
.man 3 unsetenv
‣ IO_WaitPid( pid, wait ) | ( function ) |
Returns: a record or fail or false
Waits for the termination of a child process. For details see
. The first argument must be a process id, otherwise the function immediately exits with man 2 waitpidfail as return value.
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. If the child process has not yet terminated, returns false; otherwise, returns a GAP record describing the PID, the return value of waitpid, if the process exited normally and the exit status of the process.
See IO_fork (3.2-19). If you do not care about the return value of the process, call IO_IgnorePid (3.2-67).
‣ IO_IgnorePid( pid ) | ( function ) |
Returns: Nothing
Disowns a child process. This means there is no need to call IO_WaitPid (3.2-66). Calling IO_WaitPid (3.2-66) on a pid which was previously passed to IO_IgnorePid may cause an infinite loop.F
‣ IO_write( fd, st, offset, count ) | ( function ) |
Returns: an integer or fail
Writes to a file descriptor. For details see
. 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.man 2 write
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 ) |
Returns: a string or fail
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 ) |
Returns: a list of strings
For details see
. Returns the current environment as a list of strings of the form man environkey=value
.
‣ IO_InstallSIGCHLDHandler( ) | ( function ) |
Returns: true or false
Installs our SIGCHLD handler. This functions works as an idempotent. That is, calling it twice does exactly the same as calling it once. It returns true when it is called for the first time since then a pointer to the old signal handler is stored in a global variable. This function is automatically called by any function which creates new processes, so never needs to be called unless the handler was explictly disabled with IO_RestoreSIGCHLDHandler (3.3-4) See IO_fork (3.2-19).
‣ IO_RestoreSIGCHLDHandler( ) | ( function ) |
Restores the original SIGCHLD handler. This function works as an idempotent. That is, calling it twice does exactly the same as calling it once. It returns true when it is called for the first time after calling IO_InstallSIGCHLDHandler (3.3-3). See IO_fork (3.2-19).
generated by GAPDoc2HTML