NEWCHAN(10.2)                                       NEWCHAN(10.2)

     NAME
          newchan, chanfree, cclose, eqqid, eqchan, isdir, fdtochan,
          namec - channel operations

     SYNOPSIS
          Chan* newchan(void)

          void  chanfree(Chan *c)

          int   eqqid(Qid a, Qid b)

          int   eqchan(Chan *a, Chan *b, int pathonly)

          void  isdir(Chan *c)

          Chan* fdtochan(Fgrp *f, int fd, int mode, int chkmnt, int
          iref)

          Chan* namec(char *pathname, int amode, int omode, ulong
          perm)

          void  cclose(Chan *c)

     DESCRIPTION
          A value of type Chan represents a kernel channel for I/O and
          name space operations.  It has the following public struc-
          ture:

               typedef struct Chan{
                     ushort    type;       /* driver name */
                     ulong     dev;        /* instance number */
                     ushort    mode;       /* open mode */
                     ushort    flag;       /* COPEN set once opened */
                     ulong     offset;     /* current file offset */
                     Qid       qid;        /* unique id (path, vers) */
                     Cname*     name;/* name by which it was accessed */

          Newchan returns a pointer to a newly allocated channel
          (sleeping if necessary until memory is available).  Device
          drivers do not normally call newchan directly, but instead
          allocate channels using either devattach, when a process
          attaches to the device's root, or devclone, when an existing
          channel is cloned; see devattach(10.2).

          Chanfree frees the channel structure c for reuse.

          Eqqid returns 1 if Qid values a and b are equal (ie, both
          their path and vers members are equal); it returns 0 other-
          wise.

     Page 1                       Plan 9             (printed 3/28/24)

     NEWCHAN(10.2)                                       NEWCHAN(10.2)

          Eqchan returns 1 if a and b have the same qid, type and dev
          members (ie, they represent the same file); it returns 0
          otherwise.  If pathonly is non-zero, the comparison of the
          two qid members compares only their path values, ignoring
          the version field vers.

          Isdir checks that a given channel c is a directory.  If so,
          it returns; otherwise, it generates an error(10.2), Enotdir.

          The Fgrp structure represents an array of open files, each
          represented by a Chan, indexed by integer file descriptors.
          A given Fgrp can be shared between processes.

          Fdtochan returns a pointer to the Chan corresponding to file
          descriptor fd in file descriptor group f (almost invariably
          up->env->fgrp, the file descriptor group for the current
          process).  If mode is a valid mode for sys-open(2), typi-
          cally OREAD, OWRITE or ORDWR, it must correspond to the mode
          with which fd was originally opened; if mode is -1, no check
          is made.  If chkmnt is non-zero, c must not be a channel in
          use by the mount driver mnt(3). On successful return, if
          iref is non-zero, the channel's reference count has been
          incremented.  Fdtochan calls error(10.2) if it detects
          invalid uses, in particular an invalid file descriptor fd.

          Namec looks up a pathname in the current name space and
          returns a channel.  Amode determines the mode of look up,
          and must be one of the constants below:

          Aaccess  Access file for information, as in the stat command
                   or call.

          Atodir   Access file as directory (the CHDIR bit of its
                   qid.path must be set).

          Aopen    Access for I/O.

          Amount   Access directory to be mounted upon.

          Acreate  File is to be created.

          If amode is Aopen or Acreate, omode should be a mode suit-
          able for sys-open(2); if Acreate, perm should be valid file
          permissions.  In all other cases, omode and perm can be
          zero.

          Cclose decrements the reference count on c; if no further
          references remain, it calls the corresponding device's
          Dev.close to close the channel, and frees c.

     DIAGNOSTICS

     Page 2                       Plan 9             (printed 3/28/24)

     NEWCHAN(10.2)                                       NEWCHAN(10.2)

          Most functions call error(10.2) on any sort of error.

     SOURCE
          /os/port/chan.c
          /emu/port/chan.c

     SEE ALSO
          ref(10.2)

     Page 3                       Plan 9             (printed 3/28/24)