doscreate

Purpose

     Creates a DOS file.

Library

     DOS Services Library (libdos.a)

Syntax

     #include <dos.h>

     DOSFILE doscreate (path, mode)
     char *path;
     long mode;

Description

     The doscreate subroutine creates a DOS file with the path
     and  name specified  by  the path  parameter.  The  newly
     created file has  the flags set as specified  by the mode
     parameter.  If  the file specified by  the path parameter
     already exists, the file is  truncated to zero length and
     the mode and owner are unchanged.

     The  mode parameter  is a  32-bit word  containing flags.
     The low-order 12 bits  are access permission flags.  (For
     information about access permission flags, see "chmod.")

     If the file is contained in a DOS file system, the write-
     by-owner bit  of the mode  parameter is the  only signif-
     icant access flag.  If it is 0, the read-only flag is set
     in the DOS directory of the file created.

     Mode  flags for  emulating  functions unique  to DOS  are
     defined in the dos.h header  file.  They may be logically
     OR-ed together from the following list:

     M_HIDDEN    If this  flag of  the mode parameter  is set,
                 the file is created as a hidden file.  If the
                 file  is created  in a  DOS file  system, the
                 appropriate bit is set  in the directory.  If
                 the file  is created  in an AIX  file system,
                 the file  name is  prefixed by a  . (period).
                 If  a hidden  file is  created with  the same
                 file  name as  an existing  normal file,  the
                 normal file is renamed.

     M_SYSTEM    If this  flag of  the mode parameter  is set,
                 and the file is created in a DOS file system,
                 the SYSTEM attribute of  the file is set.  If

                 the file  is created  in an AIX  file system,
                 this flag is ignored.

     If the file is created in  a DOS file system, the name of
     the  file is  translated to  uppercase.  If  the file  is
     created  in  an AIX  file  system,  no translation  takes
     place.

     Warning:   DOS files  are  not implicitly  closed when  a
     process terminates.   You must  explicitly close  all DOS
     files or you may lose data.

Return Value

     Upon   successful  completion,   a  non-NULL   handle  is
     returned.  This handle is  used in subsequent operations.
     The file  is open for writing  even if the mode  does not
     permit writing.  If the  doscreate subroutine fails, a -1
     is returned and doserrno is set to indicate the error.

     The doscreate subroutine fails if one or more of the fol-
     lowing are true:

     o   The user does not have  write access to the directory
         containing the file.
     o   The user  does not have  write access to the  file if
         the file already exists.
     o   The physical medium cannot be written to.
     o   No such device or address.
     o   No such device.

Related Information

     In  this book:     "chmod," "DOS  services library,"  and
     "dosopen."