Summary Documentation: Loadable C Functions

Icon version 9.5.20f These functions are built using the macro definition file icall.h, then combined using the UNIX shell script mklib.sh to make a loadable library. For more information about dynamically loaded C functions, see Loading C Functions in Icon.

bitcount.c: Function to count bits in an integer

bitcount(i) returns the number of bits that are set in the integer i.
It works only for "normal" integers, not large integers.

[ Full documentation | Source code ]


external.c: Functions to demonstrate Icon external values

These functions demonstrate the use of external values.

extxmin()    creates a minimal external type
extxstr(s)   creates an external hold a string and trivial checksum
extxreal(r)  creates a fully customized external type holding a real value

[ Full documentation | Source code ]


files.c: Functions to manipulate file attributes

chmod(filename, mode) changes the file permission modes of a file to
those specified.

umask(mask) sets the process "umask" to the specified value.
If mask is omitted, the current process mask is returned.

[ Full documentation | Source code ]


fpoll.c: Function to poll file for input

fpoll(f, msec) waits until data is available for input from file f,
and then returns.  It also returns when end-of-file is reached.
If msec is specified, and no data is available after waiting that
many milliseconds, then fpoll fails.  If msec is omitted, fpoll
waits indefinitely.

[ Full documentation | Source code ]


ilists.c: Icon-to-C interface for simple Icon lists

This file provides three procedures for translating homogeneous
lists of integers, reals, or strings to C arrays:

    IListVal(d) returns an array of C ints.
    RListVal(d) returns an array of C doubles.
    SListVal(d) returns an array of C char pointers (char *).

[ Full documentation | Source code ]


internal.c: Functions to access Icon internals

These functions provide some access to the internal machinery of the
Icon interpreter.  Some knowledge of the interpreter is needed to use
these profitably; misuse can lead to memory violations.

dword(x)             return d-word of descriptor
vword(x)             return v-word of descriptor
descriptor(d,v)      construct descriptor from d-word and v-word
peek(addr,n)         return contents of memory as n-character string
                     (if n is omitted, return Icon integer at addr)
spy(addr,n)          return string pointer to memory, without copying

[ Full documentation | Source code ]


lgconv.c: Function to convert large integer to string

lgconv(I) converts a large integer into a string using a series of BCD
adds.  (In contrast, the Icon built-in string() function accomplishes
the same conversion using a series of divisions by 10.)

lgconv is typically 50% to 75% faster than string() on a Sun or Alpha.
For some reason it is as much as 125% SLOWER on a SGI 4/380.

lgconv(I) works for all integer values of I.  Small integers are
simply passed to string() for conversion.

[ Full documentation | Source code ]


osf.c: Function to return OSF system table value

osftable(id, index, len) returns one element from an OSF table() call.
This function is for the OSF operating system, and fails on other systems.

See "man table" for a detailed description of the "table" system call
and the formats of the structures returned; see /usr/include/table.h
for a list of allowed ID values.

Defaults: index    0
          len    100

[ Full documentation | Source code ]


pack.c: Functions to pack and unpack binary data

s := pack(value, flags, width)
x := unpack(string, flags)

Flag characters are as follows:

   l -- little-endian [default]
   b -- big-endian
   n -- host platform's native packing order

   i -- integer [default]
   u -- unsigned integer
   r -- real (host platform's native float or double format)

The default width is 4.

Integer values must fit in a standard Icon integer (not large integer).
Consequently, a word-sized value cannot have the high bit set if unsigned.
Floating values can only be converted to/from a string width matching
sizeof(float) or sizeof(double).

Size/type combinations that can't be handled produce errors.
Valid combinations produce failure if the value overflows.

Some of this code assumes a twos-complement architecture with 8-bit bytes.

[ Full documentation | Source code ]


ppm.c: Functions to manipulate PPM files in memory

These functions manipulate raw (P6) PPM image files in memory.
The images must not contain comment strings.

ppmwidth(s) -- return width of PPM image.
ppmheight(s) -- return height of PPM image.
ppmmax(s) -- return maximum value in PPM header.
ppmdata(s) -- return data portion of PPM image.

ppmimage(s,p,f) -- quantify image s using palette p, with flags f.
   Returns an Icon image string.  Flag "o" selects ordered dithering.
   Defaults:  p="c6",  f="o"

ppmstretch(s,lo,hi,max) -- apply contrast stretch operation
   Returns a PPM string image that results from setting all
   values <= lo to zero, all values >= hi to max, with values
   between scaling linearly.  If hi = lo + 1, this becomes a
   simple threshold operation.  If lo=0 and hi=ppmmax(s), this
   simply scales an image to a new maximum.

   Requirements: 0 <= lo < hi <= ppmmax(s), 1 <= max <= 255.
   Defaults:   lo=0, hi=ppmmax(s), max=255.

ppm3x3(s,a,b,c,d,e,f,g,h,i) -- apply 3x3 convolution to PPM image.
   The matrix of real numbers [[a,b,c],[d,e,f],[g,h,i]] is used
   as a transformation matrix applied independently to the three
   color components of the image.

[ Full documentation | Source code ]


process.c: Functions to manipulate UNIX processes

kill(pid, signal)    kill process (defaults: pid=0, signal=SIGTERM)
getpid()             return process ID
getuid()             return user ID
getgid()             return group ID

[ Full documentation | Source code ]


tconnect.c: Function to open TCP connection

tconnect(hostname, portnum) establishes a TCP connection to the given
host and port, returning an Icon file f.

Note that seek(f) must be called when switching between input and output
on this bidirectional file.  Additionally, the DEC Alpha requires a call
to flush(f), after the seek, when switching from input to output.

[ Full documentation | Source code ]


Program Library Page | Icon Home Page