1.\" $NetBSD: rmtops.3,v 1.17 2022/12/04 11:25:09 uwe 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 <sys/stat.h> , 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 RETURN VALUES 131Several of these routines will return \-1 and set 132.Va errno 133to 134.Er EOPNOTSUPP , 135if they are given a remote file name or a file descriptor 136on an open remote file (e.g., 137.Fn rmtdup ) . 138.Sh SEE ALSO 139.Xr rcp 1 , 140.Xr rsh 1 , 141.Xr rmt 8 142.Pp 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 <rmt.h> 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. 183In particular, it relies on TCP/IP sockets for error 184free transmission, and does no data validation of its own. 185