DCSRunArgvFixed — Run a command with a given argument vector and use fixed sized buffers for the stdout and stderr contents.
#include <dcs.h>
DCSExitCode DCSRunArgvFixed( |
argv, | |
| out, | ||
| outLen, | ||
| err, | ||
errLen);
|
const char**
|
argv; |
char*
|
out; |
size_t*
|
outLen; |
char*
|
err; |
size_t*
|
errLen; |
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 buffer in which to place the stdout stream of the
command. The result will be NUL terminated if the buffer
holds the entire result and the NUL character.
The outLen parameter is the address
of a size_t variable that on input contains the size of
the buffer pointed to by the out
parameter, and on output contains the actual size of the
stdout stream stored in the buffer, not including the
terminating NUL character, if any.
The err parameter is the address of
a char buffer in which to place the stderr stream of the
command. The result will be NUL terminated if the buffer
holds the entire result and the NUL character.
The errLen parameter is the address
of a size_t variable that on input contains the size of
the buffer pointed to by the err
parameter, and on output contains the actual size of the
stderr stream stored in the buffer, not including the
terminating NUL character, if any.
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;
size_t outLen;
char *err;
size_t errLen;
char* args[4];
args[0] = "msls";
args[1] = "-l";
args[2] = "/DIRECTORY";
args[3] = 0;
outLen = 500;
out = (char*) malloc(outLen);
errLen = 200;
err = (char*) malloc(errLen);
status = DCSRunArgvFixed((const char**) args, out, &outLen, err, &errLen);
printf("msls exit status: %d\n", status);
printf("%.*s\n", outLen, out);
printf("%.*s\n", errLen, err);
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).