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