Goonix is a posix-compliant (John S. Quarterman and Susanne Willhelm: "UNIX, POSIX, and Open Systems", Addison-Wesley Publishing Co, Inc. 1993) library for systems programming in scheme. It allows the scheme programmer to use the same calls available to C programmers in a posix environment.
This chapter is written assuming that you are running the guile program directly. If you are writing a C program instead, and linking with libguile, you can follow the instructions in section Libguile reference to initialize goonix correctly, and then follow this section when you write scheme code.
Unlike the Tk package, no special scheme code is required to initialize goonix: all goonix procedures are primitive, and available as long as goonix has been initialized with the correct libguile calls.
When documenting the procedures in this chapter, I use the convention [arg] to indicate that the argument is optional, and [args ...] to indicate that the optional argument can be repeated.
You will notice that most of these procedures closely mirror the equivalent UNIX system or library calls. If you want to know more detail about how these procedures behave, you can read the relevant UNIX man page.
You will also notice that many of these procedures begin with a %
character. There is a convention in goonix that puts a % in front
of all procedures that might invoke the scheme (error ...)
mechanism, thus escaping from the current continuation.
These I/O Extensions to scheme provide many of the UNIX file
system calls, thus allowing sophisticated file manipulation and
directory traversal. This is mostly done using UNIX's stdio
layer, rather than the raw open, read, write layer.
Standard I/O file pointers are directly translated to scheme ports. Ports are described in great detail in all the scheme references (see section `Where to find more Guile/scheme resources' in Guile User Manual), so I will simply remind you that an input port is a scheme object which can deliver characters, and an output port is a scheme object which can accept characters. It is OK to think of ports as file pointers, even though there are some subtelties in ports related to scheme's unique control structure.
In the following read/write routines, if port is omitted, standard input (or standard output) is assumed.
%readdir and closedir.
umask to be the specified value mask-value.
The new setting is returned. If no mask-value is given,
umask will return the current setting.
Notice that the UNIX umask command interprets the
mask-value to be an octal integer, whereas the goonix umask
call does not make any such conversion, so you have to explicitly tell
scheme to use an octal radix, or think about permissions in decimal!
mv command and the rename system
call.
#f is returned.
#t if the port is associated with a terminal device, and
#f otherwise.
r open for reading
w truncate or create for writing
a append: open for writing at end of file, or
create for writing
r+ open for update (reading and writing)
w+ truncate or create for update
a+ append; open or create for update at EOF
Returns #f for error, 0 if the file descriptor is already equal
to fd, and 1 if the file descriptor is successfully moved.
R_OK test for read permission
W_OK test for write permission
X_OK test for execute or search permission
The following value may also be supplied for mode:
F_OK test whether the directories leading to
the file can be searched and the file
exists.
stat
structure values are stored in the following order: #(st_dev
st_ino st_mode st_nlink st_uid st_gid st_rdev st_size st_atime st_mtime
st_ctime st_blksize st_blocks)
"VARIABLE=value" and adds
that to the user's environment.
car and the write port in its cdr. If the pipe
creation fails, %pipe returns #f.
"w") or read from it (if mode is "r").
(open-pipe pipe-str "r").
(open-pipe pipe-str "w").
%getpwuid returns a
vector with the following data: #(login-name password uid gid
GEGOS home-dir shell).
If name is not specified, the first entry in the password file is returned (or the next entry, upon successive invocations).
setpwent rewinds the password file so
the next call to %getpwuid will start from the beginning.
Without arguments, setpwent will close the password file; it can
be used when processing is complete.
%getgrgid returns the group file entry for that group. If
which-group is not given, the first entry in the group file is
returned (or the next entry, upon successive invocations).
setpwent, but for the group file.
If called with an argument, setgrent rewinds the group file so
the next call to %getgrgid will start from the beginning.
Without arguments, setgrent will close the group file; it can be
used when processing is complete.
kill system call, not
the order of the kill command usually typed at the shell.
If pid is -1, %waitpid will wait on any of its children.
This is equivalent to the traditional UNIX wait system call.
If pid is greater than 0, %waitpid will wait on that
particular child process.
If pid is equal to 0, %waitpid will wait on any children in
its own process group.
If pid is less than -1, %waitpid will wait on any children
in the process group of the particular child abs(pid).
The options argument is a bitwise OR of any of the flags:
%waitpid to not suspend if status is not immediately
available for one of the relevant child processes.
The value returned by %waitpid is a scheme pair of the child pid
and the status returned for that child.
#f if the device is not a terminal. Notice
how this also serves the function of the UNIX isatty() call.
execl, except that if filename does not contain
a slash it searches for the file in the directories listed in the
PATH environment variable.
%execlp is similar, but returns #f if an error occurs.
fork() system call. It
creates a new process with the same core image as the current process.
%fork returns #f upon failure; otherwise the child gets a
return value of 0, and the parent gets the child's pid.
See the UNIX fork man page for some of the subtelties of
%fork (open file descriptors, directory streams, semaphores,
tms_ values, file locks, ...).
%select call is used to examine a set of file descriptors
(passed as scheme lists of non-negative integers in readfds,
writefds and exceptfds).
The purpose of this examination is to determine if the descriptors are ready for the requested operation (reading or writing or treatment of exception). The return value is a list of 3 lists; the three lists are the original lists stripped down to only the ready file descriptors.
A timeout can be specified (in seconds plus miliseconds) with the secs and msecs are used.
uname() system call. Upon
successful completion it returns a list of 5 strings describing the
system name and OS version: (list OSname nodename OSrelease
OSversion MachineType). Upon failure it returns #f.
"VAR=val" strings. It can be called with a list of
"VAR=val" strings, and then the environment will be set to those
values.
mknod() man page for details on the
file type bits).
The dev argument is ignored unless mode is a block or character special file, in which case dev is a configuration-dependent specification of a character or block I/O device.
#f, accounting will be turned off.
Must be super user to use this call.
The value of increment should be between -20 and 20; if it is outside these bounds it will be silently adjusted to the extreme value.
#f on
any error condition.
%stat except that if path is a symlink, %lstat
will return information about the symlink, whereas %stat will
look at the referenced file. The rationale behind this is that symlinks
should be transparent to the traditional UNIX file system calls, but
extra calls (like %lstat and %readlink) are provided to
get more information.