lib/librmt/rmtops.3

   1 .\"     $NetBSD: rmtops.3,v 1.12 2009/04/11 16:59:05 wiz 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
  10 Remote 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
  45 The
  46 .Nm
  47 library provides a simple means of transparently accessing tape drives
  48 on remote machines via
  49 .Xr rsh 1
  50 and
  51 .Xr rmt 8 .
  52 These routines are used like their corresponding system calls, but
  53 allow the user to open up a tape drive on a remote system on which he
  54 or she has an account and the appropriate remote permissions.
  55 .Pp
  56 A remote tape drive file name has the form
  57 .Dl [user@]hostname:/dev/???
  58 where
  59 .Em system
  60 is the remote system,
  61 .Em /dev/???
  62 is the particular drive on the remote system (raw, blocked, rewinding,
  63 non-rewinding, etc.), and the optional
  64 .Em user
  65 is the login name to be used on the remote system, if different from
  66 the 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
  79 For transparency, the user should include the file
  80 .Aq Pa rmt.h ,
  81 which 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
  99 This allows the programmer to use
 100 .Xr open 2 ,
 101 .Xr close 2 ,
 102 .Xr read 2 ,
 103 .Xr write 2 ,
 104 etc. in their normal fashion, with the
 105 .Nm
 106 routines taking care of differentiating between local and remote files.
 107 This file should be included
 108 .Em before
 109 including the file
 110 .Pa \*[Lt]sys/stat.h\*[Gt] ,
 111 since it redefines the identifier ``stat'' which is used to declare
 112 objects of type
 113 .Em "struct stat" .
 114 .Pp
 115 The routines differentiate between local and remote file descriptors
 116 by adding a bias (currently 128) to the file descriptor of the pipe.
 117 The programmer, if he or she must know if a file is remote, should use
 118 .Fn isrmt .
 119 .Sh ENVIRONMENT
 120 The RCMD_CMD environment variable can be set to the name or pathname
 121 of a program to use, instead of
 122 .Pa /usr/bin/rsh ,
 123 and 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
 128 remote tape library
 129 .El
 130 .Sh DIAGNOSTICS
 131 Several of these routines will return \-1 and set
 132 .Va errno
 133 to EOPNOTSUPP, if they are given a remote file name or a file descriptor
 134 on 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
 141 And 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
 158 Jeff Lee wrote the original routines for accessing tape drives via
 159 .Xr rmt 8 .
 160 .Pp
 161 Fred Fish redid them into a general purpose library.
 162 .Pp
 163 Arnold Robbins added the ability to specify a user name on the remote
 164 system, the
 165 .Pa \*[Lt]rmt.h\*[Gt]
 166 include file, this man page, cleaned up the library a little, and made
 167 the appropriate changes for
 168 .Bx 4.3 .
 169 .Pp
 170 Dan Kegel contributed the code to use the
 171 .Xr rexec 3
 172 library routine.
 173 .Sh BUGS
 174 There is no way to use remote tape drives with
 175 .Xr stdio 3 ,
 176 short of recompiling it entirely to use these routines.
 177 .Pp
 178 The
 179 .Xr rmt 8
 180 protocol is not very capable.
 181 In particular, it relies on TCP/IP sockets for error
 182 free transmission, and does no data validation of its own.