Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 Ind
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 

3 Functions directly available from the C library
 3.1 Differences in arguments - an overview
 3.2 The low-level functions in detail
 3.3 Further C level functions

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).

 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 Ind

generated by GAPDoc2HTML