gap-io 4.5.1+ds-1 / usr / share / gap / pkg / io / doc / chap3.txt

  
  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, mkstemp, mkdtemp, 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 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-62)  function  to wait or check for the termination of child processes,
  or call IO_IgnorePid (3.2-63) 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_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_mkstemp
  
  IO_mkstemp( template )  function
  Returns:  an integer or fail
  
  Create a special or ordinary file. For details see man 3 mkstemp.
  
  3.2-40 IO_mkdtemp
  
  IO_mkdtemp( template )  function
  Returns:  a string or fail
  
  Create a temporary directory. For details see man 3 mkdtemp.
  
  3.2-41 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-42 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-43 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-44 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-45 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-46 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-47 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-44)
  function.
  
  3.2-48 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-44)  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-49 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-50 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-42) command has been called.
  
  3.2-51 IO_rmdir
  
  IO_rmdir( name )  function
  Returns:  true or fail
  
  Removes an empty directory. For details see man 2 rmdir.
  
  3.2-52 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-53 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-54 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-55 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-56 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-57 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-58 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-59 IO_symlink
  
  IO_symlink( oldpath, newpath )  function
  Returns:  true or fail
  
  Creates a symbolic link. For details see man 2 symlink.
  
  3.2-60 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-61 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-62 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).  If  you  do  not care about the return value of the process, call
  IO_IgnorePid (3.2-63).
  
  3.2-63 IO_IgnorePid
  
  IO_IgnorePid( pid )  function
  Returns:  Nothing
  
  Disowns  a  child  process.  This  means there is no need to call IO_WaitPid
  (3.2-62).  Calling  IO_WaitPid (3.2-62) on a pid which was previously passed
  to IO_IgnorePid may cause an infinite loop.F
  
  3.2-64 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).