DCSRunArgvAlloc — Run a command with a given argument vector and dynamically allocate the buffers for the stdout and stderr contents.
#include <dcs.h>
DCSExitCode DCSRunArgvAlloc( |
argv, | |
| out, | ||
err);
|
const char**
|
argv; |
char**
|
out; |
char**
|
err; |
For C++ language users, this function and an enumeration
defining the DCSExitCode values are contained in the
NCAR_MSS namespace.
This function provides a convenient wrapper around the procedure
of starting a DCS (or other) command and collecting that
command's output and exit status.
By including the dcs.h header file,
the correct types for the arguments and return values will be
automatically used regardless of the specific API (32-bit, 64-bit)
used by the application program.
The argv parameter is an array of
character pointers the provide the C-strings for the command name
and arguments. The last pointer must be set to 0 (NULL) to
indicate the end of the argument list.
The out parameter is the address of
a char pointer variable, which will be set to the address of
a newly allocated buffer that contains a NUL terminated string
containing the stdout stream of the DCS command. The
maximum possible size of the buffer is 1 million bytes.
The buffer pointed to by out
must be freed by the application, or a memory leak will result.
The err parameter is the address of
a char pointer variable, which will be set to the address of
a newly allocated buffer that contains a NUL terminated string
containing the stderr stream of the DCS command. The
maximum possible size of the buffer is 1 million bytes.
The buffer pointed to by err
must be freed by the application, or a memory leak will result.
For library or system call detected errors -1
will be returned and errno
will be set. An error message, prefixed by
ERROR detected by the DCS library:,
will appear on the stderr of the calling process.
Otherwise, the (positive) exit status of the DCS command
will be returned.
If -1 is returned,
errno will likely have been set
by one of the following library or system calls:
close(2),
dup2(2),
fork(2),
free(3),
malloc(3),
pipe(2),
read(2),
select(2), and
waitpid(2).
The library routines work by executing a
fork(2)
to create a child process, then
execvp(2)
to start the DCS command (which searchs along the PATH
environment variable to find them).
The stdout and stderr streams are collected by reading two pipes
and placing the output either into the appropriate user-provided
buffers or allocating and returning new buffers. The child process
is reaped with
waitpid(2).
system(3)
function, as it is not thread safe on all of the
platforms supported by DCS. Thus it is not possible to
access shell or environment variables in the command's arguments.
If the application catches the
SIGCHLD signal, it must be
prepared for signal notifications caused by the termination of
child processes started by the DCS library.
The user's application must not use the
wait(2)
system call, or the DCS library will likely hang forever
waiting for its child process.
Ensure your PATH includes the directory containing
the DCS commands.
Since the mscdsetup command is not supported by this interface, either provide absolute MSS pathnames, or execute the appropriate mscdsetup(1NCAR) and mscd(1NCAR) commands prior to invoking your executable.
This example command line should probably work to compile 32-bit API C programs that use the DCS library:
cc -I/usr/local/dcs-4.0/include -L/usr/local/dcs-4.0/lib32 \ -o program main.c -ldcs
Here is a C example of msls:
#include <dcs.h>
#include <stdio.h>
#include <stdlib.h>
int
main(int argc, char** argv)
{
DCSExitCode status;
char *out;
char *err;
char* args[4];
args[0] = "msls";
args[1] = "-l";
args[2] = "/DIRECTORY";
args[3] = 0;
status = DCSRunArgvAlloc((const char**) args, &out, &err);
printf("msls exit status: %d\n", status);
fputs(out, stdout);
fputs(err, stderr);
free(out);
free(err);
return(0);
}
These the header file is located at
/usr/local/dcs-4.0/include/dcs.h.
The library is located either in the
/usr/local/dcs-4.0/lib32/libdcs.a file for
32-bit API programs, or the
/usr/local/dcs-4.0/lib64/libdcs.a file for
64-bit API programs. Some system administrators may
also provide symlinks to the header file and the libraries
in other system specific locations.
DCSRunArgvAlloc(3NCAR),
DCSRunArgvFixed(3NCAR),
DCSRunParseAlloc(3NCAR),
DCSRunParseFixed(3NCAR).
dcsjlog(1NCAR), dcsq(1NCAR), dcsrm(1NCAR), dcswait(1NCAR), msallinfo(1NCAR), mschproj(1NCAR), msclass(1NCAR), mscomment(1NCAR), msdu(1NCAR), msfind(1NCAR), msls(1NCAR), msmv(1NCAR), mspasswd(1NCAR), msrawinfo(1NCAR), msrcp(1NCAR), msrecover(1NCAR), msretention(1NCAR), msrm(1NCAR), mstouch(1NCAR).