SYNOPSIS

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

       #include <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  function  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 compati-
              ble 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 messages.

       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.

       rmthostname()
              This function copies the user/host part of rmtspec which  should
              be  in  remote  file  syntax.  The first argument 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.
              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 rmt-
              spec 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 rmtget-
              conn() fails to set up a connection, -1 is returned.  If rmtget-
              conn() is unable to find the port number for shell/tcp, the cur-
              rent 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; rmtget-
              conn() then will return -2 after this function did return.

EXAMPLES

       int  remfd;
       char *remfn;
       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  connection  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

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

       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 generated signals may
       interrupt the remote connection.

AUTHOR

       Joerg Schilling
       Seestr. 110
       D-13353 Berlin
       Germany

       Mail bugs and suggestions to:

       schilling@fokus.fhg.de or js@cs.tu-berlin.de



Joerg Schilling                    02/11/11                     RMTGETCONN(3L)