stopio(S)                      6 January 1993                      stopio(S)


 Name

    stopio - stop further I/O to an open file

 Syntax


    cc .. .  -lprot


    #include  <sys/types.h>
    #include  <sys/security.h>
    #include  <sys/audit.h>
    #include  <prot.h>

    int stopio (path)
    char *path;


 Description

    The stopio routine prevents further I/O on all file descriptors now hav-
    ing the argument path open.  The next time a read(S), write(S) or
    ioctl(S) is invoked by any process on any file descriptor of path, the
    system call fails with the [EBADF] error and the SIGHUP signal is sent to
    the process.  stopio may only be invoked by the super user or owner of
    file path.

    The stopio routine is used to isolate successive user sessions on a sin-
    gle terminal.  At the time stopio is invoked with the terminal path as
    the argument, background processes left by previous sessions may continue
    to run on the terminal, but any further input or output to the terminal
    fails as previously described.  As the terminal gets re-opened after the
    stopio invocation, I/O using those new file descriptors succeeds until
    the next stopio call on the same path.  This system call is intended to
    be used immediately before the open of the terminal line.

 Return value

    Upon successful completion, the stopio routine returns a value of 0.
    Otherwise, a value of -1 is returned and errno is set to indicate the
    appropriate error.

 Diagnostics

    If one of the following conditions occurs, the stopio routine fails and
    errno is set to the corresponding value:

    [EACCES]    Search permission is denied on a component of the path pre-
                fix.

    [EFAULT]    Path points outside the allocated address space of the pro-
                cess.

    [ENOENT]    The named file does not exist.

    [ENOTDIR]   A component of the path prefix is not a directory.

    [ENOTTY]    path is not a local character special file.  (This may go
                away - see following Note).

    [EPERM]     The effective user ID does not match the owner of the file
                and the effective user ID is not super-user.

    [EROFS]     The named file resides on a read-only file system.  (This may
                go away - see following Note).


 Note

    The [EROFS] error is not really appropriate for this routine.

    stopio should work for all file types, but a security study has not yet
    been made as to the utility or feasibility in such an assignment.  For
    now, it works only for character special files to specifically address
    the problem of sharing a single terminal through multiple login sessions.

    stopio's functionality should really be a command within fcntl(S), but
    fcntl expects the file to be open already and this call only requires a
    path name.

 See also

    creat(S), ioctl(S), open(S), read(S), write(S)

 Standards conformance

    The stopio routine is an extension of AT&T System V provided by the Santa
    Cruz Operation.