creat, creat64 - Create a new file (elementary)

Definition	#include <stdio.h> int creat(const char *f_name, int mode); int creat64(const char *f_name, int mode); creat and creat64 open a file for writing. If the file does not yet exist, it is created. Files that already exist are truncated to a length of 0. creat and creat64 return a file descriptor for subsequent elementary access operations (write, read). There is no functional difference between creat and creat64, except that a large file identifier is stored with the file description that is linked to the file descriptor, i.e. the O_LARGEFILE bit is set. A file descriptor is returned that can be used to extend the file over 2 GB. 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 creat. creat64 is then used implicitly with the appropriate parameters. Otherwise, you have to call creat64.
Parameters	const char *f_name A string specifying the name of the file to be opened. f_name can be: any valid BS2000 file name “link=linkname” linkname denotes a BS2000 link name int mode In BS2000 only the lbp switch,the nosplit switch and the O_RECORD entry are evaluated here. All other specifications in this parameter are ignored. However, they are necessary to create portable programs as they regulate protection bit assignment in the UNIX operating system. 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 creat, creat64 function will fail and errno is set to ENOSYS. The switch has further effects only when the file is closed. O_LBP When a file which has been newly created is closed, no marker is written and a valid LBP is set. 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 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. 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 creat, creat64 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 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.
Return val.	File descriptor	positive number used later to identify the file in elementary access operations (read, write).
	-1	if the file could not be opened, e.g. because too many files are open or because f_name is not a valid file or link name.
Notes	The BS2000 file name or link name may be written in lowercase and uppercase letters. It is automatically converted to uppercase letters. 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. 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)”. If an existing file is truncated to length 0, the catalog attributes of this file are preserved. A maximum of _NFILE files may be open simultaneously. _NFILE is defined as 2048 in <stdio.h>.
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. O_RECORD This switch functions as follows: 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.
Satz-E/A	Zum Eröffnen von Dateien mit satzorientierter Ein-/Ausgabe (Satz-E/A) kann beim Parameter modus die Konstante O_RECORD angegeben werden. Sie kann grundsätzlich mit jeder anderen Konstanten außer O_LBP kombiniert werden. O_RECORD Dieser Schalter bewirkt Folgendes: Die Funktion write schreibt einen Satz in die Datei. Bei SAM- und PAM-Dateien wird der Satz an die aktuelle Dateiposition geschrieben. Bei ISAM-Dateien wird der Satz an die Position geschrieben, die dem Schlüsselwert im Satz entspricht. Ist die Anzahl n der zu schreibenden Zeichen größer als die maximale Satzlänge, wird nur ein Satz mit maximaler Satzlänge geschrieben. Die restlichen Daten gehen verloren. Bei ISAM-Dateien wird ein Satz nur geschrieben, wenn er mindestens einen vollständigen Schlüssel enthält. Ist bei Dateien mit fester Satzlänge n kleiner als die Satzlänge, wird mit binären Nullen aufgefüllt. Beim Update eines Satzes in einer SAM- oder PAM-Datei darf die Länge des Satzes nicht verändert werden. Die Funktion write liefert auch bei Satz-E/A die Anzahl der tatsächlich geschriebenen Zeichen zurück.
Example	The program given below writes the contents of an input file to an output file. The output file is created as a new file with creat. The name of this file as well as the file attributes are defined by means of a ADD-FILE-LINK command (link name=LINK). The following command, for example, could be used to create an ISAM file named OUT.ISAM: /ADD-FILE-LINK LINK-NAME=LINK,FILE-NAME=OUT.ISAM,ACCESS-METHOD=ISAM #include <stdio.h> #include <stdlib.h> int main(void) { char name[50]; char buf; int fin, fout; printf("Name of the input file?\n"); gets(name); printf("File %s is being copied.\n", name); if ((fin = open(name,0)) == -1) { perror(name); exit(-1); } if ((fout = creat("link=link", 1)) == -1) { perror("link"); exit(-1); } while(read(fin, &buf, 1) > 0) { putchar(buf); /* Log to stdout */ write(fout, &buf, 1); } close(fin); close(fout); return 0; }
See also	close, fdopen, open, open64, read, write, perror