Daylight v4.9
Release Date: 1 February 2008


dt_alloc_program - allocate a new program object

Generic Prototype

dt_alloc_program(dt_Handle) => dt_Handle

C Prototype

#include "dt_progob.h"

dt_Handle dt_alloc_program(dt_Handle args)

FORTRAN Prototype

include ''

integer*4 dt_f_alloc_program(args)

integer*4 args


Executes a program, and sets up a communications path to that program, such that the program can be called and can return results much like an internal function. A "program object" is returned that represents the program and the communication path to it.

The parameter 'args' is an object containing the program's name and any arguments the program requires. If 'args' is not a stream or sequence, then it must be an object that responds to dt_stringvalue(3); its stringvalue is the program's name, and the program is invoked with no arguments. If 'args' is a sequence or stream, it must contain objects that respond to dt_stringvalue(3) -- the first of these objects is the name of the program itself, and the rest are the command-line arguments for the program.

UNIX Note: The following comments apply to dt_alloc_program(3) on UNIX systems. The function execvp(2) is used to start the program; see the man page for execvp(3) for comments about the PATH environment variable. The program is executed using a "fork-fork-exec" rather than a simpler "fork-exec." Because of this, the program is a grandchild, the child finishes immediately, and the dt_alloc_program(3) function immediately does a wait(3), thus preventing the formation of "zombie" processes. Because pipes are used, dt_alloc_program(3) sets SIG_IGN on the SIGPIPE, so that if the program created by dt_alloc_program(3) accidentally dies, your program won't be killed by a SIGPIPE signal. If you need to intercept the SIGPIPE signal, you should install a signal-catching function after you have called dt_alloc_program(3).

Every program object must use the pipetalk communication protocol and send, at minimum, a welcome message in order for the program object to be successfully allocated.

Return Value

A program-object's handle will be returned on success (the program is running). NULL_OB is returned on failure (e.g. the program is not accessible, failed to start, failed to send a "welcome" message, or "crashed" immediately after starting). In most cases, a failure will generate an error message that can be accessed via dt_errors(3); the exception to this is when 'args' is some object that has no dt_stringvalue(3) and or isn't a stream or sequence.

Related Topics

dt_converse(3) dt_welcome(3)