open, open64 - Open a file (elementary)

Definition

#include <stdio.h>

int open(const char *f_name, int mode);
int open64(const char *f_name, int mode);

open and open64 open the file f_name with an access mode that depends on the (octal) value of mode. open and open64 return a valid file descriptor that is used later to identify the file in elementary access operations (read, write).

There is no functional difference between open and open64, except that open64 sets the bit O_LARGEFILE implicitly in the file status flag. The open64 function corresponds to the use of the open function where O_LARGEFILE is set to oflag.

To process files > 2 GB, proceed as follows:

• If the _FILE_OFFSET_BITS 64 define (see "Support for DMS and UFS files > 2 GB") is set, call open. open64 is then used implicitly with the appropriate parameters.

• Otherwise, you have to call open64.

Parameters

const char *f_name

String specifying the name of the file to be opened. f_name may be:

• • • any valid BS2000 file name

    • "link=linkname" linkname identifies a BS2000 link name

    • "(SYSDTA)", "(SYSOUT)", "(SYSLST)" the appropriate system file

    • "(SYSTERM)" terminal Input/Output

    • "(INCORE)" temporary binary file that is only initialized in virtual memory.

int mode

Constant defined in the <stdio.h> header which specifies the desired access mode (or the corresponding octal value), namely:

O_RDONLY

0000

Open for reading. The file must already exist.

O_WRONLY

0001

Open for writing. The file must already exist. The previous contents are retained.

O_TRUNC|O_WRONLY

01001

Open for writing. If the file exists, the previous contents are deleted. If the file does not exist, it is created.

O_RDWR

0002

Open for reading and writing. The file must already exist. The previous contents are retained.

O_TRUNC|O_RDWR

01002

Open for reading and writing. If the file exists, the previous contents are deleted. If the file does not exist, it is created.

O_WRRD

0003

Open for writing and reading. If the file exists, the previous contents are deleted. If the file does not exist, it is created.

O_APPEND_OLD|O_TRUNC|O_WRONLY

0401

Open for appending to the end of the file. The file must already exist. The file is positioned to end of file, i.e. the previous contents are preserved and the new text is appended to the end of the file.

O_APPEND_OLD|O_RDWR

0402

Open for appending to the end of the file and for reading. The file must already exist. The old contents are preserved and the new text is appended to the end of the file. After it is opened, the file is positioned to the end of the file when KR functionality is being used (applies to C/C++ versions prior to V3.0 only), with ANSI functionality to the start of the file.

lbp switch

The lbp switch controls handling of the Last Byte Pointer (LBP). It is only relevant for binary files with PAM access mode and can be combined with all specifications permissible for open. If O_LBP is specified as the lbp switch, a check is made to see whether LBP support is possible. If this is not the case, the open, open64 function will fail and errno is set to ENOSYS. The switch has further effects only when the file is closed.

When an existing file is opened and read, the LBP is always taken into account independently of the lbp switch:

• • • • If the file's LBP is not equal to 0, it is evaluated. Any marker which is present is ignored.

      • When LBP = 0, a marker is searched for, and the file length is determined from this. If no marker is found, the end of the last complete block is regarded as the end of file.

O_LBP

When a file which has been modified or newly created is closed, no marker is written (even if one was present), and a valid LBP is set. In this way files with a marker can be converted to LBP without a marker.
In the case of NK files the last logical block is padded with binary zeros, in the case of K files the file is padded to the physical end of file.

O_NOLBP

When a file which has been modified or newly created is closed, the LBP is set to zero (=invalid). A marker is written. In the case of NK files the last logical block is padded with binary zeros, in the case of K files the file is padded to the physical end of file.

When a file which has been modified or newly created is closed, the LBP is set to zero (=invalid). If the file had a valid LBP when it was opened, no marker is written as in this case it is assumed that no marker exists.
In the case of NK files the last logical block is padded with binary zeros, in the case of K files the file is padded to the physical end of file.

If the lbp switch is specified in both variants (O_LBP and O_NOLBP), the open, open64 function fails and errno is set to EINVAL.

If the lbp switch is not specified, the behavior depends on the environment variable LAST_BYTE_POINTER (see also “Environment variable LAST_BYTE_POINTER” (Last Byte Pointer (LBP))):

LAST_BYTE_POINTER=YES

The function behaves as if O_LBP were specified.

LAST_BYTE_POINTER=NO

The function behaves as if O_NOLBP were specified.

Nosplit switch

This switch controls the processing of text files with SAM access mode and variable record length when a maximum record length is also specified. It can be combined with any of the other constants.

O_NOSPLIT

When reading with read, records of maximum length are not concatenated with the following record.
When writing with write, records which are longer than the maximum record length are truncated to the maximum record length.

If the switch is not specified, the following applies:

• • • When writing
      A record which is longer than the maximum record length will be split into multiple records. If a record has precisely the maximum record length, a record of the length zero is written after it.

    • When reading
      If a record has the maximum record length, it is assumed that the following record is the continuation of this record and the records are concatenated.

Record I/O

The constant O_RECORD can be specified in the modus parameter to open files with record-oriented input/output (record I/O). It can always be combined with every other constant except O_LBP. Only in the case of ISAM files is adding to the end of the file not permitted, i.e. the combination with 0401 and 0402. With ISAM files the position is determined from the key in the record.

O_RECORD

This switch functions as follows:

• In the case of record I/O the read function reads a record (or block) from the current file position. If the number n of the characters to be read is greater than the current record length, nevertheless only this record is read. If n is less than the current record length, only the first n characters are read. The data of the next record is read when the next read access takes place.

• The write function writes a record to the file. In the case of SAM and PAM files the record is written to the current file position. In the case of ISAM files the record is written to the position which corresponds to the key value in the record.
  If the number n of the characters to be written is greater than the maximum record length, only a record with the maximum record length is written. The remaining data is lost. In the case of ISAM files a record is written only if it contains at least a complete key. If in the case of files with a fixed record length n is less than the record length, binary zeros are used for padding. When a record is updated in a SAM or PAM file, the length of the record may not be modified. The write function returns the number of actually written characters also in the case of record I/O.

Return val.

File descriptor

positive number that is used later to identify the file in elementary access operations (read, write).

-1

if the file could not be opened, e.g. due to the absence of access authorization, entry of an invalid file name or link name etc.

Notes

The BS2000 file name or link name can be written in both uppercase and lowercase. It is automatically converted to uppercase.

If a non-existent file is created, the following applies by default:
With KR functionality (applies to C/C++ versions prior to V3.0 only), a SAM file with variable record length and standard block length is created; with ANSI functionality, an ISAM file with variable record length and standard block length is created.
When opened with open or open64, SAM files are always text files.

By using a link name the following file attributes can be changed with the ADD-FILE-LINK command: access method, record length, record format, block length and block format. See also section “System files (SYSDTA, SYSOUT, SYSLST)”.

Whenever the old contents of an already existing file are deleted (0003, 01001), the catalog attributes of this file are preserved.

Position of the read/write pointer in append mode:
If you explicitly position the read/write pointer away from the end of a file (lseek/lseek64) that was opened in append mode (0401, 0402), the way it is handled depends on whether you are using KR or ANSI functionality.
KR functionality (applies to C/C++ versions prior to V3.0 only): The current read/write pointer is ignored only when writing with the elementary function write and automatically positioned to the end of the file.
ANSI functionality: The current read/write pointer is ignored for all write functions and automatically positioned to the end of the file.

An attempt to open a non-existent file in the read (0000, 0002), update (0001), or append (0401, 0402) mode results in an error.

You may open a file for different access modes simultaneously, provided these modes are compatible with one another within the BS2000 data management system.

(INCORE) files can be only opened for writing (01001) or for writing and reading (0003).
Data must first be written. To read in the written data again, the file must be positioned to beginning of file with the lseek/lseek64 function.

When a program starts, the standard files for input, output, and error output are automatically opened with the following file descriptors: 

stdin:	0
stdout:	1
stderr:	2

A maximum of _NFILE files may be open simultaneously. _NFILE is defined as 2048 in <stdio.h>.

Example

The following program opens the file joke twice (for reading) and processes it with different file descriptors (fd1, fd2).

#include <stdio.h>
int fd1,fd2;
char c;
int n;
int main(void)
{
               /* open file "joke" for the
                  first time for reading */
   if((fd1=open("joke",0)) == -1)
               /* error in the first open */
      printf("Error1\n");
               /* open file "joke" for the
                  second time for reading */
   if((fd2=open("joke",0)) == -1)
               /* error in the second open */
      printf("Error2\n");
               /* reading is performed via fd1 until the first 'a' */
   while((n=read(fd1,&c,1)) > 0 && (c != 'a'))
               /* output the read in character on
                  standard output */
          write(1,&c,n);
/* reading is now performed via fd2
                  from the beginning of the file!!
                  to the end of the file */
while((n=read(fd2,&c,1)) > 0)
               /* output the read in character on
                  standard output */
          write(1,&c,n);
               /* reading continues via fd1 following
                  the first 'a', until the end of the file */
   while((n=read(fd1,&c,1)) > 0)
               /* output the read in character on
                  standard output */
          write(1,&c,n);
   return 0; 
}

See also

creat, creat64, fdopen, read, write, close