open()--Open File

 #include <fcntl.h>

 int open(const char *path, int oflag, . . .);  

The open() function opens a file and returns a number called a file descriptor. You can use this file descriptor to refer to the file in subsequent I/O operations such as read() or write(). In these subsequent operations, the file descriptor is commonly identified by the argument fildes or descriptor. Each file opened by a job gets a new file descriptor.

If the last element of the path is a symbolic link, the open() function resolves the contents of the symbolic link.

open() positions the file offset (an indicator showing where the next read or write will take place in the file) at the beginning of the file. However, there are options that can change the position.

open() clears the FD_CLOEXEC file descriptor flag for the new file descriptor. Refer to fcntl()--Perform File Control Command for additional information about the FD_CLOEXEC flag.

The open() function also can be used to open a directory. The resulting file descriptor can be used in some functions that have a fildes parameter.

If the file being opened has been saved and its storage freed, the file is restored during this open() function. The storage extension exit program registered against the QIBM_QTA_STOR_EX400 exit point is called to restore the object. (See the Storage Extension Exit Program for details). If the file cannot successfully be restored, open() fails with the EOFFLINE error number.

For information about the exit point which can be associated with open(), see Integrated File System Scan on Open Exit Programs.

Parameters

path

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

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 currently in effect for the job.

See QlgOpen()--Open a File (using NLS-enabled path name) for a description and an example of supplying the path in any CCSID.

oflag

(Input) The file status flags and file access modes of the file to be opened. See Using the oflag Parameter.

Note: The open64() API sets the O_LARGEFILE flag internally.

mode

(Input) An optional third parameter of type mode_t that is required if the O_CREAT flag is set. It specifies the file permission bits to be used when a file is created. For a description of the permission bits, see chmod()--Change File Authorizations.

conversion ID

(Input) An optional fourth parameter of type unsigned int that is required if the O_CCSID or O_CODEPAGE flag is set.

If the O_CCSID flag is set, this parameter specifies a CCSID. If the O_CODEPAGE flag is set, this parameter specifies a code page used to derive a CCSID.

The specified or derived CCSID is assumed to be the CCSID of the data in the file, when a new file is created. This CCSID is associated with the file during file creation.

When the O_TEXT_CREAT flag and its prerequisite flags are not set, the specified or derived CCSID is the CCSID in which data is to be returned (when reading from a file), or the CCSID in which data is being supplied (when writing to a file).

See Using CCSIDs and code pages for more details.

text file creation conversion ID

(Input) An optional fifth parameter of type unsigned int that is required if the O_TEXT_CREAT flag, along with prerequisite flags O_TEXTDATA, O_CREAT, and either O_CCSID or O_CODEPAGE, is set. Note: because O_EXCL is not required, this parameter may apply to files that already exist.

When O_CCSID flag is set, this parameter specifies a CCSID. If the O_CODEPAGE flag is set, this parameter specifies a code page used to derive a CCSID.

The specified or derived CCSID will be used as the CCSID of this open instance. Therefore, this will be the CCSID in which data is to be returned (when reading from a file), or the CCSID in which data is being supplied (when writing to a file). Data will be stored in the CCSID associated with the open file. Note: if the file was not created by this open operation, the file's CCSID may be different than the CCSID associated with the conversion ID parameter.

See Using CCSIDs and code pages for more details.

Using the oflag Parameter

One of the following values must be specified in oflag:

O_RDONLY

Open for reading only.

O_WRONLY

Open for writing only.

O_RDWR

Open for both reading and writing.

One or more of the following also can be specified in oflag:

O_APPEND

Position the file offset at the end of the file before each write operation.

O_CREAT

The call to open() has a mode argument.

If the file being opened already exists, O_CREAT has no effect, except when O_EXCL is also specified (see the following description of O_EXCL.

If the file being opened does not exist, it is created and then opened. Since the create and open operations occur as separate steps, error [EBUSY] could be received if another user opened the object with a conflicting file sharing mode after the create step, but before the open step. The user ID (uid) of the file is set to the effective uid of the job. If the object is being created in the "root" (/), QOpenSys, and user-defined file systems, the following applies. 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) of the new object is set to the GID of the parent directory. For all other file systems, the group ID (GID) of the file is set to the GID of the directory in which the file is created. File permission bits are set according to mode, except for those set in the file mode creation mask of the job. The S_ISUID (set-user-ID) and S_ISGID (set-group-ID) bits are also set according to mode. The file type bits in mode are ignored. All other bits in mode must be cleared (not set) or a [EINVAL] error is returned.

O_EXCL

Ignored if O_CREAT is not set. If both O_EXCL and O_CREAT are specified, open() fails if the file already exists. If both O_EXCL and O_CREAT are specified, and path names a symbolic link, open() fails regardless of the contents of the symbolic link.

O_LARGEFILE

Open a large file. The descriptor returned can be used with the other APIs to operate on files larger than 2GB (GB = 1073741824) minus 1 byte. The file systems that do not support large files will just ignore the O_LARGEFILE open flag if it is set. The O_LARGEFILE flag is ignored by the file systems when open() is used to open a directory.

O_TRUNC

Truncate the file to zero length if the file exists and it is a "regular file" (a stream file that can support positioning the file offset). The mode and owner of the file are not changed. O_TRUNC applies only to regular files. O_TRUNC has no effect on FIFO special files. The O_TRUNC behavior applies only when the file is successfully opened with O_RDWR or O_WRONLY.

Truncation of the file will return the [EOVERFLOW] error if the file is larger than 2 GB minus 1 byte and if the O_LARGEFILE oflag is not also specified on the open() call. (Note that open64() sets the O_LARGEFILE oflag automatically.)

If the file exists and it is a regular file, the S_ISUID (set-user-ID) and S_ISGID (set-group-ID) bits of the file mode are cleared.

If the file has a digital signature, open() with the O_TRUNC oflag causes the signature to be deleted.

O_TEXTDATA

Determines how the data is processed when a file is opened.

• If O_TEXTDATA is specified, the data is processed as text.

  The data is read from the file and written to the file assuming it is in textual form. When the data is read from the file, it is converted from the CCSID of the file to the CCSID of the job or the CCSID specified by the application receiving the data. When data is written to the file, it is converted to the CCSID of the file from the CCSID of the job or the CCSID specified by the application.

  For true stream files, any line-formatting characters (such as carriage return, tab, and end-of-file) are just converted from one CCSID to another.

  When reading from a record file that is being used as a stream file, end-of-line characters are added to the end of the data in each record. When writing to the record file:

  • End-of-line characters are removed.
    
  • Records are padded with blanks (for a source physical file member) or nulls (for a data physical file member).
    
  • Tab characters are replaced by the appropriate number of blanks to the next tab position.
  
  
• If O_TEXTDATA is not specified, the data is processed as binary. The data is read from the file and written to the file without any conversion. The application is responsible for handling the data.

See Using CCSIDs and code pages for more details on text conversions.

O_CCSID

The call to open has a fourth argument (conversion ID), which is to be interpreted as a CCSID. Text conversions between any two CCSIDs supported by the iconv() API can be performed.

This flag cannot be specified with the O_CODEPAGE flag.

See Using CCSIDs and code pages for more details.

O_CODEPAGE

The call to open has a fourth argument (conversion ID), which is to be interpreted as a code page. Only single-byte-to-single-byte or double-byte-to-double-byte text conversions are allowed.

This flag cannot be specified with the O_CCSID flag.

See Using CCSIDs and code pages for more details.

O_TEXT_CREAT

The call to open has a fifth argument (text file creation conversion ID), which is to be interpreted as either a code page or CCSID, depending on whether the O_CODEPAGE or O_CCSID was set.

If the O_TEXT_CREAT flag is specified, all of the following flags must also be specified: O_CREAT, O_TEXTDATA, and either O_CODEPAGE or O_CCSID. If all of these prerequisite flags are not specified when O_TEXT_CREAT is specified, then the call to open will fail with error condition [EINVAL].

This flag indicates that the textual data read from or written to this file will be converted between the CCSID specified or derived from the text file creation conversion ID and the CCSID of the file. When data is read from the file, it is converted from the CCSID of the file to the CCSID specified or derived from the text file creation conversion ID. When data is written to the file, it is converted to the CCSID of the file from the CCSID specified or derived from the text file creation conversion ID.

See Using CCSIDs and code pages for more details.

O_INHERITMODE

Create the file with the same data authorities as the parent directory that the file is created in. Any data authorities passed in the mode parameter are ignored. The mode parameter, however, must still be specified with a valid mode value. This flag is ignored if the O_CREAT flag is not set.

The "root" (/), QOpenSys, QSYS.LIB, independent ASP QSYS.LIB, and QDLS file systems support this flag on an open() with the O_CREAT flag set. The QOPT file system ignores this flag because files in this file system do not have data authorities.

O_NONBLOCK

Return without delay from certain operations on this open descriptor.

If O_NONBLOCK is specified when opening a FIFO:

• An open() for reading only or reading and writing access returns without delay.
  
• An open() for writing only returns an error if no job currently has the FIFO open for reading. The errno value will be ENXIO.

If O_NONBLOCK is not specified when opening a FIFO:

• An open() for reading only blocks the calling thread until another thread opens the FIFO for writing.
  
• An open() for writing only blocks the calling thread until another thread opens the FIFO for reading.
  
• An open() for reading and writing returns without delay.

The O_NONBLOCK open flag is ignored for all other object types.

O_SYNC

Updates to the file will be performed synchronously. All file data and file attributes relative to the I/O operation are written to permanent storage before the update operation returns. Update operations include, but are not limited to, the following: ftruncate(), open() with O_TRUNC, write(), and fclear().

O_DSYNC

Updates to the file will be performed synchronously, but only the file data is written to permanent storage before the update operation returns. Update operations include, but are not limited to, the following: ftruncate(), open() with O_TRUNC, write(), and fclear().

O_RSYNC

Read operations to the file will be performed synchronously. Pending update requests affecting the data to be read are written to permanent storage. This flag is used in combination with O_SYNC or O_DSYNC. When O_RSYNC and O_SYNC are set, all file data and file attributes are written to permanent storage before the read operation returns. When O_RSYNC and O_DSYNC are set, all file data is written to permanent storage before the read operation returns.

O_FORCE_SCAN

One or more of the following conditions will be ignored when determining whether the integrated file system scan-related exit programs will be called:

• The Scan file systems control (QSCANFSCTL) system value specification of *FSVRONLY.
• The object was marked to not be scanned (e.g. scan attribute is *NO).
• The object was marked to be scanned only if the object changed (e.g. scan attribute is *CHGONLY).

For example, an object is opened that has a scan attribute of *YES, and the open request is not through the file servers when *FSVRONLY is specified. If O_FORCE_SCAN is specified on that open request, the object will be scanned if all the remaining conditions are met. Similarly, if an object that has a scan attribute of *NO or *CHGONLY is opened with O_FORCE_SCAN specified, the object will be scanned if all the remaining conditions are met. For a list of the remaining conditions and more information, see Integrated File System Scan on Open Exit Programs and Integrated File System Scan on Close Exit Programs.

A file sharing mode may also be specified in the oflag. If none are specified, a default sharing mode of O_SHARE_RDWR is used. No more than one of the following may be specified:

O_SHARE_RDONLY

Share with readers only. Open the file only if both of the following are true:

• The file currently is not open for writing.
• The access intent does not conflict with the sharing mode of another open instance of this file.

Once opened with this sharing mode, any request to open this file for writing fails with the [EBUSY] error.

O_SHARE_WRONLY

Share with writers only. Open the file only if both of the following are true:

• The file is not currently open for reading.
  
• The access intent does not conflict with the sharing mode of another open instance of this file.

Once opened with this sharing mode, any request to open this file for reading fails with the [EBUSY] error.

O_SHARE_RDWR

Share with readers and writers. Open the file only if the access intent of this open does not conflict with the sharing mode of another open instance of this file.

O_SHARE_NONE

Share with neither readers nor writers. Open the file only if the file is not currently open. Once the file is opened with this sharing mode, any request to open this file for reading or writing fails with the [EBUSY] error.

All other bits in oflag must be cleared (not set).

Notes:

1. If O_WRONLY or O_RDWR is specified and the file is checked out by a user profile other than that of the current job, the open() fails with the [EBUSY] error.
   
   
2. If O_WRONLY or O_RDWR is specified and the file is marked "read-only," the open() fails with the [EROOBJ] error.
   
   
3. If O_CREAT is specified and the file did not previously exist, a successful open() sets the access time, change time, modification time, and creation time for the new file. It also updates the change time and modification time of the directory that contains the new file (the parent directory of the new file).

   If O_TRUNC is specified and the file previously existed, a successful open() updates the change time and modification time for the file.

4. Sharing Files

   If a sharing mode is not specified in the oflag parameter, a default sharing mode of O_SHARE_RDWR is used. The open() may fail with the [EBUSY] error number if the file is already open with a sharing mode that conflicts with the access intent of this open() request.

   Directories may only be opened with a sharing mode of O_SHARE_RDWR. If any other sharing mode is specified, the open() fails with error number [EINVAL].

   For *CHRSF files, a sharing mode of O_SHARE_RDWR is used regardless of the sharing mode specified in the oflag parameter. The sharing mode specified in the oflag parameter is ignored.

   The following table shows when conflicts will occur:

   File Sharing Conflicts
   Access Intent	Sharing Mode
   	Readers Only	Writers Only	Readers and Writers	No Others (Exclusive)
   O_RDONLY	OK	EBUSY	OK	EBUSY
   O_WRONLY	EBUSY	OK	OK	EBUSY
   O_RDWR	EBUSY	EBUSY	OK	EBUSY

Using CCSIDs and code pages

If the O_CCSID or O_CODEPAGE flag is specified, but O_CREAT is not, the mode parameter must be specified, but its value will be ignored.

The value of conversion ID must be less than 65536. The [EINVAL] error will be returned if it is not.

When a new file is created:

• conversion ID is used to derive a CCSID to be associated with the new file (the "file CCSID") and this open instance (the "open CCSID"). If the file is to contain textual data, this CCSID is assumed to be the CCSID of the data, unless the O_TEXT_CREAT flag and its prerequisite flags were also specified.
  
  
• If neither O_CCSID nor O_CODEPAGE is specified, or if O_CCSID is specified and conversion ID is zero (0), the file CCSID is set to the CCSID of the job. If the job CCSID is 65535, the file CCSID is set to the default CCSID of the job.
  
  
• For this open instance, if the O_TEXT_CREAT flag and its prerequisite flags were not specified, the file CCSID and open CCSID are the same and no text conversion will take place on data written to or read from the file, whether O_TEXTDATA is specified or not. If you would like to associate the new file with the CCSID specified in conversion ID, but you would also like to have text conversion occur between the file's CCSID and a different CCSID, consider using the O_TEXT_CREAT flag and corresponding text file creation conversion ID parameter.
  
  
• The QSYS.LIB and independent ASP QSYS.LIB file systems cannot associate the derived CCSID with the database file member being created. Rather, the CCSID of the new member is the CCSID of the database file in which the member is being created. Data read or written during this open instance is converted from or to the CCSID of the database file.

When an existing file is opened and O_TEXTDATA is not specified:

• The value of conversion ID is ignored.

When an existing file is opened and O_TEXTDATA is specified:

• conversion ID is used to derive a CCSID to be associated with this open instance (the "open CCSID").
  
  
• If neither O_CCSID nor O_CODEPAGE is specified, or if O_CCSID is specified and conversion ID is zero (0), the open CCSID is set to the CCSID of the job. If the job CCSID is 65535, the open CCSID is set to the default CCSID of the job.
  
  
• The system will convert from the file CCSID to the open CCSID when reading data from the file, and convert from the open CCSID to the file CCSID when writing data to the file.
  
  
• If O_CCSID is not specified, and the file CCSID and open CCSID are not the same, and one of them is not strictly single-byte, open() will fail with errno set to [ECONVERT].

See Examples for a sample program that creates a new file and then opens it for data conversion.

Authorities

Note: Adopted authority is not used.

Return Value

Error Conditions

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

Additionally, if interaction with a file server is required to access the object, errno could also 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 number [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. The S_ISGID bit of the directory affects what the group ID (GID) is for objects that are created in the directory. 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 is copied from the parent directory in which the file is created.

   When you do not specify O_INHERITMODE for the oflag parameter, 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.

   When you specify O_INHERITMODE for the oflag parameter, the owner, primary group, and public data and object authorities (*R, *W, *X, *OBJEXIST, *OBJMGT, *OBJALTER, and *OBJREF) are copied from the parent directory's owner, primary group, and public data and object authorities. In addition, the private authorities (if any) and authorization list (if any) are copied from the parent directory. If the new file has a different owner than the parent directory and the new file's owner has a private authority in the parent directory, that private authority is not copied from the parent directory. The authority for the owner of the new file is copied from the owner of the parent directory.

   There are some restrictions when opening a FIFO for text conversion and the CCSIDs involved are not strictly single-byte:

   • Opening a FIFO for reading or reading and writing is not allowed. The errno global variable is set to [ENOTSUP].
     
     
   • Any conversion between CCSIDs that are not strictly single-byte must be done by an open instance that has write only access.
   
   
3. QSYS.LIB and Independent ASP QSYS.LIB File System Differences

   The following object types are allowed to be opened:

   • *MBR (physical file member)
     The only types of physical files supported when specifying the O_TEXTDATA flag are program-described physical files that contain a single field and source physical files that contain a single text field. Externally described physical files are supported for binary access only.
     
     
   • *LIB (library)
     
     
   • *FILE (physical file or save file)
     
     
   • *USRSPC (user space)

   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 primary group authorities specified in mode are not saved if no primary group exists.

   You cannot open a member in a file that has a mixed data CCSID.

   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.

   Due to the restriction that only one job may have a database member open for writing at a time, the sharing modes O_SHARE_WRONLY and O_SHARE_RDWR do not provide the requested level of sharing.

   • If O_SHARE_WRONLY is specified, the open() succeeds. However, in all jobs other than the one that performed this open(), the actual enforced share mode for this file is equivalent to O_SHARE_NONE.
     
     
   • If O_SHARE_RDWR is specified, or if no share mode is specified, the open() succeeds. However, in all jobs other than the one that performed this open(), the actual enforced share mode is equivalent to O_SHARE_RDONLY.

   The open() of a database member fails with an [EBUSY] error under any of the following conditions:

   • The O_TEXTDATA flag is specified, but the file is already open in this job or another job where the O_TEXTDATA flag is not specified.
     
     
   • The O_TEXTDATA flag is not specified, but the file is already open in this job or another job where the O_TEXTDATA flag and write access are specified.
     
     
   • The O_TEXTDATA flag is specified and write access is requested, but the file is already open in this job or another job where O_TEXTDATA is specified and write access is also requested.
     
     
   • The O_CREAT flag is specified, the member already exists, and the QSYS.LIB or independent ASP QSYS.LIB file system cannot get exclusive access to the member. They must have exclusive access to clear the old member.
     
     
   • The O_TEXTDATA flag is not specified (binary mode) and more than one job tries to obtain write access to the member. This condition does not apply to PC clients. Because PC clients share the same server job, they can share access to the member.
     
     
   • The user attempts to open a member with access intentions that conflict with existing object locks on the member.

   This function will fail with error number [ENOTSAFE] if the object on which this function is operating is a save file and multiple threads exist in the job.

   This function will fail with error number [ENOTSUP] if the file specified is a save file and the O_RDWR flag is specified. A save file can be opened for either reading only or writing only.

   This function will fail with error number [ENOTSUP] if the file specified is a save file and the O_TEXTDATA flag is specified.

   If a save file containing data is opened for writing, the O_APPEND or O_TRUNC flag must be specified. Otherwise, the open() will fail with error number [ENOTSUP].

   There are some restrictions on sharing modes when opening a save file.

   1. A save file may not have more than one open descriptor per job, regardless of the sharing mode specified.
      
      
      • A save file currently open for reading only cannot be opened again in the same job for reading or writing. The open() will fail with errno set to [EBUSY].
        
        
      • A save file currently open for writing only cannot be opened again in the same job for reading or writing. The open() will fail with errno set to [EBUSY].
      
      
   2. Due to the restriction that only one job may have a save file open when the save file is open for writing, the sharing modes O_SHARE_WRONLY and O_SHARE_RDWR do not provide the reqested level of sharing.
      
      
      • If O_SHARE_WRONLY is specified, the open() succeeds. However, in all jobs other than the one that performed this open(), the actual enforced share mode for this file is equivalent to O_SHARE_NONE.
        
        
      • If O_SHARE_RDWR is specified and the file is opened for reading only, the open() succeeds. However, in all jobs other than the one that performed this open(), the actual enforced share mode is equivalent to O_SHARE_RDONLY.
        
        
      • If O_SHARE_RDWR is specified and the file is opened for writing only, the open() succeeds. However, in all jobs other than the one that performed this open(), the actual enforced share mode is equivalent to O_SHARE_NONE.

   Note: Unpredictable results, including loss of data, could occur if, in the same job, a user tries to open the same file for writing at the same time by using both open() API for stream file access and a data management open API for record access.

4. QDLS File System Differences

   When O_CREAT is specified and a new file is created:

   • the owner's object authority is set to *OBJMGT + *OBJEXIST + *OBJALTER + *OBJREF.
     
     
   • The primary group and public object authority and all other authorities are copied from the directory (folder) in which the file is created.
     
     
   • 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.

   QDLS does not store the language ID and country ID with its files. When this information is requested (using the readdir() function), QDLS returns the language ID and country ID of the system.

5. QOPT File System Differences

   When the volume on which the file is being opened 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 open().
     
     
   • The volume authorization list is checked for *USE when the access mode is O_RDONLY. The volume authorization list is checked for *CHANGE when the access mode is O_RDWR or O_WRONLY.
     
     
   • 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).
     
     
   • When O_INHERITMODE is specified for the oflag parameter, the data authorities are copied from the parent directory.
     
     
   • The sharing modes O_SHARE_RDONLY, O_SHARE_WRONLY, and O_SHARE_RDWR do not provide the requested level of sharing when the access mode is O_RDWR or O_WRONLY. When the access mode is O_RDWR or O_WRONLY, the resulting sharing mode semantic will be equivalent to O_SHARE_NONE.
     
     
   • For newly created files, the same uppercase and lowercase forms in which the names are entered are preserved. No distinction is made between uppercase and lowercase when searching for names.
     
     
   • This function will fail with error number [EINVAL] if the O_SYNC, O_DSYNC, or O_RSYNC open flag is specified.

   When the volume on which the file is being opened 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 *USE when the access mode is O_RDONLY. The volume authorization list is checked for *CHANGE when the access mode is O_RDWR or O_WRONLY.
     
     
   • 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.
   
   
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.

   The sharing modes O_SHARE_RDONLY, O_SHARE_WRONLY, and O_SHARE_NONE do not provide the requested level of sharing. If any one of these share modes is specified, the resulting share mode semantic will be equivalent to O_SHARE_RDWR.

7. QNetWare File System Differences

   The QNetWare file system does not fully support mode bits. See Netware on iSeries in the iSeries Information Center 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 2 GB minus 1 byte).
   
   
9. When you develop in C-based languages and an application is compiled with the _LARGE_FILES macro defined, the open() API will be mapped to a call to the open64() API.
   
   
10. Using this function on the /dev/null or /dev/zero character special file, the oflag values of O_CREAT and O_TRUNC have no effect.
    
    
11. The O_SYNC, O_DSYNC, and O_RSYNC open flags will not cause updates made to the file via mapped access to be written to permanent storage.

Related Information

• The <fcntl.h> file (see Header Files for UNIX-Type Functions)
• close()--Close File or Socket Descriptor
• creat()--Create or Rewrite File
• dup()--Duplicate Open File Descriptor
• fcntl()--Perform File Control Command
• Integrated File System Scan on Open Exit Programs
• lseek()--Set File Read/Write Offset
• open64()--Open File (Large File Enabled)
• QlgOpen()--Open a File (using NLS-enabled path name)
• read()--Read from Descriptor
• stat()--Get File Information
• umask()--Set Authorization Mask for Job
• write()--Write to Descriptor

Examples

See Code disclaimer information for information pertaining to code examples.

The following example opens an output file for appending. Because no sharing mode is specified, the O_SHARE_RDWR sharing mode is used.

int fildes;
fildes = open("outfile",O_WRONLY | O_APPEND);

The following example creates a new file with read, write, and execute permissions for the user creating the file. If the file already exists, the open() fails. If the open() succeeds, the file is opened for sharing with readers only.

fildes = open("newfile",O_WRONLY|O_CREAT|O_EXCL|O_SHARE_RDONLY,S_IRWXU);

This example first creates an output file for with a specified CCSID. The file is then closed and opened again with data conversion. The open() function is called twice because no data conversion would have occurred when using the first open's descriptor on read or write operations, even if O_TEXTDATA had been specified on that open; however, the second open could be eliminated entirely by using O_TEXT_CREAT on the first open. This is demonstrated in the code example immediately following this example. In this example, EBCDIC data is written to the file and converted to ASCII.

#include <fcntl.h>
#include <sys/stat.h>
#include <errno.h>
#include <stdio.h>

int main(int argc, char *argv[])
{
  int fd;
  int rc;
  char name[]="/test.dat";
  char data[]="abcdefghijk";
  int oflag1 = O_CREAT | O_RDWR | O_CCSID;
  int oflag2 = O_RDWR | O_TEXTDATA | O_CCSID;
  mode_t mode = S_IRUSR | S_IWUSR | S_IXUSR;
  unsigned int file_ccsid = 819;
  unsigned int open_ccsid = 37;

  /***************************************************/
  /*  First create the file with the CCSID 819.      */
  /***************************************************/

  if ((fd=open(name,oflag1,mode,file_ccsid)) < 0)
  {
    perror("open() for create failed");
    return(0);
  }

  if (close(fd) < 0)
  {
    perror("close() failed.");
    return(0);  
  }

  /***************************************************/
  /*  Now open the file so EBCDIC (CCSID 37) data    */
  /*  written will be converted to ASCII (CCSID 819).*/
  /***************************************************/

  if ((fd=open(name,oflag2,mode,open_ccsid)) < 0)
  {
    perror("open() with translation failed");
    return(0);  
  }

  /***************************************************/
  /* Write some EBCDIC data.                         */
  /***************************************************/

  if (-1 == (rc=write(fd, data, strlen(data))))
  {
    perror("write failed");
    return(0);
  }

  if (0 != (rc=close(fd)))
  {
    perror("close failed");
    return(0);
  }
}

In this second example, EBCDIC data is written to the file and converted to ASCII. This will produce the same results as the first example, except that it did it by only using one open instead of two.

#include <fcntl.h>
#include <sys/stat.h>
#include <errno.h>
#include <stdio.h>

int main(int argc, char *argv[])
{
  int fd;
  int rc;
  char name[]="/test.dat";
  char data[]="abcdefghijk";
  int oflag1 = O_CREAT | O_RDWR | O_CCSID | O_TEXTDATA | O_TEXT_CREAT | O_EXCL;
  mode_t mode = S_IRUSR | S_IWUSR | S_IXUSR;
  unsigned int file_ccsid = 819;
  unsigned int open_ccsid = 37;

  /***************************************************/
  /*  First create the file with the CCSID 819, and  */
  /*  open it such that the data is converted        */
  /*  between the the open CCSID of 37 and the       */
  /*  file's CCSID of 819 when writing data to it.   */
  /***************************************************/

  if ((fd=open(name,oflag1,mode,file_ccsid,open_ccsid)) < 0)
  {
    perror("open() for create failed");
    return(0);
  }

  /***************************************************/
  /* Write some EBCDIC data.                         */
  /***************************************************/

  if (-1 == (rc=write(fd, data, strlen(data))))
  {
    perror("write failed");
    return(0);
  }

  /***************************************************/
  /* Close the file.                                 */
  /***************************************************/
  if (0 != (rc=close(fd)))
  {
    perror("close failed");
    return(0);
  }
}