NetBSD/lib/librmt/rmtops.3

.\"	$NetBSD: rmtops.3,v 1.3 1998/03/08 23:36:46 mrg Exp $
.\"
.TH RMTOPS 3
.SH NAME
rmtops \- access tape drives on remote machines
.SH SYNOPSIS
.nf
.ft B
#include <rmt.h>
#include <sys/stat.h>	/* MUST come after <rmt.h> */

int isrmt (fd)
int fd;

int rmtaccess (file, mode)
char *file;
int mode;

int rmtclose (fd)
int fd;

int rmtcreat (file, mode)
char *file;
int mode;

int rmtdup (fd)
int fd;

int rmtfcntl (fd, cmd, arg)
int fd, cmd, arg;

int rmtfstat (fd, buf)
int fd;
struct stat *buf;

int rmtioctl (fd, request, argp)
int fd, request;
char *argp;

int rmtisatty (fd)
int fd;

long rmtlseek (fd, offset, whence)
int fd, whence;
long offset;

int rmtlstat (file, buf)
char *file;
struct stat *buf;

int rmtopen (file, flags [, mode])
char *file;
int flags, mode;

int rmtread (fd, buf, nbytes)
int fd, nbytes;
char *buf;

int rmtstat (file, buf)
char *file;
struct stat *buf;

int rmtwrite (fd, buf, nbytes)
int fd, nbytes;
char *buf;
.fi
.ft R
.SH DESCRIPTION
.I Rmtops
provides a simple means of transparently accessing tape drives
on remote machines over the ethernet, via
.IR rsh (1)
and
.IR rmt (8).
These routines are used like their corresponding
system calls, but allow the user to open up a tape drive on a remote
system on which he or she has an account and the appropriate remote
permissions.
.PP
A remote tape drive file name has the form
.sp
.RS
.RI [ user @] system :/dev/???
.RE
.sp
where
.I system
is the remote system,
.I /dev/???
is the particular drive on the remote system (raw, blocked, rewinding,
non-rewinding, etc.), and the optional
.I user
is the login name to be used on the remote system, if different from
the current user's login name.
.PP
The library source code may be optionally compiled to recognize the
old, 4.2 BSD, remote syntax
.sp
.RS
.IR system [. user ]:/dev/???
.RE
.sp
By default, only the first form (introduced in 4.3 BSD) is recognized.
.PP
For transparency, the user should include the file
.IR <rmt.h> ,
which has the following defines in it:
.PP
.nf
#define access rmtaccess
#define close rmtclose
#define creat rmtcreat
#define dup rmtdup
#define fcntl rmtfcntl
#define fstat rmtfstat
#define ioctl rmtioctl
#define isatty rmtisatty
#define lseek rmtlseek
#define lstat rmtlstat
#define open rmtopen
#define read rmtread
#define stat rmtstat
#define write rmtwrite
.fi
.PP
This allows the programmer to use
.IR open ,
.IR close ,
.IR read ,
.IR write ,
etc. in their normal fashion, with the
.I rmtops
routines taking care of differentiating between local and remote files.
This file should be included
.I before
including the file
.IR <sys/stat.h> ,
since it redefines the identifier ``stat,'' which is used to declare
objects of type
.BR "struct stat" .
.PP
The routines differentiate between local and remote file descriptors by
adding a bias (currently 128) to the file descriptor of the pipe.
The programmer, if he or she must know if a file is remote, should use the
.I isrmt
function.
.SH FILES
.TP
.B /usr/lib/librmt.a
Contains the remote tape library.  To include the library with a program,
add the flag
.B \-lrmt
to the
.IR cc (1)
command line.
.SH SEE ALSO
.IR rcp (1),
.IR rsh (1),
.IR rmt (8),
and the appropriate system calls in section 2.
.SH DIAGNOSTICS
Several of these routines will return \-1 and set
.I errno
to EOPNOTSUPP, if they are given a remote file name or a file descriptor
on an open remote file (e.g.,
.IR rmtdup ).
.SH BUGS
See \s-1DIAGNOSTICS\s+1 above.  It is to be hoped that true remote file systems
will eventually appear, and eliminate the need for these routines.
.PP
There is no way to use remote tape drives with the
.IR stdio (3)
package, short of recompiling it entirely to use these routines.
.PP
The
.IR rmt (8)
protocol is not very capable.  In particular, it relies on
TCP/IP sockets for error free transmission, and does no data validation
of its own.
.SH CONFIGURATION OPTIONS
The library may be compiled to allow the use of 4.2 BSD style remote
file names. This is not recommended.
.PP
By default, the library opens two pipes to
.IR rsh (1).
It may optionally be compiled to use
.IR rexec (3),
instead. Doing so requires the use of a
.I .netrc
file in the user's home directory, or that the application designer
be willing to have
.I rexec
prompt the user for a login name and password on the remote host.
.SH ENVIRONMENT
The
.I RCMD_CMD
environment variable can be set to the name or pathname of a program
to use, instead of
.P /usr/bin/rsh ,
and must have the same calling conventions as
.IR rsh(1).
.SH AUTHORS
Jeff Lee (gatech!jeff) wrote the original routines for accessing
tape drives via
.IR rmt (8).
.PP
Fred Fish (unisoft!fnf) redid them into a general purpose library.
.PP
Arnold Robbins
(formerly gatech!arnold, now emory!arnold)
added the ability to specify a user
name on the remote system, the
.B <rmt.h>
include file, this man page,
cleaned up the library a little,
and made the appropriate changes for 4.3 BSD.
.PP
Dan Kegel (srs!dan) contributed the code to use
.IR rexec (3)
library routine.