3 Functions directly available from the C library 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. 3.1 Differences in arguments - an overview 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 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. 3.2 The low-level functions in detail 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. 3.2-1 IO_accept IO_accept( fd, addr )  function Returns: an integer or fail 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. 3.2-2 IO_bind IO_bind( fd, my_addr )  function Returns: an integer or fail 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. 3.2-3 IO_chdir IO_chdir( path )  function Returns: true or fail Changes the current working directory. For details see man 2 chdir. 3.2-4 IO_chmod IO_chmod( pathname, mode )  function Returns: true or fail Changes the mode of a file. For details see man 2 chmod. 3.2-5 IO_chown IO_chown( path, owner, group )  function Returns: true or fail Sets owner and/or group of file. For details see man 2 chown. 3.2-6 IO_close IO_close( fd )  function Returns: true or fail Closes a file descriptor. For details see man 2 close. 3.2-7 IO_closedir IO_closedir( )  function Returns: true or fail Closes a directory. For details see man 3 closedir. Has no arguments, because we only have one DIR struct in the C part. 3.2-8 IO_connect IO_connect( fd, serv_addr )  function Returns: true or fail 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. 3.2-9 IO_creat IO_creat( pathname, mode )  function Returns: an integer or fail Creates a new file. For details see man 2 creat. 3.2-10 IO_dup IO_dup( oldfd )  function Returns: an integer or fail Duplicates a file descriptor. For details see man 2 dup. 3.2-11 IO_dup2 IO_dup2( oldfd, newfd )  function Returns: true or fail Duplicates a file descriptor to a new one. For details see man 2 dup2. 3.2-12 IO_execv IO_execv( path, argv )  function Returns: fail or does not return 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. 3.2-13 IO_execve IO_execve( path, argv, envp )  function Returns: fail or does not return 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-8) from a record acquired from IO_Environment (4.3-7) and modified later. 3.2-14 IO_execvp IO_execvp( path, argv )  function Returns: fail or does not return 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. 3.2-15 IO_exit 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. 3.2-16 IO_fchmod IO_fchmod( fd, mode )  function Returns: true or fail Changes mode of an opened file. For details see man 2 fchmod. 3.2-17 IO_fchown 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. 3.2-18 IO_fcntl 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. 3.2-19 IO_fork IO_fork( )  function Returns: an integer or fail Forks off a child process, which is an identical copy. For details see man 2 fork. Note that IO_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. 3.2-20 IO_fstat IO_fstat( fd )  function Returns: a record or fail 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. 3.2-21 IO_getcwd IO_getcwd( )  function Returns: a string or fail Returns the current working directory. For details see man 3 getcwd. 3.2-22 IO_getenv 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. 3.2-23 IO_gethostbyname IO_gethostbyname( name )  function Returns: a record or fail Return host information by name. For details see man 3 gethostbyname. A GAP record is returned with all the relevant information about the host. 3.2-24 IO_gethostname IO_gethostname( )  function Returns: a string or fail Return host name. For details see man 3 gethostname. 3.2-25 IO_getpid IO_getpid( )  function Returns: an integer Returns the process ID of the current process as an integer. For details see man 2 getpid. 3.2-26 IO_getppid 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. 3.2-27 IO_getsockname IO_getsockname( fd )  function Returns: a string or fail Get a socket name. For details see man 2 getsockname. 3.2-28 IO_getsockopt IO_getsockopt( fd, level, optname, optval )  function Returns: true or false 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. 3.2-29 IO_gettimeofday 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. 3.2-30 IO_gmtime 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. 3.2-31 IO_kill IO_kill( pid, sig )  function Returns: true or fail Sends the signal sig to the process with process ID pid. For details see man 2 kill. The signal numbers available can be found in the global IO record with names like SIGTERM. 3.2-32 IO_lchown 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. 3.2-33 IO_link IO_link( oldpath, newpath )  function Returns: true or false Create a hard link. For details see man 2 link. 3.2-34 IO_listen IO_listen( fd, backlog )  function Returns: true or false Switch a socket to listening. For details see man 2 listen. 3.2-35 IO_localtime 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. 3.2-36 IO_lseek IO_lseek( fd, offset, whence )  function Returns: an integer or fail Seeks within an open file. For details see man 2 lseek. 3.2-37 IO_lstat IO_lstat( name )  function Returns: a record or fail 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. 3.2-38 IO_mkdir IO_mkdir( pathname, mode )  function Returns: true or false Creates a directory. For details see man 2 mkdir. 3.2-39 IO_mkfifo IO_mkfifo( pathname, mode )  function Returns: true or false Creates a FIFO special file (a named pipe). For details see man 3 mkfifo. 3.2-40 IO_mknod IO_mknod( pathname, mode, dev )  function Returns: true or false Create a special or ordinary file. For details see man 2 mknod. 3.2-41 IO_mkstemp IO_mkstemp( template )  function Returns: an integer or fail Create a special or ordinary file. For details see man 3 mkstemp. 3.2-42 IO_mkdtemp IO_mkdtemp( template )  function Returns: a string or fail Create a temporary directory. For details see man 3 mkdtemp. 3.2-43 IO_open IO_open( pathname, flags, mode )  function Returns: an integer or fail Open and possibly create a file or device. For details see man 2 open. Only the variant with 3 arguments can be used. 3.2-44 IO_opendir IO_opendir( name )  function Returns: true or false 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. 3.2-45 IO_pipe IO_pipe( )  function Returns: a record or fail 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 respectively. 3.2-46 IO_read IO_read( fd, st, offset, count )  function Returns: an integer or fail 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. The number of bytes read or fail in case of an error is returned. 3.2-47 IO_readdir IO_readdir( )  function Returns: a string or fail or false 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. If the directory is read completely false is returned, and otherwise a string. An error is indicated by fail. 3.2-48 IO_readlink IO_readlink( path, buf, bufsize )  function Returns: an integer or fail Reads the value of a symbolic link. For details see man 2 readlink. buf is modified. The new length of buf is returned or fail in case of an error. 3.2-49 IO_recv IO_recv( fd, st, offset, len, flags )  function Returns: an integer or fail 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-46) function. 3.2-50 IO_recvfrom 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 man 2 recvfrom. Note the additional argument offset which plays the same role as for the IO_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. 3.2-51 IO_rename IO_rename( oldpath, newpath )  function Returns: true or false Renames a file or moves it. For details see man 2 rename. 3.2-52 IO_rewinddir IO_rewinddir( )  function Returns: true or fail 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. Returns fail only, if no prior IO_opendir (3.2-44) command has been called. 3.2-53 IO_rmdir IO_rmdir( name )  function Returns: true or fail Removes an empty directory. For details see man 2 rmdir. 3.2-54 IO_seekdir IO_seekdir( offset )  function Returns: true or fail 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. 3.2-55 IO_select IO_select( inlist, outlist, exclist, timeoutsec, timeoutusec )  function Returns: an integer or fail 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. 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. 3.2-56 IO_send IO_send( fd, st, offset, len, flags )  function Returns: an integer or fail 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. 3.2-57 IO_sendto IO_sendto( fd, st, offset, len, flags, addr )  function Returns: an integer or fail 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. 3.2-58 IO_setenv 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. 3.2-59 IO_setsockopt IO_setsockopt( fd, level, optname, optval )  function Returns: true or fail 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. 3.2-60 IO_socket IO_socket( domain, type, protocol )  function Returns: an integer or fail 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. 3.2-61 IO_stat IO_stat( pathname )  function Returns: a record or fail 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. 3.2-62 IO_symlink IO_symlink( oldpath, newpath )  function Returns: true or fail Creates a symbolic link. For details see man 2 symlink. 3.2-63 IO_telldir IO_telldir( )  function Returns: an integer or fail 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. 3.2-64 IO_unlink IO_unlink( pathname )  function Returns: true or fail Delete a name and possibly the file it refers to. For details see man 2 unlink. 3.2-65 IO_unsetenv IO_unsetenv( name )  function Returns: true or fail Remove the environment variable name. For details see man 3 unsetenv. 3.2-66 IO_WaitPid IO_WaitPid( pid, wait )  function Returns: a record or fail or false Waits for the termination of a child process. For details see man 2 waitpid. The first argument must be a process id, otherwise the function immediately exits with fail 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). 3.2-67 IO_IgnorePid 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 3.2-68 IO_write IO_write( fd, st, offset, count )  function Returns: an integer or fail 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. 3.3 Further C level functions The following functions do not correspond to functions in the C library, but are there to provide convenience to use other functions: 3.3-1 IO_make_sockaddr_in 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. 3.3-2 IO_environ IO_environ( )  function Returns: a list of strings For details see man environ. Returns the current environment as a list of strings of the form key=value. 3.3-3 IO_InstallSIGCHLDHandler 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). 3.3-4 IO_RestoreSIGCHLDHandler 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).