0% found this document useful (0 votes)

108 views

Gamref2 Book

gamma2

Uploaded by

Oscar Osorio

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

108 views

Gamref2 Book

gamma2

Uploaded by

Oscar Osorio

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 244

Gamma Reference Volume 2

Version 7.2

Cogent Real-Time Systems, Inc.

August 15, 2012

Gamma Reference Volume 2: Version 7.2

A dynamically-typed interpreted programming language specifically designed to allow rapid development of
control and user interface applications. Gamma has a syntax similar to C and C++, but has a range of built-in
features that make it a far better language for developing sophisticated real-time systems.

Published August 15, 2012

Cogent Real-Time Systems, Inc.
162 Guelph Street, Suite 253
Georgetown, Ontario
Canada, L7G 5X7
Toll Free: 1 (888) 628-2028
Tel: 1 (905) 702-7851
Fax: 1 (905) 702-7850
Information Email: [email protected]
Tech Support Email: [email protected]
Web Site: www.cogent.ca

Copyright 1995-2011 by Cogent Real-Time Systems, Inc.

Revision History
Revision 7.2-1 September 2007
Updated DataHub-related functions for 6.4 release of the DataHub.
Revision 6.2-1 February 2005
Simplified TCP connectivity.
Revision 4.1-1 August 2004
Compatible with Cogent DataHub Version 5.0.
Revision 4.0-2 October 2001
New functions in Input/Output, OSAPIs, Date, and Dynamic Loading reference sections.
Revision 4.0-1 September 2001
Source code compatible across QNX 4, QNX 6, and Linux.
Revision 3.2-1 August 2000
Renamed "Gamma", changed function syntax.
Revision 3.0 October 1999
General reorganization and update of Guide and Reference, released in HTML and QNX Helpviewer formats.
Revision 2.1 June 1999
Converted from Word97 to DocBook SGML.
Revision 2.0 June 1997
Initial release of hardcopy documentation.

Copyright, trademark, and software license information.

Copyright Notice
1995-2011 Cogent Real-Time Systems, Inc. All rights reserved.
Information in this document is subject to change without notice. No part of this document may be reproduced or transmitted in any form or by
any means, electronic or mechanical, for any purpose, without the express written consent of Cogent Real-Time Systems, Inc.
Cogent Real-Time Systems, Inc. assumes no responsibility for any errors or omissions, nor do we assume liability for damages resulting from the
use of the information contained in this document.

Trademark Notice
Cascade DataHub, Cascade Connect, Cascade DataSim, Connect Server, Cascade Historian, Cascade TextLogger, Cascade NameServer, Cascade
QueueServer, RightSeat, SCADALisp and Gamma are trademarks of Cogent Real-Time Systems, Inc.
All other company and product names are trademarks or registered trademarks of their respective holders.

END-USER LICENSE AGREEMENT FOR COGENT SOFTWARE

IMPORTANT - READ CAREFULLY: This End-User License Agreement ("EULA") is a legal agreement between you (either an individual or a
single entity) and Cogent Real-Time Systems Inc. ("Cogent") of 162 Guelph Street, Suite 253, Georgetown, Ontario, L7G 5X7, Canada (Tel:
905-702-7851, Fax: 905-702-7850), from whom you acquired the Cogent software product(s) ("SOFTWARE PRODUCT" or "SOFTWARE"),
either directly from Cogent or through one of Cogents authorized resellers.
The SOFTWARE PRODUCT includes computer software, any associated media, any printed materials, and any "online" or electronic
documentation. By installing, copying or otherwise using the SOFTWARE PRODUCT, you agree to be bound by the terms of this EULA. If you
do not agree with the terms of this EULA, Cogent is unwilling to license the SOFTWARE PRODUCT to you. In such event, you may not use or
copy the SOFTWARE PRODUCT, and you should promptly contact Cogent for instructions on return of the unused product(s) for a refund.

SOFTWARE PRODUCT LICENSE

The SOFTWARE PRODUCT is protected by copyright laws and copyright treaties, as well as other intellectual property laws and treaties. The
SOFTWARE PRODUCT is licensed, not sold.
1. EVALUATION USE: This software is distributed as "Free for Evaluation", and with a per-use royalty for Commercial Use, where "Free for
Evaluation" means to evaluate Cogents software and to do exploratory development and "proof of concept" prototyping of software
applications, and where "Free for Evaluation" specifically excludes without limitation:
i. use of the SOFTWARE PRODUCT in a business setting or in support of a business activity,
ii. development of a system to be used for commercial gain, whether to be sold or to be used within a company, partnership, organization
or entity that transacts commercial business,
iii. the use of the SOFTWARE PRODUCT in a commercial business for any reason other than exploratory development and "proof of
concept" prototyping, even if the SOFTWARE PRODUCT is not incorporated into an application or product to be sold,
iv. the use of the SOFTWARE PRODUCT to enable the use of another application that was developed with the SOFTWARE PRODUCT,
v. inclusion of the SOFTWARE PRODUCT in a collection of software, whether that collection is sold, given away, or made part of a
larger collection.
vi. inclusion of the SOFTWARE PRODUCT in another product, whether or not that other product is sold, given away, or made part of a
larger product.

2. COMMERCIAL USE: COMMERCIAL USE is any use that is not specifically defined in this license as EVALUATION USE.
3. GRANT OF LICENSE: This EULA covers both COMMERCIAL and EVALUATION USE of the SOFTWARE PRODUCT. Either clause
(A) or (B) of this section will apply to you, depending on your actual use of the SOFTWARE PRODUCT. If you have not purchased a
license of the SOFTWARE PRODUCT from Cogent or one of Cogents authorized resellers, then you may not use the product for
COMMERCIAL USE.
A. GRANT OF LICENSE (EVALUATION USE): This EULA grants you the following non-exclusive rights when used for
EVALUATION purposes:

Software: You may use the SOFTWARE PRODUCT on any number of computers, either stand-alone, or on a network, so long as
every use of the SOFTWARE PRODUCT is for EVALUATION USE. You may reproduce the SOFTWARE PRODUCT, but only as
reasonably required to install and use it in accordance with this LICENSE or to follow your normal back-up practices.
Subject to the license expressly granted above, you obtain no right, title or interest in or to the SOFTWARE PRODUCT or related
documentation, including but not limited to any copyright, patent, trade secret or other proprietary rights therein. All whole or partial
copies of the SOFTWARE PRODUCT remain property of Cogent and will be considered part of the SOFTWARE PRODUCT for the
purpose of this EULA.
Unless expressly permitted under this EULA or otherwise by Cogent, you will not:

i. use, reproduce, modify, adapt, translate or otherwise transmit the SOFTWARE PRODUCT or related components, in whole or in
part;
ii. rent, lease, license, transfer or otherwise provide access to the SOFTWARE PRODUCT or related components;
iii. alter, remove or cover proprietary notices in or on the SOFTWARE PRODUCT, related documentation or storage media;
iv. export the SOFTWARE PRODUCT from the country in which it was provided to you by Cogent or its authorized reseller;
v. use a multi-processor version of the SOFTWARE PRODUCT in a network larger than that for which you have paid the
corresponding multi-processor fees;
vi. decompile, disassemble or otherwise attempt or assist others to reverse engineer the SOFTWARE PRODUCT;
vii. circumvent, disable or otherwise render ineffective any demonstration time-outs, locks on functionality or any other restrictions
on use in the SOFTWARE PRODUCT;
viii. circumvent, disable or otherwise render ineffective any license verification mechanisms used by the SOFTWARE PRODUCT;
ix. use the SOFTWARE PRODUCT in any application that is intended to create or could, in the event of malfunction or failure,
cause personal injury or property damage; or
x. make use of the SOFTWARE PRODUCT for commercial gain, whether directly, indirectly or incidentally.

B. GRANT OF LICENSE (COMMERCIAL USE): This EULA grants you the following non-exclusive rights when used for
COMMERCIAL purposes:
Software: You may use the SOFTWARE PRODUCT on one computer, or if the SOFTWARE PRODUCT is a multi-processor version on one node of a network, either: (i) as a development systems for the purpose of creating value-added software applications in
accordance with related Cogent documentation; or (ii) as a single run-time copy for use as an integral part of such an application. This
includes reproduction and configuration of the SOFTWARE PRODUCT, but only as reasonably required to install and use it in
association with your licensed processor or to follow your normal back-up practices.
Storage/Network Use: You may also store or install a copy of the SOFTWARE PRODUCT on one computer to allow your other
computers to use the SOFTWARE PRODUCT over an internal network, and distribute the SOFTWARE PRODUCT to your other
computers over an internal network. However, you must acquire and dedicate a license for the SOFTWARE PRODUCT for each
computer on which the SOFTWARE PRODUCT is used or to which it is distributed. A license for the SOFTWARE PRODUCT may
not be shared or used concurrently on different computers.
Subject to the license expressly granted above, you obtain no right, title or interest in or to the SOFTWARE PRODUCT or related
documentation, including but not limited to any copyright, patent, trade secret or other proprietary rights therein. All whole or partial
copies of the SOFTWARE PRODUCT remain property of Cogent and will be considered part of the SOFTWARE PRODUCT for the
purpose of this EULA.
Unless expressly permitted under this EULA or otherwise by Cogent, you will not:

i. use, reproduce, modify, adapt, translate or otherwise transmit the SOFTWARE PRODUCT or related components, in whole or in
part;

ii. rent, lease, license, transfer or otherwise provide access to the SOFTWARE PRODUCT or related components;
iii. alter, remove or cover proprietary notices in or on the SOFTWARE PRODUCT, related documentation or storage media;
iv. export the SOFTWARE PRODUCT from the country in which it was provided to you by Cogent or its authorized reseller;
v. use a multi-processor version of the SOFTWARE PRODUCT in a network larger than that for which you have paid the
corresponding multi-processor fees;
vi. decompile, disassemble or otherwise attempt or assist others to reverse engineer the SOFTWARE PRODUCT;
vii. circumvent, disable or otherwise render ineffective any demonstration time-outs, locks on functionality or any other restrictions
on use in the SOFTWARE PRODUCT;
viii. circumvent, disable or otherwise render ineffective any license verification mechanisms used by the SOFTWARE PRODUCT, or
ix. use the SOFTWARE PRODUCT in any application that is intended to create or could, in the event of malfunction or failure,
cause personal injury or property damage.

4. WARRANTY: Cogent cannot warrant that the SOFTWARE PRODUCT will function in accordance with related documentation in every
combination of hardware platform, software environment and SOFTWARE PRODUCT configuration. You acknowledge that software bugs
are likely to be identified when the SOFTWARE PRODUCT is used in your particular application. You therefore accept the responsibility of
satisfying yourself that the SOFTWARE PRODUCT is suitable for your intended use. This includes conducting exhaustive testing of your
application prior to its initial release and prior to the release of any related hardware or software modifications or enhancements.
Subject to documentation errors, Cogent warrants to you for a period of ninety (90) days from acceptance of this EULA (as provided above)
that the SOFTWARE PRODUCT as delivered by Cogent is capable of performing the functions described in related Cogent user
documentation when used on appropriate hardware. Cogent also warrants that any enclosed disk(s) will be free from defects in material and
workmanship under normal use for a period of ninety (90) days from acceptance of this EULA. Cogent is not responsible for disk defects
that result from accident or abuse. Your sole remedy for any breach of warranty will be either: i) terminate this EULA and receive a refund
of any amount paid to Cogent for the SOFTWARE PRODUCT, or ii) to receive a replacement disk.

5. LIMITATIONS: Except as expressly warranted above, the SOFTWARE PRODUCT, any related documentation and disks are provided "as
is" without other warranties or conditions of any kind, including but not limited to implied warranties of merchantability, fitness for a
particular purpose and non-infringement. You assume the entire risk as to the results and performance of the SOFTWARE PRODUCT.
Nothing stated in this EULA will imply that the operation of the SOFTWARE PRODUCT will be uninterrupted or error free or that any
errors will be corrected. Other written or oral statements by Cogent, its representatives or others do not constitute warranties or conditions of
Cogent.
In no event will Cogent (or its officers, employees, suppliers, distributors, or licensors: collectively "Its Representatives") be liable to you for
any indirect, incidental, special or consequential damages whatsoever, including but not limited to loss of revenue, lost or damaged data or
other commercial or economic loss, arising out of any breach of this EULA, any use or inability to use the SOFTWARE PRODUCT or any
claim made by a third party, even if Cogent (or Its Representatives) have been advised of the possibility of such damage or claim. In no event
will the aggregate liability of Cogent (or that of Its Representatives) for any damages or claim, whether in contract, tort or otherwise, exceed
the amount paid by you for the SOFTWARE PRODUCT.
These limitations shall apply whether or not the alleged breach or default is a breach of a fundamental condition or term, or a fundamental
breach. Some jurisdictions do not allow the exclusion or limitation of liability for consequential or incidental damages, or certain limitations
of implied warranties. Therefore the above limitation may not apply to you.

6. DESCRIPTION OF OTHER RIGHTS AND LIMITATIONS:

Separation of Components. The SOFTWARE PRODUCT is licensed as a single product. Its component parts may not be separated for use
on more than one computer.

Termination. Without prejudice to any other rights, Cogent may terminate this EULA if you fail to comply with the terms and conditions of
this EULA. In such an event, you must destroy all copies of the SOFTWARE PRODUCT and all of its component parts.

7. UPGRADES: If the SOFTWARE PRODUCT is an upgrade from another product, whether from Cogent or another supplier, you may use or
transfer the SOFTWARE PRODUCT only in conjunction with that upgrade product, unless you destroy the upgraded product. If the
SOFTWARE PRODUCT is an upgrade of a Cogent product, you now may use that upgraded product only in accordance with this EULA. If
the SOFTWARE PRODUCT is an upgrade of a component of a package of software programs which you licensed as a single product, the
SOFTWARE PRODUCT may be used and transferred only as part of that single product package and may not be separated for use on more
than one computer.
8. COPYRIGHT: All title and copyrights in and to the SOFTWARE PRODUCT (including but not limited to any images, photographs,
animations, video, audio, music, text and applets", incorporated into the SOFTWARE PRODUCT), any accompanying printed material, and
any copies of the SOFTWARE PRODUCT, are owned by Cogent or its suppliers. You may not copy the printed materials accompanying the
SOFTWARE PRODUCT. All rights not specifically granted under this EULA are reserved by Cogent.
9. PRODUCT SUPPORT: Cogent has no obligation under this EULA to provide maintenance, support or training.
10. RESTRICTED RIGHTS: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as provided in DFARS
227.7202-1(a) and 227.7202-3(a) (1995), DFARS 252.227-7013(c)(1)(ii) (OCT 1988), FAR 12.212(a)(1995), FAR 52.227-19, or FAR
52.227-14 (ALT III), as appropriate. Manufacturer is Cogent Real-Time Systems Inc. 162 Guelph Street, Suite 253, Georgetown, Ontario,
L7G 5X7, Canada.
11. GOVERNING LAW: This Software License Agreement is governed by the laws of the Province of Ontario, Canada. You irrevocably attorn
to the jurisdiction of the courts of the Province of Ontario and agree to commence any litigation that may arise hereunder in the courts
located in the Judicial District of Peel, Province of Ontario.

Table of Contents
1. What is Gamma? ...................................................................................................................................1
2. System Requirements ............................................................................................................................2
I. Input/Output...........................................................................................................................................3
close................................................................................................................................................4
fd_close.........................................................................................................................................5
fd_data_function .....................................................................................................................6
fd_eof_function........................................................................................................................7
fd_open...........................................................................................................................................8
fd_read.........................................................................................................................................10
fd_to_file..................................................................................................................................11
fd_write.......................................................................................................................................12
fileno ...........................................................................................................................................14
ioctl..............................................................................................................................................15
open ................................................................................................................................................16
pipe ................................................................................................................................................18
princ, print, pretty_princ, pretty_print ..................................................................19
pty, ptytio ..................................................................................................................................21
read ................................................................................................................................................23
read_char, read_double, read_float, read_long, read_short ............................24
read_eval_file ........................................................................................................................26
read_line ....................................................................................................................................27
read_n_chars.............................................................................................................................28
read_until..................................................................................................................................29
seek ................................................................................................................................................30
ser_setup ....................................................................................................................................32
tell ................................................................................................................................................33
terpri ...........................................................................................................................................34
unread_char ...............................................................................................................................35
write, writec, pretty_write, pretty_writec .............................................................36
write_n_chars...........................................................................................................................37
II. File System...........................................................................................................................................38
absolute_path...........................................................................................................................39
access ...........................................................................................................................................40
basename.......................................................................................................................................41
cd .....................................................................................................................................................42
chars_waiting...........................................................................................................................43
directory ....................................................................................................................................44
dirname.........................................................................................................................................45
drain..............................................................................................................................................46
file_date ....................................................................................................................................47
file_size ....................................................................................................................................48
flush..............................................................................................................................................49
getcwd ...........................................................................................................................................50
is_busy.........................................................................................................................................51
is_dir ...........................................................................................................................................52
is_file.........................................................................................................................................53
is_readable ...............................................................................................................................54
is_writable ...............................................................................................................................55
mkdir..............................................................................................................................................56
vii

path_node ....................................................................................................................................58
rename ...........................................................................................................................................59
root_path ....................................................................................................................................60
tmpfile.........................................................................................................................................61
unbuffer_file...........................................................................................................................62
unlink ...........................................................................................................................................63
III. OS APIs..............................................................................................................................................64
atexit ...........................................................................................................................................65
block_signal, unblock_signal .........................................................................................66
errno..............................................................................................................................................67
exec ................................................................................................................................................68
exit_program.............................................................................................................................69
fork ................................................................................................................................................70
getenv ...........................................................................................................................................72
gethostname ...............................................................................................................................73
getnid ...........................................................................................................................................74
getpid ...........................................................................................................................................75
getsockopt, setsockopt........................................................................................................76
kill ................................................................................................................................................78
nanosleep ....................................................................................................................................79
setenv ...........................................................................................................................................80
shm_open.......................................................................................................................................81
shm_unlink..................................................................................................................................83
signal ...........................................................................................................................................84
sleep, usleep .............................................................................................................................86
strerror.......................................................................................................................................87
system ...........................................................................................................................................88
tcp_accept..................................................................................................................................89
tcp_connect ...............................................................................................................................90
tcp_listen..................................................................................................................................91
wait ................................................................................................................................................92
IV. Dynamic Loading ..............................................................................................................................94
AutoLoad.......................................................................................................................................95
autoload_undefined_symbol..............................................................................................97
AutoMapFunction......................................................................................................................98
ClearAutoLoad...........................................................................................................................99
dlclose.......................................................................................................................................100
dlerror.......................................................................................................................................101
dlfunc .........................................................................................................................................102
DllLoad.......................................................................................................................................103
dlmethod.....................................................................................................................................104
NoAutoLoad................................................................................................................................105
dlopen .........................................................................................................................................106
V. Profiling and Debugging...................................................................................................................107
allocated_cells....................................................................................................................108
eval_count................................................................................................................................109
free_cells................................................................................................................................110
function_calls ......................................................................................................................111
function_runtime .................................................................................................................112
gc ...................................................................................................................................................113

viii

gc_blocksize...........................................................................................................................114
gc_enable ..................................................................................................................................115
gc_newblock .............................................................................................................................116
gc_trace.....................................................................................................................................117
profile.......................................................................................................................................118
set_autotrace.........................................................................................................................120
set_breakpoint ......................................................................................................................121
time ..............................................................................................................................................122
trace, notrace ......................................................................................................................123
VI. Miscellaneous...................................................................................................................................124
apropos.......................................................................................................................................125
create_state, enter_state, exit_state.....................................................................126
gensym .........................................................................................................................................127
modules.......................................................................................................................................128
stack............................................................................................................................................129
VII. IPC ..................................................................................................................................................130
add_hook.....................................................................................................................................131
close_task................................................................................................................................133
_destroy_task.........................................................................................................................134
init_async_ipc ......................................................................................................................135
init_ipc.....................................................................................................................................136
isend............................................................................................................................................137
locate_task .............................................................................................................................138
locate_task_id ......................................................................................................................140
name_attach .............................................................................................................................141
nserve_query...........................................................................................................................142
remove_hook .............................................................................................................................143
run_hooks ..................................................................................................................................144
send ..............................................................................................................................................145
send_async................................................................................................................................147
send_string .............................................................................................................................148
send_string_async...............................................................................................................149
taskdied, taskstarted ........................................................................................................150
task_info ..................................................................................................................................152
VIII. Events and Callbacks...................................................................................................................154
add_set_function .................................................................................................................155
flush_events...........................................................................................................................157
next_event, next_event_nb...............................................................................................158
remove_set_function ..........................................................................................................159
when_set_fns...........................................................................................................................160
IX. Time, Date, and Timers ..................................................................................................................161
after............................................................................................................................................162
at ...................................................................................................................................................163
block_timers, unblock_timers .......................................................................................165
cancel .........................................................................................................................................166
clock, nanoclock ....................................................................................................................167
date ..............................................................................................................................................168
date_of.......................................................................................................................................169
every............................................................................................................................................170
gmtime .........................................................................................................................................171
ix

localtime ..................................................................................................................................173
mktime .........................................................................................................................................175
timer_is_proxy ......................................................................................................................176
X. Cogent DataHub ...............................................................................................................................177
add_exception_function, add_echo_function ........................................................178
lock_point................................................................................................................................180
point_locked...........................................................................................................................181
point_nanoseconds...............................................................................................................182
point_seconds.........................................................................................................................183
point_security ......................................................................................................................184
read_existing_point, read_point ................................................................................185
register_all_points ..........................................................................................................186
register_exception.............................................................................................................187
register_point, register_existing_point.............................................................188
remove_echo_function........................................................................................................190
remove_exception_function............................................................................................191
secure_point...........................................................................................................................192
set_domain................................................................................................................................193
set_security...........................................................................................................................194
unregister_point .................................................................................................................196
when_echo_fns, when_exception_fns ...........................................................................197
write_existing_point, write_point ...........................................................................198
XI. QNX 4 ...............................................................................................................................................200
dev_read.....................................................................................................................................201
dev_setup ..................................................................................................................................203
inp, inpw.....................................................................................................................................204
mmap ..............................................................................................................................................205
outp, outpw ................................................................................................................................207
qnx_name_attach....................................................................................................................208
qnx_name_detach....................................................................................................................209
qnx_name_locate....................................................................................................................210
qnx_osinfo................................................................................................................................211
qnx_osstat................................................................................................................................214
qnx_proxy_attach .................................................................................................................215
qnx_proxy_detach .................................................................................................................216
qnx_proxy_rem_attach........................................................................................................217
qnx_proxy_rem_detach........................................................................................................218
qnx_receive .............................................................................................................................219
qnx_reply ..................................................................................................................................220
qnx_send.....................................................................................................................................221
qnx_spawn_process...............................................................................................................222
qnx_trigger .............................................................................................................................225
qnx_vc_attach.........................................................................................................................226
qnx_vc_detach.........................................................................................................................228
qnx_vc_name_attach.............................................................................................................229
Index..........................................................................................................................................................??
Colophon.................................................................................................................................................233

List of Tables
1. User/owner permission modes...............................................................................................................??
2. Group permission modes .......................................................................................................................??
3. Other permission modes ........................................................................................................................??
1. Signals....................................................................................................................................................??
1. dev_read min, time, and timeout values............................................................................................??

Chapter 1. What is Gamma?

Gamma is an interpreter, a high-level programming language that has been designed and optimized to
reduce the time required for building applications. It has support for the Photon GIU in QNX, and the
GTK GUI in Linux and QNX 6. It also has extensions that support HTTP and MySQL.

With Gamma a user can quickly implement algorithms that are far harder to express in other languages
such as C. Gamma lets the developer take advantage of many time-saving features such as memory
management and improved GUI support. These features, coupled with the ability to fully interact with
and debug programs as they run, mean that developers can build, test and refine applications in a shorter
time frame than when using other development platforms.
Gamma programs are small, fast and reliable. Gamma is easily embedded into todays smart appliances
and web devices.
Gamma is an improved and expanded version of our previous Slang Programming Language for
QNX and Photon. Gamma is available on QNX 4, QNX 6 and Linux, and is being ported to
Microsoft Windows.
The implementation of Gamma is based on a powerful SCADALisp engine. SCADALisp is a dialect of
the Lisp programming language which has been optimized for performance and memory usage, and
enhanced with a number of internal functions. All references in this manual to Lisp are in fact to the
SCADALisp dialect of Lisp.
You could say Gammas object language is Lisp, just like Assembler is the object language for C.
Knowing Lisp is not a requirement for using Gamma, but it can be helpful. All necessary information on
Lisp and how it relates to Gamma is in the Input and Output chapter of this guide.

Chapter 2. System Requirements

QNX 6

QNX 6.1.0 or later.

QNX 4

QNX 4.23A or later.

(For Gamma/Photon) Photon 1.14 or later.

Linux 2.4 or later.

(For Gamma/GTK) GTK 1.2.8.

The SRR IPC kernel module, which includes a synchronous message passing library modeled on the
QNX 4 send/receive/reply message-passing API. This module installs automatically, but requires a C
compiler for the installation. You can get more information and/or download this module at the Cogent
Web Site.
This module may not be necessary for some Gamma applications, but it is required for any use
of timers, event handling, or inter-process communication.

Linux

I. Input/Output
Table of Contents
close .........................................................................................................................................................4
fd_close ..................................................................................................................................................5
fd_data_function...............................................................................................................................6
fd_eof_function .................................................................................................................................7
fd_open.....................................................................................................................................................8
fd_read...................................................................................................................................................10
fd_to_file ...........................................................................................................................................11
fd_write ................................................................................................................................................12
fileno.....................................................................................................................................................14
ioctl .......................................................................................................................................................15
open..........................................................................................................................................................16
pipe..........................................................................................................................................................18
princ, print, pretty_princ, pretty_print............................................................................19
pty, ptytio............................................................................................................................................21
read..........................................................................................................................................................23
read_char, read_double, read_float, read_long, read_short......................................24
read_eval_file..................................................................................................................................26
read_line..............................................................................................................................................27
read_n_chars.......................................................................................................................................28
read_until ...........................................................................................................................................29
seek..........................................................................................................................................................30
ser_setup..............................................................................................................................................32
tell..........................................................................................................................................................33
terpri.....................................................................................................................................................34
unread_char.........................................................................................................................................35
write, writec, pretty_write, pretty_writec.......................................................................36
write_n_chars ....................................................................................................................................37

close
close closes an open file.

Syntax
close (file)

Arguments
file
A file pointer to a previously opened file. This may be either a file in the file system, or a string
opened for read and write.

Returns
t if the file had been open and was closed successfully, else nil.

Description
This function closes a previously opened file. It is not strictly necessary, as the file will be closed when
the garbage collector recognizes that there are no references to the file, but it is extremely good policy.
This function will close a string opened for reading and writing as well.

Example
Gamma> fp = open("myfile.dat","r");
#<File:"myfile.dat">
Gamma> close(fp);
t
Gamma> fp;
#<Destroyed Instance>
Gamma>

O_RDONLY Read-only mode

O_WRONLY Write-only mode

O_RDWR Read-Write mode

Any combination of the following flags may be bitwise OR-ed with the open mode to modify how the
file is accessed:

O_APPEND Append (writes guaranteed at the end)

O_CREAT Opens with file create

O_EXCL Exclusive open

O_NOCTTY Dont assign a controlling terminal

O_NONBLOCK Non-blocking I/O

O_TRUNC Open with truncation

O_DSYNC Data integrity synch

O_SYNC File integrity synch

O_TEMP Temporary file, dont put to disk

O_CACHE Cache sequential files too

If an error occurs -1 is returned and errno is set to one of the following:

fd_open

EACCES Search permission denied on a portion of the path prefix, or the file exists and the
permissions required to open the file in the given mode so not exist.

EBADFSYS The file or the path prefix to the file was found to be corrupted

EBUSY The file is already open for writing.

EEXIST O_CREAT and O_EXCL are set and the named file exists

EINTR The function was interrupted by a signal

EISDIR The named file is a directory

EMFILE Too many file descriptors are currently in use by this process

ENAMETOOLONG The length of the path to the file is too long.

ENFILE Too many files are currently open on the system

ENOENT O_CREAT is not set and the file does not exist

ENOSPC The directory or file system which would create the new file cannot be extended

ENOTDIR A component of the path to the file is not a directory

ENXIO O_NONBLOCK is set, the file is a FIFO, O_WRONLY is set, and no process has the file
open for reading

EROFS The named file resides on a read-only file system.

Example
Gamma> require_lisp("const/filesys");
"/usr/cogent/lib/const/filesys.lsp"
Gamma> ptr = fd_open("/fd/ttyp8",O_WRONLY);
4
Gamma> fd_write(ptr,"\nhello\n");
7

See Also
fd_close, fd_data_function, fd_eof_function, fd_read, fd_write ser_setup,
Referencing Files

fd_read
fd_read reads a buffer or string from a file identified by a file descriptor.

Syntax
fd_read (fd, buffer|string, length?, offset?)

Arguments
fd
A file descriptor as returned from fd_open.
buffer|string
A buffer or string to be read from the file.
length
An integer specifying the length of the buffer or string.
offset
An integer specifying the position in the file to begin reading the buffer or string.

Returns
The number of bytes actually read from the file, or -1 on failure and the errno is set.

Description
This function reads a buffer or string from the specified file.
When an error occurs, the following errnos are possible:

EAGAIN The O_NONBLOCK flag is set for the fd and the process would be delayed in the read
operation.

EBADF The passed fd is invalid or not open for writing.

EFBIG File is too big.

EINTR Read was interrupted by a signal.

EINVAL iovcnt was less than or equal to 0, or greater than UIO_MAXIOV.

EIO Physical I/O error.

Example
Gamma> x = fd_open("/fd/ser1",O_RDWR);
4
Gamma> fd_read(x,"hello\n");
6
Gamma> fd_close(x);
t

See Also
fd_close, fd_open, fd_read, ser_setup, Referencing Files

fd_to_file
fd_to_file creates a file pointer from a descriptor.

Syntax
fd_to_file (fd, mode)

Arguments
fd
A file descriptor as returned from fd_open.
mode
A string indicating the mode for the file: "r" for read-only, "w" for writable, "a" for append.

Returns
t, if successful, otherwise nil.

Description
This function creates a file pointer from a file descriptor.

EBADF The passed fd is invalid or not open for writing.

EFBIG File is too big.

EINTR Write was interrupted by a signal.

EINVAL iovcnt was less than or equal to 0, or greater than UIO_MAXIOV.

EIO Physical I/O error.

ENOSPC No free space remaining on drive.

EPIPE Attempt to write to a pipe (or FIFO) that is not open for write. SIGPIPE is also sent to process.

Example
Gamma> x = fd_open("/fd/ser1",O_RDWR);
4
Gamma> fd_write(x,"hello\n");
6
Gamma> fd_close(x);
t

fd_write

See Also
fd_close, fd_open, fd_read, ser_setup, Referencing Files

fileno
fileno creates a file descriptor from a pointer.

Syntax
fileno (file)

Arguments
file
A file pointer as returned from open.

Returns
t, if successful, otherwise nil.

Description
This function creates a file descriptor from a file pointer.

Calling open will produce:

Gamma> fp = open ("myopenfile.dat", "r", nil);
#<File:"myopenfile.dat">
Gamma> princ(read_line(fp), "\n");
(setq y 5)
t
Gamma> fp = open ("myopenfile.dat", "r", nil);

open

#<File:"myopenfile.dat">
Gamma> eval (read(fp));
5
Gamma> fp = open ("myopenfile.dat", "r", t);
#<File:"myopenfile.dat">
Gamma> princ(read_line(fp), "\n");
(setq y 5)
t
Gamma> fp = open ("myopenfile.dat", "r", t);
#<File:"myopenfile.dat">
Gamma> eval (read(fp));
Error: ./generate.slg: line 1: Malformed expression within ()
Error: ./generate.slg: line 1: Unexpected end of file
Macro read left extra stuff on the LISP stack: 8098478, 8098470
nil
nil
Gamma>

The following example opens and reads a file, if it exists. If not, it prints and error message.
if ( (fp=open("myfile","r")) != nil )
{
local line;
while((line = read_line(fp)) != _eof_)
{
princ(line, "\n");
}
close(fp);
}
else
{
princ("Error : unable to open myfile for read\n");
}

See Also
close, fd_open, open_string, read, read_char, read_double, read_float,
read_line, read_long, read_short, read_until, seek, tell, terpri, write, writec

pipe
pipe creates a pipe.

Syntax
pipe ()

Arguments
none

Returns
A list of the read pipe and the write pipe, each as a file pointer.

Description
This function creates an un-named pipe.

Example
Gamma> pipe1 = pipe();
(#<File:"read_pipe"> #<File:"write_pipe">)
Gamma> pread = car(pipe1);
#<File:"read_pipe">
Gamma> pwrite = cadr(pipe1);
#<File:"write_pipe">
Gamma> write (pwrite, "This is a test");
t
Gamma> read (pread);
"This is a test"
Gamma>

princ, print, pretty_princ, pretty_print

princ, print, pretty_princ, pretty_print write to the standard output file.

Syntax
princ (s_exp...)
print (s_exp...)
pretty_princ (s_exp...)
pretty_print (s_exp...)

Arguments
s_exp
Any Gamma or Lisp expression.

Returns
t

Description
These functions write to the standard output file, typically the screen. The princ and pretty_princ
functions produce formatted output, which means that special characters are not escaped, and double
quotes are not printed around character strings. Output generated by princ cannot be read by the Lisp
reader.
print and pretty_print produce Lisp-readable output. The result of reading a printed expression
using a call to read will generate an equal expression.
pretty_princ and pretty_print generate carriage returns and spaces with the intention of
formatting the output to make long or complex Lisp expressions easier for a person to read.

Examples
Gamma> x = "hello";
"hello"
Gamma> print (x,"\n");
"hello""\n"t
Gamma> princ (x,"\n");
hello
t
Gamma> >
Gamma> class C {a; b; c;}
(defclass C nil [][a b c])
Gamma> princ (C);
(defclass C nil [][a b c])t
Gamma> pretty_princ (C);
(defclass C nil
[]
[a b c])t
Gamma>
Gamma> L = list (1,2,3,4,5,list(1,2,3,4,5,list(1,2,3
list(1,2,3,4,5,list(1,2,3,4,5,list(1,2,3,4,5,list(1,2
,list(1,2,3,4,5,list(1,2,3,4,5)))))))))));
(1 2 3 4 5 (1 2 3 4 5 (1 2 3 4 5 (1 2 3 4 5 (1 2 3 4
4 5 (1 2 3 4 5 (1 2 3 4 5 (1 2 3 4 5 (1 2 3 4 5)))))
Gamma> princ (L);

princ, print, pretty_princ, pretty_print

(1 2 3 4 5 (1 2 3 4 5 (1 2 3 4 5 (1 2 3 4 5 (1 2 3 4
4 5 (1 2 3 4 5 (1 2 3 4 5 (1 2 3 4 5 (1 2 3 4 5)))))
Gamma> pretty_princ (L);
(1 2 3 4 5
(1 2 3 4 5
(1 2 3 4 5
(1 2 3 4 5
(1 2 3 4 5
(1 2 3 4 5
(1 2 3 4 5 (1 2 3 4 5 (1 2 3 4 5 (
))))))))))t
Gamma>

read_char, read_double, read_float, read_long,

read_short
read_char, read_double, read_float, read_long, read_short read the next
character, double, float, long or short value in binary representation from the input file.

Syntax
read_char (file)
read_double (file)
read_float (file)
read_long (file)
read_short (file)

Arguments
file
A file pointer to a previously opened file. This may be either a file in the file system, or a string
opened for read and write.

Returns
read_char returns the decimal representation of a string of length 1 containing a single character, or
-1 indicating end of file.
read_double, read_float return a floating point value, or nan indicating end of file.
read_long, read_short return an integer value, or -1 indicating end of file.

Description
These functions read the next character, double, float, long or short value in binary representation from
the input file, regardless of Lisp expression syntax. This allows a programmer to read binary files
constructed by other programs.

Example
The file "myfile.dat" contains the following:
ajz
Successive calls to read_char will produce:
Gamma> ft = open ("myreadcfile.dat","r");
#<File:"myreadcfile.dat">
Gamma> read_char(ft);
97
Gamma> read_char(ft);
106
Gamma> read_char(ft);
122
Gamma> read_char(ft);
-1 Gamma>

read_char, read_double, read_float, read_long, read_short

Successive calls to read_line will produce:

Gamma> ft = open ("myreadlfile.dat", "r");
#<File:"myreadlfile.dat">
Gamma> read_line(ft);
"Lists can be"
Gamma> read_line(ft);
"expressed as (a b c)."
Gamma> read_line(ft);
"Unexpected end of file"
Gamma>

See Also
read, read_char, read_double, read_float, read_long, read_short, read_until

read_n_chars
read_n_chars reads and stores characters.

Syntax
read_n_chars (file, nchars)

Arguments
file
A file pointer to a previously opened file. This may be either a file in the file system, or a string
opened for read and write.
nchars
The number of characters to read.

Returns
A buffer containing the characters read. The length of the return buffer is equal to the number of
characters actually read. This function returns nil if no characters could be read.

Description
This function reads the given number of characters from the file, without any form of translation, and
builds a new buffer object in which to store them. If this function reaches the end of the file before all
characters are read, then the buffer will be shorter than the requested number of characters.

Example
An input file contains the following:
To be or not to be, that is the question.

Successive calls to read_n_chars will produce:

Gamma> ft = open ("myreadnfile.dat", "r");
#<File:"myreadnfile.dat">
Gamma> read_n_chars(ft,15);
#{To be or not to}
Gamma> read_n_chars(ft,18);
#{ be, that is the q}
Gamma> read_n_chars(ft,18);
#{uestion.}
Gamma> read_n_chars(ft,18);
nil
Gamma>

Successive calls to read_until will produce:

Gamma> ft = open ("myreadlfile.dat","r");
#<File:"myreadlfile.dat">
Gamma> read_until(ft, "(");
"Lists can be\nexpressed as "
Gamma> read_until(ft,"x");
"a b c)."
Gamma> read_until(ft,"y");
"Unexpected end of file"
Gamma>

See Also
read, read_char, read_double, read_float, read_line, read_long, read_short

seek
seek sets the file position for reading or writing.

Syntax
seek (file, offset, where)

Arguments
file
A file pointer to a previously opened file. This may be either a file in the file system, or a string
opened for read and write.
offset
An integer specifying the number of characters into the file, starting from where.
where
A starting point, indicated by a number:

0 Beginning of the file.

1 Current position in the file.

2 End of the file.

Returns
t if successful, nil if unsuccessful.

Description
This function lets you specify a position in a file to start reading or writing.

Example
The file "myseekfile" contains the following:
Now is the time for all good men and women
to come to the aid of their world.
Gamma> msk = open("myseekfile.dat", "r",nil);
#<File:"myseekfile.dat">
Gamma> seek(msk, 5, 0);
t
Gamma> read_line(msk);
"s the time for all good men and women"
Gamma> seek(msk, 2, 1);
t
Gamma> read_line(msk);
" come to the aid of their world."
Gamma> seek(msk, -15, 2);
t
Gamma> read_line(msk);
"of their world."
Gamma> seek(msk, -3, 0);
nil
Gamma>

seek

See Also
open, open_string, read, read_char, read_double, read_float, read_line,
read_long, read_short, read_until, tell

ser_setup
ser_setup sets parameters for a serial port device.

Syntax
ser_setup (devno, baud, bits/char, parity, stopbits, min, time)

Arguments
devno
A file ID as returned from a call to fd_open.
baud
A legal baud rate.
bits/char
Bits per character (6, 7 or 8).
parity
"none", "even", "odd", "mark" or "space"
stopbits
Stop bits (0, 1 or 2).
min
Default minimum number of characters for a read.
time
Default inter-character timeout for a read.

Returns
t on success or nil on failure.

Description
This function sets the most common parameters for a serial port device, as opened by a call to
fd_open. The function is currently only available in QNX 4.

Example
Gamma> id = fd_open("/dev/ser1",O_RDWR);
4
Gamma> ser_setup(id,9600,8,"none",1,1,0);
t

Gamma> fw = open("mytpfile.dat", "w");

#<File:"mytpfile.dat">
Gamma> write(fw,list(#chars,list(1,2,3)));
t
Gamma> terpri(fw);
t
Gamma> write(fw,list(#chars,list(4,5,6)));
t
Gamma> close(fw);
t
Gamma> fr = open("mytpfile.dat", "r", nil);
#<File:"mytpfile.dat">
Gamma> read_line(fr);
"(chars (1 2 3))"
Gamma> read_line(fr);
"(chars (4 5 6))"
Gamma> terpri();
t
Gamma>

unread_char
unread_char attempts to replace a character to a file for subsequent reading.

Syntax
unread_char (file, character)

Arguments
file
A file pointer to a previously opened file. This may be either a file in the file system, or a string
opened for read and write.
character
A single character.

Returns
t if the character could be replaced on the file, otherwise nil.

Description
This function attempts to place the given character back onto the file so that it can be read again
by subsequent calls to any of the read family of functions. Only one character may be replaced onto a
file between calls to read. At least one read call must have been made prior to calling this function.

Example
An input file contains the following:
ABCDE

A call to unread_char within a succession of calls to read_char will produce:

Gamma> fr = open("myunreadfile.dat", "r", t);
#<File:"myunreadfile.dat">
Gamma> read_char(fr);
65
Gamma> read_char(fr);
66
Gamma> unread_char(fr,A);
t
Gamma> read_char(fr);
65
Gamma> read_char(fr);
67
Gamma> read_char(fr);
68
Gamma>

write, writec, pretty_write, pretty_writec

write, writec, pretty_write, pretty_writec write an expression to a file.

Syntax
write (file, s_exp...)
writec (file, s_exp...)
pretty_write (file, s_exp...)
pretty_writec (file, s_exp...)

Arguments
file
A file pointer to a previously opened file. This may be either a file in the file system, or a string
opened for read and write.
s_exp
Any Gamma or Lisp expression.

Returns
t on success, otherwise nil.

Description
Writes the given expressions to the file using the same format as print. See print for more
information.
writec produces the same format as princ; pretty_write produces the same format as
pretty_print; and pretty_writec produces the same format as pretty_printc. Any
contents written to the file before it was opened will be deleted when any of these write functions are
used.

Example
Gamma> fw = open("mywritefile.dat", "w");
#<File:"mywritefile.dat">
Gamma> write(fw,"This is on \n one line.");
t
Gamma> writec(fw,"This finishes on \n another line.");
t
Gamma> close(fw);
t
Gamma> fr = open("mywritefile.dat", "r", nil);
#<File:"mywritefile.dat">
Gamma> read_line(fr);
"\"This is on \n one line.\"This finishes on "
Gamma> read_line(fr);
" another line."
Gamma>

II. File System

Table of Contents
absolute_path ....................................................................................................................................39
access.....................................................................................................................................................40
basename ................................................................................................................................................41
cd...............................................................................................................................................................42
chars_waiting ....................................................................................................................................43
directory..............................................................................................................................................44
dirname...................................................................................................................................................45
drain .......................................................................................................................................................46
file_date..............................................................................................................................................47
file_size..............................................................................................................................................48
flush .......................................................................................................................................................49
getcwd.....................................................................................................................................................50
is_busy...................................................................................................................................................51
is_dir.....................................................................................................................................................52
is_file...................................................................................................................................................53
is_readable.........................................................................................................................................54
is_writable.........................................................................................................................................55
mkdir .......................................................................................................................................................56
path_node..............................................................................................................................................58
rename.....................................................................................................................................................59
root_path..............................................................................................................................................60
tmpfile...................................................................................................................................................61
unbuffer_file ....................................................................................................................................62
unlink.....................................................................................................................................................63

absolute_path
absolute_path returns the absolute path of the given file.

Syntax
absolute_path (filename)

Arguments
filename
The name of a disk file.

Returns
The absolute path of the file.

Description
This function returns the absolute path of the given file, with extraneous ../ constructs removed, and with
the full QNX 4 node number added. The filename can be relative or absolute, on any node on the
network.

Example
Gamma> absolute_path(".profile");
"//1/home/andrewt/.profile"

access
access checks a file for various permissions.

Syntax
access (filename, mode)

Arguments
filename
The name of a file on disk.
mode
The file mode to be tested. The legal modes are discussed below.

Returns
Zero is returned if the access mode is valid, otherwise -1 is returned and the errno is set.

Description
This function checks a file for the following permissions. Two or more permissions in bitwise OR
combinations can be checked at one time.

R_OK Test for read permission.

W_OK Test for write permission.

X_OK Test for execute permission.

F_OK Test for existence of file.

The library "const/Filesys.lsp" must be required to use the constants listed above.

Example
Gamma> require_lisp("const/Filesys");
"/usr/cogent/lib/const/Filesys.lsp"
Gamma> system("touch /tmp/access_test");
0
Gamma> system("chmod a=rx /tmp/access_test");
0
Gamma> access("/tmp/access_test", R_OK|X_OK);
0
Gamma> access("/tmp/access_test", W_OK);
-1
Gamma>

See Also
is_busy, is_file, is_readable, is_writable, errno

basename
basename gives the base of a filename.

Syntax
basename (filename, suffix?)

Arguments
filename
A file name as a string, as defined by the operating system.
suffix
Any ending part of the filename to exclude.

Returns
The base of the filename. If a suffix is specified, the base of the filename without the suffix.

Example
Gamma> x = basename("/usr/george/lib/misc/myfile.dat");
"myfile.dat"
Gamma> y = basename("misc/myfile.dat", ".dat");
"myfile"
Gamma>

0 Find all files and directories.

1 Find all files.

2 Find all directories.

fullpaths
If non-nil, show the full pathname of the file by prepending the path to all filenames.

Returns
A list containing all of the requested directory entries as strings.

Example
Gamma> directory("/usr",0,nil);
("local" "lib" "bin" "readme")
Gamma> sort(directory("/usr",2,t),strcmp);
("/usr/bin" "/usr/lib" "/usr/local")

dirname
dirname returns the directory path of a file.

Syntax
dirname (filename)

Arguments
filename
A file name as a string, including its directory path, as defined by the operating system.

Returns
The directory path of the filename, or if no path is entered, the filename.

Description
This function reads the filename and directory path as a string, returning the directory path as a string.

Example
Gamma> x = dirname("/usr/george/lib/misc/myfile.dat");
"/usr/george/lib/misc"
Gamma> y = dirname("misc/myfile.dat");
"misc"
Gamma> z = dirname("myfile.dat");
"myfile.dat"
Gamma>

Read, write, execute/search

S_IRUSR

0o4

Read permission

S_IWUSR

0o2

Write permission

S_IXUSR

0o1

Execute/search permission

Table 2. Group permission modes

Text format

Octal format

Meaning

S_IRWXG

0o7

Read, write, execute/search

S_IRGRP

0o4

Read permission

S_IWGRP

0o2

Write permission

S_IXGRP

0o1

Execute/search permission

Table 3. Other permission modes

Text format

Octal format

Meaning

S_IRWXO

0o7

Read, write, execute/search

S_IROTH

0o4

Read permission

S_IWOTH

0o2

Write permission

S_IXOTH

0o1

Execute/search permission

mkdir

Miscellaneous permissions.

S_IREAD same as S_IRUSR

S_IWRITE same as S_IWUSR

S_IEXEC same as S_IXUSR

These flags are bitwise OR-ed together to get the desired mode.
Error constants for this function:

EACCES Search permission for some component of the path denied.

EEXIST The named file exists.

EMLINK Maximum sub-dirs. reached.

ENAMETOOLONG The name of the path or the new directory is too long.

ENOENT The specified path does not exist.

ENOSPC No space left on the file system.

ENOSYS This function is not supported for this path.

ENOTDIR A component of the passed path is not a directory.

EROFS Tried to create a directory on a read-only file system.

Example
Gamma> require_lisp("const/Filesys");
"/usr/cogent/lib/const/Filesys.lsp"
Gamma> mkdir("/tmp/mydir", S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH);
0
Gamma> mkdir("/tmp/mydir2", 0o755);
0
Gamma>

...gives these results:

[sh]$ exiting.g
Started running...
Still running.
Exiting now.
[sh]$

block_signal, unblock_signal
block_signal, unblock_signal delimit signal blocking.

Syntax
block_signal (signo)
unblock_signal (signo)

Arguments
signo
The integer signal number as defined by the operating system. Symbols such as SIGINT are defined
to provide an operating-system independent method for specifying this number. (see signal)

Returns
t

Description
block_signal causes a particular signal to be blocked until a call to unblock_signal is made. If
the signal actually occurred while it was blocked, it will occur immediately when unblock_signal is
called. Multiple occurrences of the signal while it was blocked will cause the signal to be reported
multiple times when unblock_signal is called on most operating systems. Code that blocks signals
should be surrounded by a call to unwind_protect.

Example
Gamma> block_signal(14);
t
Gamma> kill(getpid(),14);
t
Gamma> unblock_signal(14);
Alarm clock
Gamma> block_signal (SIGINT);
t
Gamma> critical_function();
<function return>
Gamma> unblock_signal (SIGINT);
t

...gives these results:

[]$ gamma exiting.g
Started running...
Still running.
Exiting now.
[]$
Exit showing abnormal termination of -1 (255) to the operating system.
exit_program(-1);
/>echo $?
255
/>

fork
fork duplicates a process.

Syntax
fork ()

Arguments
none

Returns
A positive task id that identifies the child process, and 0 that identifies the parent process to the child; or
-1 if an error occurred. The errno is set if an error occurs.

Description
The fork function creates a new process identical to the calling (parent) process except for a unique
process ID. The child process has a different parent process ID and its own copy of the parent file
descriptors. The child process does not inherit outstanding signals.

Example
The following example illustrates using the fork function with if syntax. This is a useful way of
separating the two, identical processes produced from fork. The first block of code applies to the parent
process, while the second block applies to the child.
#!/usr/cogent/bin/gamma
if ((childID = fork()) > 0)
{
princ("P> My ID is: ", getpid(),"\n");
princ("P> My childs ID is: ", childID, "\n");
signal(SIGCHLD, #princ("P> Signal received that my child -- ",
childID, " -- has died.\n"));
princ("P> Waiting for my child.\n");
w = wait(childID);
princ("P> wait() returned this: ", w, "\n");
}
else
{
sleep(2);
if (childID == -1)
error("C> An error occurred.\n");
else
{
princ("C> I am the child process.\nC> My process ID is: ",
getpid(), "\n");
sleep(2);
princ("C> Time to exit.\n");
exit_program(3);
}
}

Will produce these results:

P> My ID is: 1225
P> My childs ID is: 1226
P> Waiting for my child.

fork

(after 2 seconds)
C> I am the child process.
C> My process ID is: 1226

(after 2 more seconds)

C> Time to exit.
P> Signal received that my child -- 1226 -- has died.
P> wait() returned this: (1226 3 nil nil)

0 for off, non-zero for on.

Allows for broadcasting datagrams from the

socket.

SO_DEBUG

0 for off, non-zero for on.

Records debugging information.

SO_DONTROUTE

0 for off, non-zero for on.

Sends messages directly to the network interface

instead of using normal message routing.

SO_ERROR

A number.

Resets the error status (for getsockopt only).

SO_KEEPALIVE

0 for off, non-zero for on.

Transmits messages periodically on a connected

socket. No response means the connection is
broken.

SO_LINGER

Two values: on_or_off

and linger_time, where
on_or_off is 0 for off,
non-zero for on. If on, a
value for linger_time is
required.

Keeps the socket open after a close() call, to

deliver untransmitted messages. If on_or_off
is non-zero, the socket will block for the
duration of the linger_time or until all
messages have been sent.

getsockopt, setsockopt

Option

Possible Values

Comments

TCP_NODELAY

0 for enable, non-zero for

disable.

Disables the Nagle algorithm for sending data.

SO_OOBINLINE

0 for off, non-zero for on.

Puts out-of-band data in the normal input queue.

SO_REUSEADDR

0 for off, non-zero for on.

Permits the reuse of local addresses for this

socket.

SO_RCVBUF

A number.

The size of the input buffer.

SO_RCVLOWAT

A number.

Sets the minimum count for input operations.

SO_RCVTIMEO

Two values: seconds and

nanoseconds.

Sets a timeout value for input.

SO_SNDBUF

A number.

The size of the output buffer.

SO_SNDLOWAT

A number.

Sets the minimum count for output operations.

SO_SNDTIMEO

Two values: seconds and

nanoseconds.

Sets a timeout value for output.

SO_TYPE

A number.

The type of socket (for getsockopt only).

Example
Gamma>
8
Gamma>
0
Gamma>
0
Gamma>
1
Gamma>
0
Gamma>
-1
Gamma>
0
Gamma>

skt = tcp_connect("localhost", 22);

getsockopt(skt, SO_KEEPALIVE);
setsockopt(skt, SO_KEEPALIVE, 1);
getsockopt(skt, SO_KEEPALIVE);
getsockopt(skt, SO_DEBUG);
setsockopt(skt, SO_DEBUG, 1);
getsockopt(skt, SO_DEBUG);

kill
kill sends a signal to a process.

Syntax
kill (pid, signo)

Arguments
pid
The process id number.
signo
The signal number, normally one of the built-in signal values.

Returns
t

Description
This process functions similarly to the kill shell command. Signals and their descriptions can be found
in signal.

Example
Process 1:
Gamma> getpid();
8299
Gamma>

Process 2:
Gamma> kill(8299,9);
t
Gamma>

Process 1:
Gamma> Killed

Process 3:
Gamma> getpid();
9041
Gamma> kill (9041,14);
Alarm clock

O_RDONLY open for read-only

O_RDWR open for read and write access

O_CREAT create a new shared memory segment with access privledges governed by the
create_mode parameter

O_EXCL Exclusive mode. If O_EXCL and O_CREAT are set then shm_open will fail if the shared
memory segment exists.

O_TRUNC If the shared memory object exists, and it is successfully opened O_RDWR, the object is
truncated to zero length and the mode and owner are unchanged.

The creation mode is usually an octal number in the range 0o000 - 0o777 defining the access privledges
for the shared memory object. Require the const/filesys file to load constants to make this arg easier
Possible errno values are:
81

shm_open

EACCESS permission to create the shared memory object denied

EEXIST O_CREAT and O_EXCL are set and the named shared memory object already exists

EINTR The function call was interrupted by a signal

EMFILE Too many file descriptors in use by this process

ENAMETOOLONG The lengthof the name arg is too long

ENFILE To many shared memory objects are currently open in the system

ENOENT O_CREAT is not set and the named shared memory object does not exist, or O_CREAT is
set and either the name prefix does not exist or the name arg is an empty string

ENOSPC Not enough space for the creation of the new shared memory object

ENOSYS This function is not supported by this implementation.

Example
//This code maps the first 1000 bytes from video
//memory (0xA0000) into a buffer named buf.
require_lisp("const/filesys");
require_lisp("const/mman");
fd = shm_open("Physical",O_RDONLY, 0o777);
buf = mmap(1000, PROT_READ , MAP_SHARED, fd, 0xA0000);

EACCESS Permission to unlink the object is denied

ENAMETOOLONG The lenght of the name of the object is too long

ENOENT The named shared memory object does not exist.

ENOSYS This function is not supported by this implementation.

Example
Gamma> shm_unlink("card_mem");
t
Gamma>

Abort signal from the abort() C function.

SIGALRM

A timer has occurred. This signal is reserved in most operating system

implementations of Gamma for use with the after, at and every
functions. This signal is not available in Linux because it is used by the
timer processing internally to Gamma. In QNX, it is the timer signal from
the alarm() C function.

SIGBUS

Bus error.

SIGCHLD

Child died. Generated when a child process of the current process has died.

SIGCONT

Continue. Causes the task to restart after a SIGSTP.

SIGFPE

Floating point exception. Generated by an illegal mathematical function call

(such as division by zero).

SIGHUP

Hangup. Typically generated when a terminal session disconnects.

SIGILL

Illegal instruction. This is an internal error.

SIGINT

Keyboard interrupt. Generated by CTRL-C.

SIGIO

I/O processing is required. This signal is generated when a socket or file

descriptor has incoming data which must be processed.

SIGIOT

IOT trap. A synonym for SIGABRT.

signal

Signal

Description

SIGKILL

Killed. Kills the process with extreme prejudice. This signal cannot be
caught.

SIGPIPE

Broken pipe. This occurs when a TCP/IP socket or a pipe to an inferior

process is broken.

SIGPOLL

A pollable event. Synonym of SIGIO.

SIGPWR

Power failure. This is generated by a power monitor program to indicate that

a power loss is imminent.

SIGQUIT

Quit.

SIGSEGV

Segmentation fault. This signal is generated by an attempt to access illegal

memory. If this signal occurs, it represents a fault in the LISP interpreter and
should be reported along with the corresponding memory address of the
fault.

SIGSTOP

Stop execution immediately. This is used by the operating system to

implement multi-tasking. This signal cannot be caught.

SIGSYS

Bad argument to a system routine. This happens very rarely.

SIGTERM

Terminated. This is generated by other programs which wish to terminate

the job.

SIGTRAP

Trace/breakpoint trap.

SIGTSTP

Terminal stop. This signal is generated when the user attempts to stop a
process (in operating systems which support job control).

SIGTTIN

Terminal input is available.

SIGTTOU

Terminal output is required.

SIGURG

Urgent. An urgent condition has occurred.

SIGUSR1

User-defined signal 1.

SIGUSR2

User-defined signal 2.

SIGWINCH

Window change. This is used to indicate that a change has been made to the
size or position of the window in which the process is running.

Example
Gamma> getpid();
10341
Gamma> signal(SIGUSR1,#princ("Got the signal.\n"));
t
Gamma> kill(10341,SIGUSR1);
Got the signal.
t
Gamma>

Gamma> tcp_connect("localhost", 51715);

Gamma> fd_write(5, "Hi there");

Gamma> fd_read(6, "Hi there");

A list of four items:

1. The process ID.
2. The process exit status (WEXITSTATUS), or nil.
3. A termination signal (WTERMSIG) if the process exited due to a signal, or nil.
4. A stopped signal (WSTOPSIG) if the process stopped due to a signal, or nil.

t if the WNOHANG option had been set and there was a child with a status change.

nil if there was a failure due to error.

Description
This function combines and simplifies the C functions wait and waitpid in a single function. If
taskid is provided, then the function acts as waitpid, and will not return until the given child task
has died.
The WNOHANG option allows the calling process to continue if the status of specified child process is not
immediately available. The WUNTRACED option allows the calling process to return if the child process
has stopped and its status has not been reported. Both of these can be specified using the OR (||)
operator.

Example
Process 1:
Gamma> child = fork();
9089
Gamma> 0
Gamma> if (child > 0) wait(); else exit_program(5);

Process 2:
Gamma> kill(9089,14);

wait

t
Gamma>

Process 1:
(9089 nil 14 nil)
Gamma>

IV. Dynamic Loading

Table of Contents
AutoLoad ................................................................................................................................................95
autoload_undefined_symbol .......................................................................................................97
AutoMapFunction ...............................................................................................................................98
ClearAutoLoad ....................................................................................................................................99
dlclose.................................................................................................................................................100
dlerror.................................................................................................................................................101
dlfunc...................................................................................................................................................102
DllLoad.................................................................................................................................................103
dlmethod ..............................................................................................................................................104
NoAutoLoad .........................................................................................................................................105
dlopen...................................................................................................................................................106

AutoLoad
AutoLoad allows for run-time symbol lookup.

Syntax
AutoLoad ("pattern", action)

Arguments
pattern
A shell style pattern.
action
An action to be taken when the pattern is matched.

Returns
The _auto_load_alist_, which is a list of all currently stored AutoLoad rules. Each rule is itself
formatted as a list. This is the _auto_load_alist_ syntax:
((pattern action_func action_arg ...) ...)

The members of each rule list are as follows:

pattern
The AutoLoad pattern parameter.
action_func
The function specified in the AutoLoad action parameter.
action_arg
The function argument(s) specified in the AutoLoad action parameter.
For example, the AutoLoad rules in AutoLoadLib.g (at the time of this writing) would be returned
as follows:
(("P[Tthg]*" DllLoad "libgammaph.so") ("gl[A-Z]*" DllLoad "libgammagl.so")
("GLUT_*" DllLoad "libgammagl.so") ("GLU_*" DllLoad "libgammagl.so")
("GL_*" DllLoad "libgammagl.so") ("ASCII_*" DllLoad "libgammamgl.so")
("KB_*" DllLoad "libgammamgl.so") ("GM_*" DllLoad "libgammamgl.so")
("EVT_*" DllLoad "libgammamgl.so") ("[mM][gG][lL]*" DllLoad "libgammamgl.so")
("[gG]tk*" DllLoad "gammagtk.so"))

Description
This function gives Gamma a way to look up symbols during run-time. If Gamma comes across an
undefined symbol while executing a program, and if the symbol matches the pattern, then Gamma
executes the action. Normally the action is either a direct definition of the symbol, or an attempt to
load a DLL that defines the symbol, using DllLoad, for example.
The available patterns are as follows:

* matches any number of characters, including zero.

[c] matches a single character which is a member of the set contained within the square brackets.

[^c] matches any single character which is not a member of the set contained within the square
brackets.
95

AutoLoad

? matches a single character.

{xx,yy} matches either of the simple strings contained within the braces.

\c (a backslash followed by a character) - matches that character.

This function is not part of the base Gamma executable. It is provided by a Gamma library
AutoLoadLib.g which can be accessed using the Gamma require function like this:
require ("/usr/cogent/require/AutoLoadLib.g");

Example
In this example, we use the ClearAutoLoad function to clear the AutoLoad list just to
make the steps easier to follow.
Once a library is loaded or a symbol is defined, Gamma no longer sends a "Looking for
symbol" message.
Notice how although NoAutoLoad and ClearAutoLoad remove a pattern from future
consideration, any symbols defined or any libraries loaded before they were called remain valid.

Gamma> require ("/usr/cogent/require/AutoLoadLib.g");

t
Gamma> ClearAutoLoad();
nil
Gamma> AutoLoad ("[gG]tk*", DllLoad ("gammagtk.so"));
(("[gG]tk*" DllLoad "gammagtk.so"))
Gamma> gtk_arg_new;
Looking for gtk_arg_new
(defun gtk_arg_new (arg_type) ...)
Gamma> gtk_main;
(defun gtk_main () ...)
Gamma> testvar;
Looking for testvar
Symbol is undefined: testvar
debug 1> (Ctrl - D)
Gamma> AutoLoad("testvar", testvar = 5);
(("testvar" setq testvar 5) ("[gG]tk*" DllLoad "gammagtk.so"))
Gamma> testvar;
Looking for testvar
5
Gamma> NoAutoLoad("testvar");
(("[gG]tk*" DllLoad "gammagtk.so"))
Gamma> testvar;
5
Gamma> ClearAutoLoad();
nil
Gamma> gtk_main;
(defun gtk_main () ...)
Gamma> gtk_false;
(defun gtk_false () ...)
Gamma>

See Also
ClearAutoLoad, NoAutoLoad, DllLoad

autoload_undefined_symbol
autoload_undefined_symbol checks undefined symbols for AutoLoad.

Syntax
autoload_undefined_symbol (!sym)

Arguments
sym
A symbol.

Returns
nil on success, else error.

Description
This function is generally used internally by the AutoLoadLib.g program. It is the default function
that is called when an undefined symbol is encountered at run-time, if the AutoLoad.g library has
been required into the program. This is normally done by startup.g, which is automatically loaded by the
Gamma executable at startup.

Example
In this example, the first symbol (test1) is checked by autoload_undefined_symbol from
within the AutoLoadLib.g program. We know this because the message "Looking for symbol"
indicates that Gamma had to use AutoLoadLib.g to get the definition of the symbol. For the second
symbol (test2), we make the autoload_undefined_symbol call ourselves, and the "Looking
for symbol" doesnt appear. This indicates that Gamma knew the value of the symbol and didnt have
to use AutoLoadLib.g to look it up.
Gamma> AutoLoad("test1", test1 = 9);
(("test1" setq test1 9) ("P[Tthg]*" DllLoad "libgammaph.so")...)
Gamma> test1;
Looking for test1
9
Gamma> AutoLoad("test2", test2 = 8);
(("test2" setq test2 8) ("test1" setq test1 9) ("P[Tthg]*" DllLoad "libgammaph.so")...)
Gamma> autoload_undefined_symbol(test2);
nil
Gamma> test2;
8
Gamma>

See Also

102

DllLoad
DllLoad loads dynamic libraries.

Syntax
DllLoad ("filename", verbose? = nil)

Arguments
filename
The name of the dynamic library to be loaded.
verbose
When set to t, shows the paths of load attempts.

Returns
An integer "handle" on success, or an error message.

Description
This function loads a DLL if the system supports it (Linux, QNX 6, and MS-Windows). The first search
path for the DLL is taken to be ./, next is /usr/cogent/dll/, and finally the system DLL search
path, if any.

Example
Without using the optional verbose parameter:
Gamma> DllLoad("gammagtk.so");
135024608
Gamma>

Using the optional verbose parameter:

Gamma> DllLoad("gammagtk.so", t);
DllLoad: attempting to load: ./gammagtk.so
DllLoad: attempting to load: /usr/cogent/dll/gammagtk.so
135024608
Gamma>

See Also

104

NoAutoLoad
NoAutoLoad removes selected AutoLoad rules.

Syntax
NoAutoLoad ("pattern")

Arguments
pattern
A shell style pattern.

Returns
The _auto_load_alist_ (a list of all currently stored AutoLoad rules) with the rules
corresponding to the pattern removed.

Description
This function removes from future consideration any AutoLoad rules that correspond to the pattern.
The available patterns are as follows:

* matches any number of characters, including zero.

[c] matches a single character which is a member of the set contained within the square brackets.

[^c] matches any single character which is not a member of the set contained within the square
brackets.

? matches a single character.

{xx,yy} matches either of the simple strings contained within the braces.

\c (a backslash followed by a character) - matches that character.

Example
See the example for AutoLoad.

V. Profiling and Debugging

Table of Contents
allocated_cells .............................................................................................................................108
eval_count .........................................................................................................................................109
free_cells .........................................................................................................................................110
function_calls................................................................................................................................111
function_runtime...........................................................................................................................112
gc.............................................................................................................................................................113
gc_blocksize.....................................................................................................................................114
gc_enable............................................................................................................................................115
gc_newblock.......................................................................................................................................116
gc_trace ..............................................................................................................................................117
profile.................................................................................................................................................118
set_autotrace ..................................................................................................................................120
set_breakpoint................................................................................................................................121
time........................................................................................................................................................122
trace, notrace................................................................................................................................123

107

allocated_cells
allocated_cells gives the number of allocated and free cells.

Syntax
allocated_cells ()

Arguments
none

Returns
A list containing the number of allocated cells and the number of free cells currently held by the memory
management system.

Description
The memory management system allocates cells as required to continue execution, limited only by
operating system memory. Once cells have been allocated, they are placed on the heap by the garbage
collector and re-used. New cells are only allocated from the operating system if the garbage collector is
unable to fulfill a request for more memory from the running Gamma or Lisp program. This function
returns the number of cells which are currently in use, and the number of free cells remaining on the
heap. The sum of these numbers is the total number of cells allocated by the interpreter.

Example
This example shows 380 cells in use and 1620 cells free on the heap, for a total of 2000 cells available.
Gamma> allocated_cells();
(380 1620 0 0 0 0 0 0)
Gamma>

Entered on command line:

[sh]$ ex_profile.g 1 2 3 4 5

Output:
The numbers in reverse order are:
(5 4 3 2 1)
Function
Calls Total Time
+++
5 4e-06
cdr
1 0
cons
5 2e-06
for
1 2.3e-05
profile
1 1e-06
setq
5 3e-06
princ
1 0.006502
print_reverse
1 0.006534
progn
6 0.006546
Function calls: 5
Function runtime: 1.9999999999999999095e-06

See Also
function_calls, function_runtime

119

set_autotrace
set_autotrace is reserved for future use.

Syntax
set_autotrace (state, functions...)

Arguments
state

functions

Returns
Description
Example

See Also

120

set_breakpoint
set_breakpoint is reserved for future use.

Syntax
set_breakpoint (state, functions...)

Arguments
state

functions

Returns
Description
Example

See Also

121

time
time gives command execution times.

Syntax
time (iterations, !command)

Arguments
iterations
The number of times to execute the command.
command
Any Gamma or Lisp command.

Returns
The number of seconds consumed performing the command for the given number of iterations.

Description
This function performs the command for the given number of iterations and returns the clock time
consumed. This does not break down the time into user and system time. Times on successive calls to this
function will differ slightly due to operating system requirements, garbage collection and active timers.

Example
Gamma> time(10, list(1,2,3));
3.297225339338183403e_05
Gamma>

122

trace, notrace
trace, notrace turn tracing on or off.

Syntax
trace (!code?)
notrace (!code?)

Arguments
code
If provided, limits the scope to this code.

Returns
With no argument, t, or with a code argument, the result of evaluating code.

Description
These functions turn tracing (execution tracking to standard output) on or off, either at the global level,
or for the duration of the evaluation of code, if provided.

Example
#!/usr/local/bin/gamma -d
/* here is an example of a troublesome function and its
return being debugged with the aid of trace() and
notrace() functions.
*/
a = 0;
b = 1;
trace();
function trouble_function(x,y) {y/x;}
results = trouble_function(a,b);
notrace();
princ(results, "\n");

Gamma generates the following:

(defun trouble_function (x y) (/ y x))
--> trouble_function
(trouble_function a b)
(/ y x)
--> inf
--> inf
(setq results (trouble_function a b))
--> inf
(notrace)
inf

123

VI. Miscellaneous
Table of Contents
apropos.................................................................................................................................................125
create_state, enter_state, exit_state ..............................................................................126
gensym...................................................................................................................................................127
modules.................................................................................................................................................128
stack .....................................................................................................................................................129

124

apropos
apropos finds all defined symbols in the current interpreter environment.

Syntax
apropos (pattern, predicate?)

Arguments
pattern
A character string which specifies a search pattern
predicate
A function taking one argument which will return either nil or non-nil.

Returns
A list of all symbols defined in the system which match the given pattern, and if the predicate is
supplied, whose values are true under that predicate.

Description
This function searches the names of all defined symbols in the currently running interpreter environment.
The pattern can contain the following special characters:

* matches any number of characters, including zero.

[c] matches a single character which is a member of the set contained within the square brackets.

[^c] matches any single character which is not a member of the set contained within the square
brackets.

? matches a single character.

{xx,yy} matches either of the simple strings contained within the braces.

\c (a backslash followed by a character) - matches that character.

The predicate is any function which accepts a single argument. If the predicate evaluates to
non-nil when given the value of a symbol, and if the symbol matches the pattern, then the symbol will
be reported by apropos. If the predicate is not supplied, then all symbols which match the pattern
will be reported. The pattern is case-sensitive.

Example
Gamma> apropos("s*", function_p);
(setq strchr string symbol)
Gamma> apropos("?[sli]{igc,er}*");
(SIGCHLD SIGCONT dlerror)

125

create_state, enter_state, exit_state

create_state, enter_state, exit_state are part of the SCADALisp exception-driven
state machine mechanism.

Syntax
create_state (state_function, symbol?...)
enter_state (state_machine, state)
exit_state (state_machine, state)

Arguments
state_function
The function to call upon entering this state.
symbol
One or more symbols which will act as triggers to cause this state to be re-evaluated.
state_machine
A state machine created through a call to (new StateMachine)
state
A state created through a call to (create-state...)

Returns
create_state: The new state definition.
enter_state: A status value.
exit_state: A status value.

Description
These functions are part of the exception-driven state machine mechanism built into SCADALisp. This
mechanism is not fully supported, and will not be documented for this release. The reader may find the
library file StateMachine.lsp helpful in determining how to use state machines. In general, this function
should not be called directly from user code, as it is designed to provide support for the StateMachine
library functions.

Example
none

126

gensym
gensym generates a unique symbol.

Syntax
gensym (prefix_string?)

Arguments
prefix_string
A character string which will be used as the prefix for the newly generated symbol.

Returns
A unique symbol.

Description
This function generates a symbol which does not currently exist by attaching a unique number to the end
of the prefix_string. If the prefix_string is nil, use a default prefix.

Example
Gamma> gensym("tag");
tag1
Gamma> gensym();
tmp_sym2
Gamma> tag3 = 1;
1
Gamma> gensym("tag");
tag4
Gamma>

127

modules
modules is obsolete, and returns nothing of value.

Syntax
modules ()

Arguments
none
nil

Returns
A string.

Description
This function is obsolete, and returns nothing of value.

128

stack
stack lists all functions called so far.

Syntax
stack ()

Arguments
none

Returns
A list of all of the functions called up to this point in the execution of the Gamma program.

Description
A function that calls stack is presented in order, with the most recently called function at the end of the
function list. stack can be useful for debugging programs by requesting a stack trace when an error
occurs.

Example
The following program:
#!/usr/cogent/bin/gamma
function hms_to_sec(hms)
{
hms = list_to_array(string_split(hms, ":", -1));
(number(hms[0]) * 60 + number(hms[1])) * 60 + number(hms[2]);
stk = stack();
}
tocheck = list(12,5,13);
hms_to_sec("tocheck");
princ(stk,"\n");

Yields these results:

((hms_to_sec tocheck) (progn (setq hms (list_to_array (string_split hms
: (neg 1)))) (+ (* (+ (* (number (aref hms 0)) 60) (number (aref hms 1)
)) 60) (number (aref hms 2))) (setq stk #0=(stack))) #0#)

taskstarted_hook: triggered whenever a task starts.

taskdied_hook: triggered whenever a task dies.

exception_hook: triggered whenever an exception for any point is emitted by the Cogent
DataHub.

echo_hook: triggered whenever an echo for any point is emitted by the Cogent DataHub.

gc_hook: triggered whenever the garbage collector runs.

The following are related to tracing code executions, but havent been fully documented.
trace_symbol_hook
trace_entry_hook
trace_exit_hook
breakpoint_hook

One common use of this function is to add the internal taskstarted or taskdied functions, with
the taskstarted_hook or taskdied_hook. Whenever a task that is registered with nserve starts
or dies, nserve sends a message to all Gamma applications running IPC. Any of these applications that
has added the taskstarted_hook or taskdied_hook then runs their corresponding
function_sym function.

Example
This example program requires qserve and nserve to be running. It gives the output shown below:
#!/usr/cogent/bin/gamma
//Program: ex_addrunhooks.g

131

add_hook

Output from ex_addrunhooks.g at startup:

Hooked task started: (testing start)
Hooked task died: (testing died)

Starting a new Gamma task named mytask...

Gamma> init_ipc("mytask", "myqueue");
t
Gamma>

...elicits this output from ex_addrunhooks.g:

Hooked task started: (mytask default myqueue 0 0 1874 0)

Checking process status with nsnames:

[home/robert]$
Name
Domain
mytask default
x
default

nsnames
Queue
myqueue
x

NID PID
0
1874
0
1873

Terminating mytask elicits this output from ex_addrunhooks.g:

Hooked task died: (mytask default myqueue 0 0 1874 0)

See Also
run_hooks, remove_hook, init_ipc

132

close_task
close_task closes a task opened by locate_task.

Syntax
close_task (task)

Arguments
task
A task descriptor as assigned to a locate_task call.

Returns
t if the task could be closed, else nil.

Description
When a task is opened (located) for interprocess communication, a communication link may be
established. This link must be cleaned up if it is to be re-used. There is no hard limit to the number of
tasks which may be open with QNX 4 message passing, but TCP/IP exerts an operating
system-dependent limit on the number of simultaneously open tasks. Tasks will automatically be closed
by the garbage collector when they are no longer referenced.

Example
Gamma> task = locate_task("Task 1",nil);
#<Task:9684>
Gamma> close_task(task);
t
Gamma>

This function should not be used under any circumstances.

134

init_async_ipc
init_async_ipc requests queue information from a task.

Syntax
init_async_ipc (other_task)

Arguments
other_task
A task descriptor as assigned to a locate_task call.

Returns
Non-nil on success, or nil on failure.

Description
This function initializes the interprocess communication system to allow this task to make calls to
register_point, register_existing_point, send_async and send_string_async.
It requests queue information from the given task. A deadlock situation could occur if two tasks attempt
to initialize asynchronous communication with one another at the same time. The queue server task,
qserve, must be running for this call to succeed.

Example
Gamma> init_ipc("mytask","mytask_q");
t
Gamma> task = locate_task("server", t);
#<Task: 32271>
Gamma> init_async_ipc(task);
t

See Also
init_ipc, locate_task, register_point, send_async, send_string_async

135

init_ipc
init_ipc sets up necessary data structures for IPC.

Syntax
init_ipc (my_name, my_queue_name?, domain?)

Arguments
my_name
A name for this task, as a string. It is only used internally.
my_queue_name
Optional queue name for this task, as a string. This is necessary for asynchronous communication,
and it must be unique on the system.
domain
Optional domain name for this task.

Returns
t on success, otherwise nil.

Description
Sets up all of the data structures needed prior to attempting any interprocess communication from this
task. Messages can be neither sent nor received before this call is made. All Cogent DataHub functions
use IPC. If the value of my_queue_name is nil, no queue name is assigned and no asynchronous IPC
is possible.

Example
Gamma> init_ipc("myname","myqueue");
t
Gamma>

See Also
isend, next_event, next_event_nb, read_point, read_existing_point,
register_point, send, send_async, send_string, send_string_async,
write_point, write_existing_point

136

isend
isend sends a synchronous message and doesnt wait for the result.

Syntax
isend (task, s_exp)

Arguments
task
A task descriptor as assigned to a locate_task call.
s_exp
Any Gamma or Lisp expression.

Returns
t if the message was sent successfully, otherwise nil.

Description
This function sends a message via synchronous interprocess communication, but does not wait for the
result. The receiving task must respond immediately, prior to actually evaluating the message that was
sent. The result code can only show whether the message was sent successfully. This is a compromise
between synchronous and asynchronous messaging techniques.

Example
Gamma> init_ipc("mytask","myqueue");
t
Gamma> task = locate_task("other_task",nil);
<task id>
Gamma> isend(task,#list(do_something));
t

would remove the taskstarted_hook.

t if the message was delivered successfully.

nil if the message could not be delivered.

An expression in the form: (error "error message") if there was an error. See error.

Description
This function constructs an ASCII string representing the s_exp and transmits it via synchronous
interprocess communication to the receiving task. The task processes the message and returns a
result based on that processing. If the task is another Gamma process, the message will be interpreted
as a Gamma expression and evaluated. The return value will be the result of that evaluation.

Example
Task 1:
Gamma> init_ipc ("a","a");
t
Gamma> tsk = locate_task("b",nil);
#<Task:9751>
Gamma> send(tsk, #princ("hello\n"));
hello
t
Gamma> send_async(tsk, #princ(cos(5), "\n"));
t
Gamma> send(tsk, #princ("goodbye\n"));
t
Gamma>

Task 2:
Gamma> init_ipc ("b","b");
t
Gamma> while(t) next_event();
hello
0.28366218546322624627
goodbye

145

send

See Also
isend, locate_task, send_async, send_string, send_string_async

146

send_async
send_async transmits expressions asynchronously.

Syntax
send_async (task, s_exp)

Arguments
task
A task descriptor as assigned to a locate_task call.
s_exp
Any Gamma or Lisp expression.

Returns
t if the message was successfully delivered, otherwise nil.

Description
This function constructs a string representation of the given expression and delivers it via asynchronous
interprocess communication to the receiving task. If the message could not be delivered, send_async
returns nil. There is no indication of the status of the receiving task as a result of processing the
message.

Example
Task 1:
Gamma> init_ipc ("a","a");
t
Gamma> tsk = locate_task("b",t);
#<Task:9751>
Gamma> send_async(tsk, #princ("hello, b\n"));
t
Gamma> send_async(tsk, #princ(cos(5), "\n"));
t
Gamma>

Task 2:
Gamma> init_ipc ("b","b");
t
Gamma> while(t) next_event();
hello, b
0.28366218546322624627

See Also
isend, locate_task, send, send_string, send_string_async

147

send_string
send_string transmits strings for evaluation.

Syntax
send_string (task, string)

Arguments
task
A task descriptor as assigned to a locate_task call.
string
Any string.

Returns
A result depending on the receiving task.

Description
This function transmits the string via synchronous interprocess communication to a non-Cogent
DataHub receiving task. The task processes the message and returns a result based on that
processing. If the task is a Gamma process, the message will be interpreted as a Lisp expression and
evaluated. The return value will be the result of that evaluation. If an error occurs during the evaluation,
an expression of the form: (error "error message") will be returned. If the message could not be
delivered, nil is returned.

Example
Gamma> a = 5;
5
Gamma> b = 6;
5
Gamma> send_string(task,string("(+",a," ",b,")"));
11

See Also
isend, locate_task, send, send_async, send_string_async

148

send_string_async
send_string_async transmits a string asynchronously.

Syntax
send_string_async (task, string)

Arguments
task
A task descriptor as assigned to a locate_task call.
string
A string.

Returns
t if the message was successfully delivered, otherwise nil.

Description
This function delivers the string via asynchronous interprocess communication to a non-Cogent
DataHub receiving task. If the message could not be delivered, send_string_async returns nil.
There is no indication of the status of the receiving task as a result of processing the message.

Example
Task 1:
Gamma> init_ipc ("a","a");
t
Gamma> tsk = locate_task("b",t);
#<Task:9751>
Gamma> send_string_async(tsk, "2 + 2");
t
Gamma> send_string_async(tsk,string(list(#a,#b,#c)));
t
Gamma>

Task 2:
Gamma> init_ipc ("b","b");
t
Gamma> while(t) next_event();

See Also
isend, locate_task, send, send_async, send_string

149

taskdied, taskstarted
taskdied, taskstarted internal functions that call another function when a task starts or
stops.

Syntax
taskdied (task_name, qname, domain, node, task_id)
taskstarted (task_name, qname, domain, node, task_id)

Arguments
task_name
The name of the task which started or stopped.
node
The node on which the task started or stopped.
task_id
The process ID for the task.
qname
The name of the tasks queue, if any.
domain
The Cogent DataHub domain for this task.

Returns
User-defined.

Description
These functions are internal to Gamma. They call run_hooks (#taskstarted_hook,
args...) and run_hooks (#taskdied_hook, args...) respectively. They are called
whenever a task registered with the Cascade NameServer (nserve) starts or stops. You can set up hooks
to use these functions through the add_hook function.

150

taskdied, taskstarted

These functions were originally available to programmers, and have been internalized to allow
for the greater flexibility of the add_hook and run_hook functions. However, if you have
existing code that you dont want to change, you can define your own versions of taskdied
and taskstarted that shadow the built-in functions and do what they always used to do. Your
old code will not break, but it will hide the hook version of the taskdied and taskstarted
functions.
On the other hand, you could get both with something like this:
builtin_taskdied = taskdied;
builtin_taskstarted = taskstarted;
function main ()
{
init_ipc ("x","x");
add_hook (#taskdied_hook, #hook_taskdied);
add_hook (#taskstarted_hook, #hook_taskstarted);
while(t)
next_event();
}
function taskdied (!a?...=nil)
{
princ ("task died: ", a, "\n");
funcall (builtin_taskdied, a);
}
function taskstarted (!a?...=nil)
{
princ ("task started: ", a, "\n");
funcall (builtin_taskstarted, a);
}
function hook_taskdied (!a?...=nil)
{
princ ("hook task died: ", a, "\n");
}
function hook_taskstarted (!a?...=nil)
{
princ ("hook task started: ", a, "\n");
}

151

task_info
task_info gets information from a task descriptor.

Syntax
task_info (tsk)

Arguments
tsk
A task descriptor, as returned by the locate_task function.

Returns
An instance of the class TaskInfo, or nil on failure.

Description
This function returns an instance of Gammas TaskInfo class. The instance variables of this class
correspond to information contained in the task descriptor, as follows:

channel_id
The channel ID number, which is used in QNX 6 but not in QNX 4 or Linux.
domain
The name of the Cogent DataHub domain for the tsk.
name
The name of the tsk, as recorded in the Cascade NameServer. This attribute is not contained in a
task descriptor, and thus is always returned as nil from this function.
node_id
The node ID number.
node_name
The node_id expressed as a string.
pid
The process ID number.
queue_name
The name of the Cascade QueueServer queue, as registered with the Cascade NameServer.
queue_size
The size of the Cascade QueueServer queue.

152

task_info

Example
Gamma> init_ipc("a", "aq");
t
Gamma> tsk = locate_task("/dh/toolsdemo", nil);
#>Task:5394<
Gamma> task_info(tsk);
{TaskInfo (channel_id . 0) (domain . "toolsdemo") (name)
(node_id . 0) (node_name . "0") (pid . 5394)
(queue_name . "/dh/toolsde") (queue_size . 0)}
Gamma>

VIII. Events and Callbacks

Table of Contents
add_set_function...........................................................................................................................155
flush_events.....................................................................................................................................157
next_event, next_event_nb ........................................................................................................158
remove_set_function....................................................................................................................159
when_set_fns.....................................................................................................................................160

154

add_set_function
add_set_function sets an expression to be evaluated when a given symbol changes value.

Syntax
add_set_function (symbol, s_exp)

Arguments
symbol
A symbol.
s_exp
Any Gamma or Lisp expression.

Returns
t

Description
This function binds an expression to be evaluated whenever the value of the symbol changes. This
expression is available globally, so if the value of the symbol changes during a change in scope, the
expression will be evaluated. All changes in that sub-scope will trigger new evaluations of the
expression. This can be used to automatically maintain consistency between the program and a the
Cogent DataHub, or to implement forward chaining in calculation rules. The expression will not be
evaluated if the new value is eq to the previous value.
When a set expression (the s_exp) is being evaluated the special variables this, value and
previous are all bound:

this The symbol whose value has changed.

value The current value of this as a result of the change.

previous The value of this immediately prior to the change.

Example
Gamma> b = 5;
5
Gamma> add_set_function(#b,#princ("changed\n"));
(princ "changed\n")
Gamma> b = 4;
changed
4
Gamma>

The following code automatically sounds an alarm whenever a computed_tank_level rises above
10000 and silences the alarm whenever it drops below 10000. The Cogent DataHub is automatically
updated to maintain the same value as the Gamma task.
function send_to_datahub (point)
{
write_point(point, value);
}
function check_alarm (value)

155

add_set_function

{
if (value == 1)
sound_alarm();
else
silence_alarm();
send_to_datahub(this);
}
function check_tank_level (depth)
{
if (depth > 10000)
high_alarm = 1;
else
high_alarm = 0;
send_to_datahub(this);
}
add_set_function(#high_alarm, #check_alarm(high_alarm));
add_set_function(#computed_tank_level,#check_tank_level(computed_tank_level));

See Also
when_set_fns, remove_set_function

156

flush_events
flush_events handles all pending events, then exits.

Syntax
flush_events ()

Arguments
none

Returns
The result of executing all pending events, then exits.

Description
This function ensures that an appropriate event-handling function is called to handle all pending events
from: a window system (where applicable), other tasks (interprocess communication messages), timers,
or signals. Upon completion, flush_events causes the program to exit.

Example
Gamma> flush_events();
(the result of any pending events)
[/user/cogent/bin]$

IX. Time, Date, and Timers

Table of Contents
after .....................................................................................................................................................162
at.............................................................................................................................................................163
block_timers, unblock_timers.................................................................................................165
cancel...................................................................................................................................................166
clock, nanoclock..............................................................................................................................167
date........................................................................................................................................................168
date_of.................................................................................................................................................169
every .....................................................................................................................................................170
gmtime...................................................................................................................................................171
localtime............................................................................................................................................173
mktime...................................................................................................................................................175
timer_is_proxy................................................................................................................................176

161

after
after a timer that initiates an action after a period of time.

Syntax
after (seconds, action...)

Arguments
seconds
A number of seconds, which may be fractional.
action
One or more statements to be executed. This argument is evaluated, so literal statements must be
quoted.

Returns
An integer timer number which may be used as the argument to cancel.

Description
This function specifies an action to be performed after a given period of time in seconds has elapsed. The
number of seconds may be specified to arbitrary precision, but will be limited in fact by the timer
resolution of the operating system. In most cases this is practically limited to 20 milliseconds (0.05
seconds).
The timer functions after, every and at all cause an action to occur at the specified time, regardless
of what is happening at that time, except if the timer expires during garbage collection. In this case, the
timer will be serviced as soon as the garbage collection finishes.
For Gamma to notice a timer, you must make a call to next_event.

Example
Gamma> after(30, #princ("Times up!\n"));
1
Gamma> next_event();
(30 seconds pass)
Times up!
nil
Gamma>

See Also
at, every, cancel, _timers_ in Predefined Symbosl

162

at
at a timer that initiates an action at a given time, or regularly.

Syntax
at (day, month, year, hour, minute, second, actions...)

Arguments
day
Restriction on the day of the month (1-31), or nil for none.
month
Restriction on the month of the year (1-12), or nil for none.
year
Restriction on the year (1994-2026), or nil for none.
hour
Restriction on the hour of the day (0-23), or nil for none.
minute
Restriction on the minute in the hour (0-59), or nil for none.
second
Restriction on the second in the minute (0-59), or nil for none.
actions
The actions to perform when the specified time arrives.

Returns
An integer number which may be used as the argument to cancel.

Description
This function specifies an action to be performed at a given time, or to occur regularly at certain times of
the minute, hour, day, month or year. A restriction on a particular attribute of the time will cause
at to fire only if that restriction is true.
A restriction may be any number in the legal range of that attribute, or a list of numbers in that range.
Illegal values for the time will be normalized. For example, a time specified as July 0, 1994 00:00:00 will
be treated as June 30, 1994 00:00:00. If nil is specified for any attribute of the time, this implies no
restriction and at will fire cyclically at every legal value for that attribute.
For Gamma to notice a timer, you must make a call to next_event. To notice repeating timers, the call
to next_event can be used with a call to while(t).

Example
//To print "hello" at 12:00 noon on June 2, 1994:
at(2,6,1994,12,0,0,#princ("hello\n"));
//To print "hello" at 12:00 noon on the first day
//of every month in 1994:
at(1,nil,1994,12,0,0,#princ("hello\n"));

163

//To print "hello" every half minute at 30 seconds

//and on the minute on the 1st and 15th of every month
//except July and August, for any year:
at(list(1,15), list(1,2,3,4,5,6,9,10,11,12),list(0,30), #(princ "hello\n"));
//To print "hello" every 10 seconds during the hour
//of 3:00pm every December 21st.
at(21,12,nil,15,nil,list(0,10,20,30,40,50), #princ("hello\n"));

See Also
after, every, _timers_ in Predefined Symbosl

164

block_timers, unblock_timers
block_timers, unblock_timers block and unblock timer firing.

Syntax
block_timers ()
unblock_timers ()

Arguments
none

Returns
t

Description
Timers are potentially handled by a different mechanism from operating system signals. It may be
desirable to block all timers from firing for the duration of an operation, which may not be possible using
the block_signal mechanism. If a timer fires while timers are blocked, the timer function will be
called as soon as timers are unblocked. This will not delay subsequent timers.
For example, if a timer is intended to fire every 5 seconds at 5, 10, ... seconds after the minute and the
5-second timer is blocked until second 7, the next timer in the sequence will still fire at 10 seconds. If the
5-second timer were blocked until second 27, then the 5, 10, 15, 20 and 25-second timers would all fire
at second 27 and the next timer would fire at second 30. Code which blocks timers should be surrounded
by a call to unwind_protect.

Example
Gamma> block_timers();
t
Gamma> protected_function();
<function return>
Gamma> unblock_timers();
t

See Also
block_signal, unblock_signal, after, at, every, _timers_ in Predefined Symbosl

165

cancel
cancel removes a timer from the set of pending timers.

Syntax
cancel (timer_number)

Arguments
timer_number
An integer number returned from a call to after, at or every.

Returns
The complete timer definition for the canceled timer, or nil if no timer was canceled.

Description
Removes a timer from the set of pending timers based on its unique timer ID as returned by the function
which created the timer. If no timer could be found with the corresponding timer number, nothing
happens.

Example
To set a timer to repeat every 5 seconds, then stop it:
Gamma> every(5, #princ("hello\n"));
1
Gamma> cancel(1);
[945884155 683256506 5 ((princ "hello\n")) 1]
Gamma>

this The symbol which received the exception.

value The current value of this as a result of the exception.

previous The value of this immediately prior to the exception.

Example
Gamma> add_exception_function(#temp, #princ("temp change\n"));
(princ "temp change\n")
Gamma> add_echo_function(#temp,nil);
nil
Gamma> next_event();
temp change
(t)
Gamma> read_point(#temp);
30
Gamma> write_point(#temp,25);
t
Gamma> next_event();

178

add_exception_function, add_echo_function

(nil)
Gamma>

See Also
register_point, when_echo_fns, when_exception_fns, remove_echo_function,
remove_exception_function

179

lock_point
lock_point locks or unlocks points.

Syntax
lock_point (symbol, locked)

Arguments
symbol
A point name, as a symbol.
locked
t to set a lock, nil to release a lock.

Returns
t if the function is successful, otherwise nil.

Description
This function locks or unlocks a point in the Cogent DataHub. The current security level must be greater
than or equal to the security level on the point.

Example
Gamma>
t
Gamma>
t
Gamma>
t
Gamma>
nil
Gamma>
t
Gamma>
t
Gamma>

init_ipc("locker","lq");
write_point(#a,5);
lock_point(#a,t);
write_point(#a,300);
lock_point(#a,nil);
write_point(#a,300);

See Also

187

register_point, register_existing_point
register_point, register_existing_point register an application to receive
exceptions for a single point.

Syntax
register_point (symbol)
register_existing_point (symbol)

Arguments
symbol
A point name, as a symbol.

Returns
The current value of the point in the Cogent DataHub. If the point does not exist, register_point
will create the point in the DataHub and return a default value. However
register_existing_point will return nil if the point does not exist.

Description
These functions register an application to receive changes in the value of a point whenever they occur.
The current value of the point is returned as a result of the registration. Once this function has been
called, any changes to the value of the point in the DataHub will be transmitted to the input queue of the
application. These changes are events, and as such must be processed by calling next_event or
next_event_nb before the application will recognize the new value of the point.
A function may be attached to the value change event using the when_exception and when_echo
functions. Regardless of whether an event is attached to the point, the interpreter will update the value of
the symbol whose name is the same as the point name. This means that once a point has been registered
its value will always be current in the global scope of the interpreter. If the point name is pre-qualified
with a domain name and a colon (:), this function will search that domains data rather than the DataHub
for the default domain.

Example
Gamma>
26
Gamma>
t
Gamma>
26
Gamma>
nil
Gamma>
85
Gamma>
nil
Gamma>
0
Gamma>
0

register_point(#f);
write_point(#f,85);
f;
next_event();
f;
register_existing_point(#newpoint);
register_point("newpoint");
register_point("acme:newpoint");

188

register_point, register_existing_point

See Also
init_ipc, next_event, next_event_nb, when_echo, when_exception

189

remove_echo_function
remove_echo_function removes an echo function from a symbol.

Syntax
remove_echo_function (symbol, echo_fn)

Arguments
symbol
The point name, as a symbol, from which to remove the echo function.
echo_fn
The echo function body.

Returns
The echo function which was removed, or nil if no function was removed.

Description
This function removes an echo function (Cogent DataHub echo handler) from the symbol. The
echo_fn is compared to all of the current echo functions for the symbol using the comparison
function eq.

Example
Gamma>
(princ
Gamma>
t
Gamma>
echo
(t t)
Gamma>
(princ
Gamma>
t
Gamma>
(t)
Gamma>

add_echo_function(#temp,#princ("echo\n"));
"echo\n")
write_point(#temp,28);
next_event();

remove_echo_function(#temp,#princ("echo\n"));
"echo\n")
write_point(#temp,32);
next_event();

Returns immediately with as many bytes as are currently available

(up to nchars bytes).

Return with up to nchars bytes only when at least M bytes are

available.

Return with up to nchars bytes when at least one byte is available,

or T * 0.1 sec has expired.

Return with up to nchars bytes when either M bytes are available or

at least one bytes has been received and the inter-byte time between
any subsequently received characters exceeds T * 0.1 sec.

Reserved.
201

dev_read

min

time

timeout

Description

Return with up to nchars bytes when t * 0.1 sec has expired, or M

bytes are available.

Reserved.

Return with up to nchars when M bytes are available, or t * 0.1 sec

has expired and no characters are received, or at least one byte has
been received and the inter-byte time between any subsequently
received characters exceeds T * 0.1 sec.

Reserved.

Return with up to nchars when M bytes are available, or t * 0.1 sec

has expired and no characters are received, or at least one byte has
been received and the inter-byte time between any subsequently
received characters exceeds T * 0.1 sec.

If an error occurs the errno is set. The following error constants are relevant:

EAGAIN The O_NONBLOCK flag is set on the devno.

EBADF The devno argument is invalid or not open for read

EINTR The function was interrupted by a signal

EIO The process cannot read data from the devno

ENOSYS This function is not supported for the given devno

Example
Gamma> id = dev_open("/dev/ser1",O_RDWR);
4
Gamma> x = dev_read(id,5,1,0,100);
#[104 101 108 108 111]
Gamma> buffer_to_string(x);
"hello"

PROT_EXEC The region can be executed.

PROT_NOCACHE Disable caching of the region (use for dual port RAM).

PROT_NONE The region cannot be accessed.

PROT_READ The region can be read.

PROT_WRITE The region can be written.

The share_flags specify the handling of the memory region. Valid share_flags are bitwise
OR-ed combinations of:

MAP_PRIVATE Changes are private.

MAP_SHARED Share changes.

Remember to require the "const/mman.lsp" file before using these constants.

Possible errors when using this function are:

205

mmap

EACCES The shm_file is not open for the correct mode

EAGAIN The mapping could not be locked in memory due to a lack of resources

EBADF The passed shm_file is bad.

EINVAL The prot_flags of share_flags argument is invalid

ENODEV The shm_file arg refers to an argument for which mmap is meaningless

ENOMEM The mapping could not be locked because it would require more space than the system is
able to supply

ENOSYS The function mmap is not supported by this implementation

ENOTSUP MAP_PRIVATE was specified but the implementation does not support this functionality

ENXIO The offset or size arguments are invalid.

cpu processor type, typically given as the last 3 digits (386,486,586,686,etc.)

cpu_speed a measure of the CPU speed using a 16-bit algorithm. A classic PC/XT is 96. A 133MHz
Pentium is approx. 18000-19000.

fpu the floating point processor type given as the last 3 digits of the chip (387,487,587,687,etc.)

freememk free memory in the system

machine machine name

max_nodes the number of nodes you are licensed for

nodename logical node numberof this cpu

num_handlers maximum number of interrupt handlers

num_names maximum number of names

num_procs mamimum number of processes (programs + virtual curcuits + proxies)

num_sessions maximum number of sessions

num_timers maximum number of timers

pidmask process ID bit mask

release a single number that is the ASCII equivalent of the release letter. Use char() function to
convert.

reserve64k Relocation offset

sflags System flags, see below

tick_size tick size, in microseconds

timesel segment in which the time is kept

211

qnx_osinfo

totmemk total memory (kB) in the system

version the QNX 4 version number * 100

The following system flags are available: nil

_PSF_PROTECTED The system is running in protected mode

_PSF_NDP_INSTALLED An 80x87 numeric processor is installed

_PSF_EMULATOR_INSTALLED An 80x87 emulator is running

_PSF_EMU16_INSTALLED The 16-bit 80x87 emulator is running

_PSF_EMU32_INSTALLED The 32-bit 80x87 emulator is running

_PSF_APM_INSTALLED Advanced Power Management is running in the BIOS of this system

_PSF_32BIT_KERNEL This system is running with a 32 bit kernel

_PSF_PCI_BIOS This system has a PCI BIOS

_PSF_32BIT Proc32 is running

_PSF_RESERVE_DOS The lower 640k is reserved for DOS

_PSF_RESERVE_DOS32 ???

Example
Gamma> sin = qnx_osinfo(0);
<instance of Osinfo class>
Gamma> char(sin.bootsrc);
"H"
Gamma> sin.cpu;
586
Gamma> sin.cpu_speed;
18883
Gamma> sin.freememk;
18260
Gamma> sin.machine;
"PCI"
Gamma> sin.max_nodes;
34
Gamma> sin.nodename;
2
Gamma> sin.num_handlers;
64
Gamma> sin.num_names;
100
Gamma> sin.num_procs;
500
Gamma> sin.num_sessions;
64
Gamma> sin.num_timers;
125
Gamma> sin.pidmask;
511
Gamma> char(sin.release);
"G"
Gamma> sin.reserve64k;
0
Gamma> sin.ticksize;
9999
Gamma> sin.totmemk;
32384
Gamma> sin.version / 100;
4.23
//These examples use loaded constants.

Any return value greater

212

qnx_osinfo

//than zero indicates a positive result.

require_lisp("const/QNXOS");
Gamma> sin.sflags & _PSF_PROTECTED;
1
Gamma> sin.sflags & _PSF_NDP_INSTALLED;
2
Gamma> sin.sflags & _PSF_EMULATOR_INSTALLED
0
Gamma> sin.sflags & _PSF_RESERVE_DOS
0

EAGAIN No process entries free to make a proxy.

EINVAL The proxy message exceeds the maximum.

ENOMEM The process manager doesnt have enough memory to hold the message.

ESRCH The process ID (pid) does not exist.

Example
Examples of this function are beyond the scope of this documentation.

EPERM This task is not the owner of the proxy.

ESRCH The proxy does not exist.

Example
Examples of this function are beyond the scope of this documentation.

EINVAL Invalid proxy.

EPERM Proxy does not belong to task specified.

ESRCH Proxy does not exist.

Example
Examples of this function are beyond the scope of this documentation.

See Also
qnx_trigger qnx_rem_proxy_detach

217

qnx_proxy_rem_detach
qnx_proxy_rem_detach removes a remote proxy.

Syntax
qnx_proxy_rem_detach (node, proxyid)

Arguments
node
The node of the remote proxy.
proxyid
The proxy ID number of the remote proxy.

Returns
0 upon success, else -1.

Description
This function removes a remote proxy. When a task dies, all remote proxies attached to it will
automatically be detached.
In case of error, the following errnos are possible:

EINVAL Invalid proxy.

EPERM Proxy does not belong to task specified.

ESRCH Proxy does not exist.

Example
Examples of this function are beyond the scope of this documentation.

EFAULT invalid buffer size

EINTR the function call was interrupted by a signal

ESRCH the process ID does not exist

Example
Examples of this function are beyond the scope of this documentation.

See Also
qnx_send, qnx_reply, send, send_async, next_event, next_event_nb, PtMainLoop

219

qnx_reply
qnx_reply replies to qnx_receive messages.

Syntax
qnx_reply (taskid, message)

Arguments
taskid
The task which will get the reply.
message
A string containing the reply.

Returns
Returns zero on success and -1 on failure. Errno is set on error.

Description
The qnx_reply function is a wrap of the C function Reply. Any message that you receive using the
qnx_receive function should be replied to. This function should only be used if you are also using
qnx_receive. The event handling functions next_event, next_event_nb, and PtMainLoop
are the preferred choice for Gamma programs since that automatically handle receiving, replying, and
signal, timer, Cogent DataHub events, and Photon messages.
The errno possile values for this function are:

EAGAIN Out of queue packets to network manager

EFAULT Invalid message

EINTR Function call interrupted by signal

EINVAL invalud virtual circuit buffer

ENOMEM not enough memory for operation

ESRCH the process ID does not exist

Example
Examples of this function are beyond the scope of this documentation.

See Also
qnx_send, qnx_receive, send, send_async, next_event, next_event_nb,
PtMainLoop

220

qnx_send
qnx_send implements QNX 4 Send.

Syntax
qnx_send (taskid, message)

Arguments
taskid
The task to whom the message is sent.
message
The message, as a string, to send.

Returns
Returns a reply message character string from the recipient task. On an error this function returns nil
and sets errno.

Description
This function implements the QNX 4 Send function. The reply is returned as a character string.
Possible values of errno are:

EAGAIN No queue packets available for network manager

EFAULT invalid message

EHOSTUNREACH Destination node not in the netmap, or physical I/O error has occurred

EINTR The function was interrupted by a signal

EINVAL invalid message length

ENOMEM not enough memory available for operation

ESRCH the process ID does not exist

Example
Examples of this function are beyond the scope of this documentation.

See Also
qnx_reply, qnx_receive, send, send_async, next_event, next_event_nb,
PtMainLoop

221

qnx_spawn_process
qnx_spawn_process is an implementation of the C function qnx_spawn.

Syntax
qnx_spawn_process (exec, node, priority, scheduler,
flags, program, arg_list, file_list, ctfile)

Arguments
exec
If non-nil, then execute the process, otherwise spawn a separate task.
node
The node on which to spawn, or zero for the current node.
priority
The scheduler priority of the new task.
scheduler
the scheduler algorithm for the new task.
flags
The spawn flags.
program
The program name.
arg_list
Arguments to the program, as a list, excluding the program name.
file_list
A list of up to 10 files to be associated with the first 10 file descriptors of the new process. If any
element in the list is a non-file, then use the corresponding file descriptor in the current process. A
nil file-list indicates that all 10 file descriptors will be inherited from the calling task.
ctfile
A file associated with the controlling terminal for the new process.

Returns
The task ID of the new task, or -1 if an error occurs, and the errno is set.

Description
This is an implementation of the qnx_spawn C function. It is currently only available in QNX 4. This
is the lowest level function for creating a new process.
Passing -1 to the priority option will cause the new task to inherit its priority from the parent, otherwise a
value from 1-31 is acceptable.
Passing -1 to the scheduler option will cause the new task to inherit its scheduler activities from the
parent, otherwise the following flags are defined for the scheduler option:

SCHED_FIFO First-in, First-Out scheduling algorithm.

222

qnx_spawn_process

SCHED_RR Round-robin scheduling algorithm.

SCHED_OTHER Adaptive scheduling.

The following spawn flags are defined for the flags option:

_SPAWN_BGROUND The process will be started with SIGINT and SIGQUIT ignored.

_SPAWN_DEBUG The process will be started with the single step flag set. Rarely used.

_SPAWN_HOLD The process will be started in a STOPPED state.

_SPAWN_NEWPGRP The new process will start a new process group.

_SPAWN_NOHUP The process will be started with SIGHUP ignored

_SPAWN_NOZOMBIE When the new process terminates it will not become a zombie waiting for its
father to do a wait on its death. The parent process will not see the child process die and a SIGCHILD
will not be set.

_SPAWN_SETSID The new process will start a new session.

_SPAWN_SIGCLR The new process will not inherit ignored signals from its parent.

_SPAWN_TCSETPGRP The new process will start a new terminal group. ALL keyboard breaks will
be directed a it.

_SPAWN_XCACHE Instruct the file system to place the executable in cache in hopes that it will be
loaded again soon.

The library "const/QNXOS" should be required to use these constants

Errors that can happen when using this function:

E2BIG The sum of the bytes used by the new process images argument list and environment is too
big.

EACCES No permissions to execute program.

EAGAIN No free process entries or local memory.

EINVAL The priority or the scheduling policy is invalid.

ENAMETOOLONG The length of the program name, expanded to its full path, is too long.

ENOENT The program does not exist.

ENOEXEC The program is not the correct format (not an executable).

ENOLIC Insufficient licenses to use this function.

ENOMEM Not enough system memory.

ENONDP The program needs an 80x87. A co-processor is not installed and the emulator (emu87) is
not running.

ETXTBUSY The program to launch is open for write (busy).

The ctfile is a file descriptor associated with the new process. This parameter is only meaningful if the
_SPAWN_SETID flag is set. If you wish to start a new session without a controlling terminal then pass
-1.

Example
Examples of this function are beyond the scope of this documentation.
223

qnx_spawn_process

_VC_AT_SHARE Use an existing virtual circuit, if it exists.

_VC_AT_REM_ZOMBIE The remote virtual circuit id (vid) will become a zombie process when the
remote process ID terminates.

Possible values for errno are:

EAGAIN Proc to Net enqueuing failed

EHOSTUNREACH Destination node not in netmap or physical I/O error

EINVAL buffer too big

ENOLIC no license to communicate with this node

ENOMEM not enough memory to complete operation

ENOVPE not enough proc entries to new vc

ENOSYS no Net manager found

ESRCH process ID not valid

226

qnx_vc_attach

Example
Examples of this function are beyond the scope of this documentation.

See Also
qnx_vc_name_attach, qnx_send, send, send_async

227

qnx_vc_detach
qnx_vc_detach detaches a virtual circuit.

Syntax
qnx_vc_detach (taskid)

Arguments
taskid
The task id returned by qnx_vc_attach.

Returns
t on success, nil on failure, with errno set.

Description
This function detaches a virtual circuit previously attached with qnx_vc_attach or
qnx_vc_name_attach.
Possible values for errno are:

EAGAIN Proc to Net enqueuing failed

ESRCH pid not valid

EPERM the vid is not your to detach nil

Example
Examples of this function are beyond the scope of this documentation.

See Also
qnx_vc_attach, qnx_vc_name_attach

228

qnx_vc_name_attach
qnx_vc_name_attach attaches a virtual circuit with a name instead of a process ID number.

Syntax
qnx_vc_name_attach (node, max_msg_length, name)

Arguments
node
The node for the attachment.
max_msg_length
The maximum message size which will be passed between tasks.
name
The name of the task to attach.

Returns
Virtual circuit ID on success, -1 on failure, with errno set.

Description
This function performs the same operation as qnx_vc_attach except that a name attached with
qnx_name_attach can be specified instead of a process ID number. The function is currently only
available in QNX 4.
Possible errno values are: