GAP (IO) - Chapter 3: Functions directly available from the C library

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

[MathJax off]

3 Functions directly available from the C library
3.1 Differences in arguments - an overview
3.2 The low-level functions in detail
3.2-1 IO_accept
3.2-2 IO_bind
3.2-3 IO_chdir
3.2-4 IO_chmod
3.2-5 IO_chown
3.2-6 IO_close
3.2-7 IO_closedir
3.2-8 IO_connect
3.2-9 IO_creat
3.2-10 IO_dup
3.2-11 IO_dup2
3.2-12 IO_execv
3.2-13 IO_execve
3.2-14 IO_execvp
3.2-15 IO_exit
3.2-16 IO_fchmod
3.2-17 IO_fchown
3.2-18 IO_fcntl
3.2-19 IO_fork
3.2-20 IO_fstat
3.2-21 IO_gethostbyname
3.2-22 IO_gethostname
3.2-23 IO_getpid
3.2-24 IO_getppid
3.2-25 IO_getsockname
3.2-26 IO_getsockopt
3.2-27 IO_gettimeofday
3.2-28 IO_gmtime
3.2-29 IO_kill
3.2-30 IO_lchown
3.2-31 IO_link
3.2-32 IO_listen
3.2-33 IO_localtime
3.2-34 IO_lseek
3.2-35 IO_lstat
3.2-36 IO_mkdir
3.2-37 IO_mkfifo
3.2-38 IO_mknod
3.2-39 IO_open
3.2-40 IO_opendir
3.2-41 IO_pipe
3.2-42 IO_read
3.2-43 IO_readdir
3.2-44 IO_readlink
3.2-45 IO_recv
3.2-46 IO_recvfrom
3.2-47 IO_rename
3.2-48 IO_rewinddir
3.2-49 IO_rmdir
3.2-50 IO_seekdir
3.2-51 IO_select
3.2-52 IO_send
3.2-53 IO_sendto
3.2-54 IO_setsockopt
3.2-55 IO_socket
3.2-56 IO_stat
3.2-57 IO_symlink
3.2-58 IO_telldir
3.2-59 IO_unlink
3.2-60 IO_WaitPid
3.2-61 IO_write
3.3 Further C level functions
3.3-1 IO_make_sockaddr_in
3.3-2 IO_environ
3.3-3 IO_InstallSIGCHLDHandler
3.3-4 IO_RestoreSIGCHLDHandler

### 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`, `gethostbyname`, `gethostname`, `getpid`, `getppid`, `getsockname`, `getsockopt`, `gettimeofday`, `gmtime`, `kill`, `lchown`, `link`, `listen`, `localtime`, `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 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 \(\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.

#### 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 if you want to use the `IO_WaitPid` (3.2-60) 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).

##### 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_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-22 IO_gethostname

`‣ IO_gethostname`( ) | ( function )

Returns: a string or `fail`

Return host name. For details see "`man 3 gethostname`".

##### 3.2-23 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-24 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-25 IO_getsockname

`‣ IO_getsockname`( fd ) | ( function )

Returns: a string or `fail`

Get a socket name. For details see "`man 2 getsockname`".

##### 3.2-26 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-27 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-28 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-29 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-30 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-31 IO_link

`‣ IO_link`( oldpath, newpath ) | ( function )

Returns: `true` or `false`

Create a hard link. For details see "`man 2 link`".

##### 3.2-32 IO_listen

`‣ IO_listen`( fd, backlog ) | ( function )

Returns: `true` or `false`

Switch a socket to listening. For details see "`man 2 listen`".

##### 3.2-33 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-34 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-35 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-36 IO_mkdir

`‣ IO_mkdir`( pathname, mode ) | ( function )

Returns: `true` or `false`

Creates a directory. For details see "`man 2 mkdir`".

##### 3.2-37 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-38 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-39 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-40 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-41 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-42 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-43 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-44 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-45 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-42) function.

##### 3.2-46 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-42) 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-47 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-48 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-40) command has been called.

##### 3.2-49 IO_rmdir

`‣ IO_rmdir`( name ) | ( function )

Returns: `true` or `fail`

Removes an empty directory. For details see "`man 2 rmdir`".

##### 3.2-50 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-51 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-52 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-53 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-54 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-55 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-56 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-57 IO_symlink

`‣ IO_symlink`( oldpath, newpath ) | ( function )

Returns: `true` or `fail`

Creates a symbolic link. For details see "`man 2 symlink`".

##### 3.2-58 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-59 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-60 IO_WaitPid

`‣ IO_WaitPid`( pid, wait ) | ( function )

Returns: a record or `fail`

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

##### 3.2-61 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. 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