1.\" $NetBSD: rmtops.3,v 1.6 2002/02/07 07:00:51 ross Exp $ 2.\" 3.Dd October 16, 2001 4.Os 5.Dt RMTOPS 3 6.Sh NAME 7.Nm rmtops 8.Nd access tape drives on remote machines 9.Sh LIBRARY 10Remote Magnetic Tape Library (librmt, -lrmt) 11.Sh SYNOPSIS 12.Fd #include \*[Lt]rmt.h\*[Gt] 13.Fd #include \*[Lt]sys/stat.h\*[Gt] 14.Ft int 15.Fn isrmt "int fd" 16.Ft int 17.Fn rmtaccess "char *file" "int mode" 18.Ft int 19.Fn rmtclose "int fd" 20.Ft int 21.Fn rmtcreat "char *file" "int mode" 22.Ft int 23.Fn rmtdup "int fd" 24.Ft int 25.Fn rmtfcntl "int fd" "int cmd" "int arg" 26.Ft int 27.Fn rmtfstat "int fd" "struct stat *buf" 28.Ft int 29.Fn rmtioctl "int fd" "int request" "char *argp" 30.Ft int 31.Fn rmtisatty "int fd" 32.Ft long 33.Fn rmtlseek "int fd" "long offset" "int whence" 34.Ft int 35.Fn rmtlstat "char *file" "struct stat *buf" 36.Ft int 37.Fn rmtopen "char *file" "int flags" "int mode" 38.Ft int 39.Fn rmtread "int fd" "char *buf" "int nbytes" 40.Ft int 41.Fn rmtstat "char *file" "struct stat *buf" 42.Ft int 43.Fn rmtwrite "int fd" "char *buf" "int nbytes" 44.Sh DESCRIPTION 45The 46.Nm 47library provides a simple means of transparently accessing tape drives 48on remote machines via 49.Xr rsh 1 50and 51.Xr rmt 8 . 52These routines are used like their corresponding system calls, but 53allow the user to open up a tape drive on a remote system on which he 54or she has an account and the appropriate remote permissions. 55.Pp 56A remote tape drive file name has the form 57.sp 58 [user@]hostname:/dev/??? 59.sp 60where 61.Em system 62is the remote system, 63.Em /dev/??? 64is the particular drive on the remote system (raw, blocked, rewinding, 65non-rewinding, etc.), and the optional 66.Em user 67is the login name to be used on the remote system, if different from 68the current user's login name. 69.\" .Pp 70.\" The library source code may be optionally compiled to recognize the 71.\" old 72.\" .Bx 4.2 , 73.\" remote syntax 74.\" .sp 75.\" hostname[.user]:/dev/??? 76.\" .sp 77.\" By default, only the first form (introduced in 78.\" .Bx 4.3 ) 79.\" is recognized. 80.Pp 81For transparency, the user should include the file 82.Pa \*[Lt]rmt.h\*[Gt] , 83which has the following defines in it: 84.Pp 85.Bd -literal 86#define access rmtaccess 87#define close rmtclose 88#define creat rmtcreat 89#define dup rmtdup 90#define fcntl rmtfcntl 91#define fstat rmtfstat 92#define ioctl rmtioctl 93#define isatty rmtisatty 94#define lseek rmtlseek 95#define lstat rmtlstat 96#define open rmtopen 97#define read rmtread 98#define stat rmtstat 99#define write rmtwrite 100.Ed 101.Pp 102This allows the programmer to use 103.Xr open 2 , 104.Xr close 2 , 105.Xr read 2 , 106.Xr write 2 , 107etc. in their normal fashion, with the 108.Nm 109routines taking care of differentiating between local and remote 110files. This file should be included 111.Em before 112including the file 113.Pa \*[Lt]sys/stat.h\*[Gt] , 114since it redefines the identifier ``stat'' which is used to declare 115objects of type 116.Em "struct stat" . 117.Pp 118The routines differentiate between local and remote file descriptors 119by adding a bias (currently 128) to the file descriptor of the pipe. 120The programmer, if he or she must know if a file is remote, should use 121.Fn isrmt . 122.Sh ENVIRONMENT 123The RCMD_CMD environment variable can be set to the name or pathname 124of a program to use, instead of 125.Pa /usr/bin/rsh , 126and must have the same calling conventions as 127.Xr rsh 1 . 128.Sh FILES 129.Bl -tag -width /usr/lib/librmt.a -compact 130.It Pa /usr/lib/librmt.a 131remote tape library 132.El 133.Sh DIAGNOSTICS 134Several of these routines will return \-1 and set 135.Va errno 136to EOPNOTSUPP, if they are given a remote file name or a file descriptor 137on an open remote file (e.g., 138.Fn rmtdup ) . 139.Sh SEE ALSO 140.Xr rcp 1 , 141.Xr rsh 1 , 142.Xr rmt 8 , 143and the appropriate system calls in section 2. 144.\" .Sh CONFIGURATION OPTIONS 145.\" The library may be compiled to allow the use of 146.\" .Bx 4.2 -style 147.\" remote file names. This is not recommended. 148.\" .Pp 149.\" By default, the library opens two pipes to 150.\" .Xr rsh 1 . 151.\" It may optionally be compiled to use 152.\" .Xr rexec 3 , 153.\" instead. Doing so requires the use of a 154.\" .Em .netrc 155.\" file in the user's home directory, or that the application designer be 156.\" willing to have 157.\" .Xr rexec 3 158.\" prompt the user for a login name and password on the remote host. 159.Sh AUTHORS 160Jeff Lee wrote the original routines for accessing tape drives via 161.Xr rmt 8 . 162.Pp 163Fred Fish redid them into a general purpose library. 164.Pp 165Arnold Robbins added the ability to specify a user name on the remote 166system, the 167.Pa \*[Lt]rmt.h\*[Gt] 168include file, this man page, cleaned up the library a little, and made 169the appropriate changes for 170.Bx 4.3 . 171.Pp 172Dan Kegel contributed the code to use the 173.Xr rexec 3 174library routine. 175.Sh BUGS 176There is no way to use remote tape drives with 177.Xr stdio 3 , 178short of recompiling it entirely to use these routines. 179.Pp 180The 181.Xr rmt 8 182protocol is not very capable. In particular, it relies on TCP/IP 183sockets for error free transmission, and does no data validation of 184its own. 185