creat()--Create or Rewrite File

 #include <fcntl.h>

 int creat(const char *path, mode_t mode);  

The creat() function creates a new file or rewrites an existing file so that it is truncated to zero length. The function call

     creat(path,mode);

     open(path, O_CREAT|O_WRONLY|O_TRUNC, mode);

This means that the file named by path is created if it does not already exist, opened for writing only, and truncated to zero length. For further information, see open()--Open File.

The mode argument specifies file permission bits to be used in creating the file. For more information on mode, see chmod()--Change File Authorizations.

Parameters

path

(Input) A pointer to the null-terminated path name of the file to be created or rewritten.

This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

When a new file is created, the new file name is assumed to be represented in the language and country or region currently in effect for the job.

See QlgCreat()--Create or Rewrite File for a description and an example of supplying the path in any CCSID.

mode

(Input) The file permission bits to be used when creating the file. The S_ISUID (set-user-ID), S_ISGID (set-group-ID), and S_ISVTX, bits also may be specified when creating the file.

See chmod()--Change File Authorizations for details on the values that can be specified for mode.

Authorities

Note: Adopted authority is not used.

Authorization Required for creat() (excluding QSYS.LIB, independent ASP QSYS.LIB, and QDLS)

Authorization Required for creat() in the QSYS.LIB and independent ASP QSYS.LIB File Systems

Authorization Required for creat() in the QDLS File System

Return Value

value

creat() was successful. The value returned is the file descriptor for the open file.

-1

creat() was not successful. The errno global variable is set to indicate the error.

Error Conditions

If creat() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

If interaction with a file server is required to access the object, errno could indicate one of the following errors:

Error Messages

The following messages may be sent from this function:

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:
   
   
   • Where multiple threads exist in the job.
     
   • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     
     
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400
   
   
2. "Root" (/), QOpenSys, and User-Defined File System Differences

   The user who creates the file becomes its owner. If the S_ISGID bit of the parent directory is off, the group ID (GID) is set to the effective GID of the thread creating the object. If the S_ISGID bit of the parent directory is on, the group ID (GID) is copied from the parent directory in which the file is created.

   The owner, primary group, and public object authorities (*OBJEXIST, *OBJMGT, *OBJALTER, and *OBJREF) are copied from the parent directory's owner, primary group, and public object authorities. This occurs even when the new file has a different owner than the parent directory. The owner, primary group, and public data authorities (*R, *W, and *X) are derived from the permissions specified in the mode (except for those permissions that are also set in the file mode creation mask). The new file does not have any private authorities or authorization list. It only has authorities for the owner, primary group, and public.

   
   
3. QSYS.LIB and Independent ASP QSYS.LIB File System Differences

   When creating a member, the ownership, group profile, and authorities are all derived from the member's parent physical file. The input mode value is ignored.

   The group ID is obtained from the primary user profile, if a group profile exists.

   The owner object authorities are set to *OBJEXIST, *OBJMGT, *OBJALTER, and *OBJREF. The primary group object authorities are specified by options in the user profile of the job. None of the public object authorities are set.

   The owner, primary group, and public data authorities (*R, *W, and *X) are derived from the permissions specified in the mode (except for those permissions that are also set in the file mode creation mask). The data authorities must match the data authorities of the file in which the member is being created.

   The primary group authorities are not saved if the primary group does not exist. When a primary group is attached to the object, the object gets the authorities specified in mode.

   A member cannot be created in a mixed-CCSID file.

   The file access time for a database member is updated using the normal rules that apply to database files. At most, the access time is updated once per day.

   
   
4. QDLS File System Differences

   The user who creates the file becomes its owner. The group ID is copied from the parent folder in which the file is created.

   The owner object authority is set to *OBJMGT + *OBJEXIST + *OBJALTER + *OBJREF.

   The primary group and public object authority and all other authorities are copied from the parent folder.

   The owner, primary group, and public data authority (including *OBJOPR) are derived from the permissions specified in mode (except those permissions that are also set in the file mode creation mask).

   The primary group authorities specified in mode are not saved if no primary group exists.

   
   
5. QOPT File System Differences

   When the volume on which the file is being created is formatted in Universal Disk Format (UDF):
   
   

   • The authorization that is checked for the object and preceding directories in the path name follows the rules described in "Authorization Required for creat()."
     
   • The volume authorization list is checked for *CHANGE authority.
     
   • The user who creates the file becomes its owner.
     
   • The group ID is copied from the parent directory in which the file is created.
     
   • The owner, primary group, and public data authorities (*R, *W, and *X) are derived from the permissions specified in the mode (except those permissions that are also set in the file mode creation mask).
     
   • The resulting share mode is O_SHARE_NONE; therefore, the function call

     creat(path,mode);
     

     is equivalent to the call

     open(path,
          O_CREAT|O_WRONLY|O_TRUNC|O_SHARE_NONE,
          mode);
     

   • The same uppercase and lowercase forms in which the names are entered are preserved. No distinction is made between uppercase and lower case when searching for names.

   When the volume on which the file is being created is not formatted in Universal Disk Format (UDF):

   • No authorization checks are made on the object or preceding directories in the path name.
     
   • The volume authorization list is checked for *CHANGE authority.
     
   • QDFTOWN becomes the owner of the file.
     
   • No group ID is assigned to the file.
     
   • The permissions specified in the mode are ignored. The owner, primary group, and public data authorities are set to RWX.
     
   • For newly created files, names are created in uppercase. No distinction is made between uppercase and lowercase when searching for names.

   A file cannot be created as a direct child of /QOPT.

   The change and modification times of the parent directory are not updated.

   
   
6. Network File System Differences

   Local access to remote files through the Network File System may produce unexpected results due to conditions at the server. The creation of a file may fail if permissions and other attributes that are stored locally by the Network File System are more restrictive than those at the server. A later attempt to create a file can succeed when the locally stored data has been refreshed. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) The creation can also succeed after the file system has been remounted.

   If you try to re-create a file that was recently deleted, the request may fail because data that was stored locally by the Network File System still has a record of the file's existence. The creation succeeds when the locally stored data has been updated.

   Once a file is open, subsequent requests to perform operations on the file can fail because file attributes are checked at the server on each request. If permissions on the file are made more restrictive at the server or the file is unlinked or made unavailable by the server for another client, your operation on an open file descriptor will fail when the local Network File System receives these updates. The local Network File System also impacts operations that retrieve file attributes. Recent changes at the server may not be available at your client yet, and old values may be returned from operations.

   
   
7. QNetWare File System Differences

   The user who creates the file becomes the owner. Mode bits are not fully supported. See NetWare on iSeries for more information.

   
   
8. This function will fail with the [EOVERFLOW] error if the specified file exists and its size is too large to be represented in a variable of type off_t (the file is larger than 2GB minus 1 byte).
   
   
9. When you develop in C-based languages and this function is compiled with the _LARGE_FILES macro defined, it will be mapped to creat64().

Related Information

• The <fcntl.h> file (see Header Files for UNIX-Type Functions)
  
• creat64()--Create or Rewrite a File (Large File Enabled)
  
• open()--Open File
  
• QlgCreat()--Create or Rewrite File

Example

See Code disclaimer information for information pertaining to code examples.

The following example creates a file:

#include <stdio.h>
#include <fcntl.h>

main() {
  char fn[]="creat.file", text[]="This is a test";
  int fd, rc;

  if ((fd = creat(fn, S_IRUSR | S_IWUSR)) < 0)
    perror("creat() error");
  else {
    if (-1==(rc=write(fd, text, strlen(text))))
      perror("write() error");
    if (close(fd) != 0)
      perror("close() error");
    if (unlink(fn)!= 0)
      perror("unlink() error");
  }
}