rtcallocate(3)                     CLIX                     rtcallocate(3)



  NAME

    rtc_allocate, rtc_deallocate, rtc_notify - Controls remote tape

  LIBRARY

    INC Library (libinc.a)

  SYNOPSIS

    char *rtc_allocate(
      char *cdev ,
      char *sys ,
      char *rew ,
      char *norew ,
      int timeout );

    char *rtc_tallocate(
      char * cdev ,
      char * sys ,
      char * rew ,
      char * norew ,
      int timeout );

    char *rtc_xallocate(
      char * cdev ,
      char * sys ,
      char * rew ,
      char * norew ,
      int timeout );

    char *rtc_deallocate(
      char *cdev );

    char *rtc_notify(
      char *cdev ,
      int sig );

  PARAMETERS

    cdev      Specifies the name of a tape control device (such as
              /dev/rmt/rt0.ctl) that controls the functions of other tape
              devices in the same group.

    sys       Specifies the name or address of a remote machine with a tape
              drive.

    rew       Specifies a rewindable tape device on the machine sys.

    norew     Specifies a nonrewindable tape device on the machine sys.




  2/94 - Intergraph Corporation                                              1

  rtcallocate(3)                     CLIX                     rtcallocate(3)



    timeout   Specifies the number of minutes the tape can remain idle.  After
              timeout idle minutes expire, a warning is sent to the system
              console.  If the tape remains idle an additional two minutes, it
              is deallocated.

    sig       Specifies the signal to be sent to the calling process when
              rtc_deallocate is executed on the control device cdev.

  DESCRIPTION

    The rtc_allocate(), rtc_deallocate(), and rtc_notify() functions allow a
    tape drive on a remote machine to be used as if it resided locally (see
    rtc(7)).

    The rtc_allocate() function sets up the information needed to access the
    tape drive.  Once allocated, the remote tape drive remains allocated until
    a timeout occurs or rtc_deallocate() is executed.

    The rtc_tallocate() function sets up the connection to the remote system
    using the TCP/IP network protocols. The rtc_allocate() function sets up
    the connection to the remote system using the XNS network protocols. The
    rtc_allocate() function is the same as a call to the rtc_xallocate())
    function.

    The rtc_deallocate() function closes the connection to the remote machine
    to which the cdev control device is attached.  If the tape drive is being
    used when the deallocate command is invoked, an error is returned.

    The rtc_notify() function sets up the signal sig to be sent to the calling
    process when rtc_deallocate() is executed on the control device cdev.

    Since rtc is a STREAMS driver, the control device that rtc_allocate()
    opens must remain open to preserve the network connection.  If the process
    that calls rtc_allocate() needs to exit, it must use the fork() function
    to create a child process which can use rtc_notify() to be notified when
    rtc_deallocate() is executed.  Once rtc_notify() is executed, the child
    process can execute pause() to wait for the notify signal.

  EXAMPLES

    1.  The following example associates the msa0: tape drive on the machine
        vax751 with the tape devices /dev/rmt/rt0 and /dev/rmt/rt0n on the
        local machine:

        rtc_allocate("/dev/rmt/rt0.ctl", "vax751",
           "msa0:", "msa0:", 10);

        The argument that usually represents the nonrewindable tape device may
        be ignored on non-CLIX-based machines.

    2.  The following example associates the default tape drive of the machine



  2                                              Intergraph Corporation - 2/94

  rtcallocate(3)                     CLIX                     rtcallocate(3)



        ip3040 with the tape devices /dev/rmt/rt1 and /dev/rmt/rt1n using
        TCP/IP as the networking protocol:

        rtc_tallocate("/dev/rmt/rt1.ctl", "ip3040",
           "/dev/rmt/0m", "/dev/rmt/0mn", 0);


  FILES

    /dev/rmt/rt?.ctl   control device

    /dev/rmt/rt?       rewind rtc(7) device

    /dev/rmt/rt?n      no-rewind rtc(7) device

  CAUTIONS

    If a device executes an rtc_allocate() and exits without forking and using
    rtc_notify(), or exits without calling rtc_deallocate(), the device
    associated with cdev may become unusable.

  RETURN VALUES

    Upon successful completion, NULL is returned.  Otherwise, a pointer to an
    error message is returned.

  RELATED INFORMATION

    Commands: rtc(1), rtc_s(8)

    Files: rtc(7)























  2/94 - Intergraph Corporation                                              3