Schily's LIBRARY FUNCTIONS                         RMTGETCONN(3L)


NAME

     rmtinit, rmtdebug, rmthostname,  rmtfilename,  rmtgetconn  -
     initiate a connection to a remote tape server


SYNOPSIS

     cc [ flag ... ] file ...  -lrmt -lsocket -lnsl [ library ...
     ]

     #include <schily/librmt.h>

     void rmtinit(errmsgn, eexit)
          int     (*errmsgn) (int, const char *, ...);
          void    (*eexit)   (int);

     int rmtdebug(dlevel)
          int     dlevel;

     char *rmtfilename(name)
          char    *name;

     char *rmthostname(hostname, hnsize, rmtspec)
          char    *hostname;
          int     hnsize;
          char    *rmtspec;

     int rmtgetconn(host, trsize, excode)
          char    *host;
          int     trsize;
          int     excode;


DESCRIPTION

     rmtinit()
          Is an optional function that allows to set up  a  func-
          tion  for error printing and a function to be called to
          exit the program.  If rmtinit() is not called or any of
          the  function pointers is NULL, the appropriate default
          function is used instead.  The supplied error  printing
          function  needs  to  be compatible with errmsgno(3) and
          the supplied exit function needs to be compatible  with
          exit(3).

     rmtdebug()
          allows to set the debug level for the library code. The
          default  debug level is 0 and does not print debug mes-
          sages.

     rmtfilename()
          is given a filename that may be either in  remote  file
          syntax  ( hostname:filename or user@hostname:filename )
          or not.  If the argument turns out to be in remote file
          syntax, a pointer to the filename part is returned.

Joerg Schilling       Last change: 08/10/12                     1


Schily's LIBRARY FUNCTIONS                         RMTGETCONN(3L)

     rmthostname()
          This function copies  the  user/host  part  of  rmtspec
          which should be in remote file syntax.  The first argu-
          ment is a character array that should be  large  enough
          to  hold  the  user/host  part  of rmtspec.  The second
          argument is the size of the character array.  The third
          argument is a string in remote file syntax.

     rmtgetconn()
          This function establishes a connection  to  the  remote
          tape  server  process.   The  first  parameter  is  the
          usr/host part of a string in  remote  file  syntax  and
          should be created via rmthostname().  The second param-
          eter is the expected maximum transfer size. It is  used
          to set up kernel buffering via setsockopt() to increase
          performance.  The third parameter is an alternate  exit
          code  to  be  used  instead  of  the library default if
          rmtgetconn() decides to call exit().  This allows  com-
          mands like ufsdump to use the documented exit codes for
          startup errors.


RETURNS

     rmtdebug()
          returns the old debug level.

     rmtfilename()
          returns the filename part of  the  argument  string  or
          NULL in case the argument turns out to be not in remote
          file syntax.

     rmthostname()
          returns a pointer to the first argument or NULL in case
          the rmtspec argument turns out to be not in remote file
          syntax.

     rmtgetconn()
          return a file descriptor which is suitable to  be  used
          as  first  argument  for  functions  like  rmtopen() or
          rmtwrite().  If rmtgetconn() fails to set up a  connec-
          tion,  -1  is  returned.   If rmtgetconn() is unable to
          find the port number for shell/tcp, the current uid has
          no  entry  in the passwd file or the user name includes
          illegal characters, exit() is called.  If  you  do  not
          like  rmtgetconn() to exit in this case, call rmtinit()
          before and install a non  exiting  function  as  exit()
          handler;  rmtgetconn()  then  will return -2 after this
          function did return.


EXAMPLES

     int  remfd;
     char *remfn;

Joerg Schilling       Last change: 08/10/12                     2


Schily's LIBRARY FUNCTIONS                         RMTGETCONN(3L)

     char host[256];

     if ((remfn = rmtfilename(filename)) != NULL) {
          rmthostname(host, sizeof (host), filename);

          if ((remfd = rmtgetconn(host, iosize, 0)) < 0)
               comerrno(EX_BAD, "Cannot get connection to '%s'.\n",
                    /* errno not valid !! */      host);
     }

     if (rmtopen(remfd, remfn, mode) < 0)
          comerr("Cannot open '%s'.\n", remfn);

     if (rmtread(remfd, buf, sizeof(buf) < 0)
          comerr("Read error on '%s'.\n", remfn);

     rmtclose(remfd);


ENVIRONMENT

     RSH  If the RSH environment is present, the  remote  connec-
          tion will not be created via rcmd(3) but by calling the
          program pointed to by RSH.  Use  e.g.  RSH=/usr/bin/ssh
          to create a secure shell connection.

     RMT  If the RMT environment  is  present,  the  remote  tape
          server will not be the program /etc/rmt but the program
          pointed to by RMT.  Note that the  remote  tape  server
          program  name  will  be  ignored if you log in using an
          account that has been created with a remote tape server
          program as login shell.


SEE ALSO

     rmt(1), rsh(1), ssh(1),  rcmd(3),  rmtinit(3),  rmtdebug(3),
     rmthostname(3),  rmtfilename(3),  rmtgetconn(3), rmtopen(3),
     rmtioctl(3),    rmtclose(3),    rmtread(3),     rmtwrite(3),
     rmtseek(3),   rmtxstatus(3),   rmtstatus(3),   _mtg2rmtg(3),
     _rmtg2mtg(3), errmsgno(3)


DIAGNOSTICS


NOTES


BUGS

     For now (late 2002), we know that the following programs are
     broken and do not implement signal handling correctly:

     rsh  on SunOS-5.0...SunOS-5.9

     ssh  from ssh.com

     ssh  from openssh.org

Joerg Schilling       Last change: 08/10/12                     3


Schily's LIBRARY FUNCTIONS                         RMTGETCONN(3L)

     Sun already did accept a bug report for rsh(1).  Openssh.org
     accepted a bug for their implementation of ssh(1).

     If you use rmtgetconn() to create a remote connection via an
     unfixed  rsh(1)  or  ssh(1),  be prepared that terminal gen-
     erated signals may interrupt the remote connection.


AUTHOR

     Joerg Schilling
     Seestr. 110
     D-13353 Berlin
     Germany

     Mail bugs and suggestions to:

     joerg.schilling@fokus.fraunhofer.de or js@cs.tu-berlin.de

Joerg Schilling       Last change: 08/10/12                     4


Man(1) output converted with man2html


FhG Schily's Home VED powered