Creates a new file.
Format
#include <fcntl.h>
int creat (const char *file_spec, mode_t mode); (ISO POSIX-1)
int creat (const char *file_spec, mode_t mode, . . . );
(DEC C Extension)
1 – Arguments
file_spec
A null-terminated string containing any valid file specification.
mode
An unsigned value that specifies the file-protection mode. The
compiler performs a bitwise AND operation on the mode and the
complement of the current protection mode.
You can construct modes by using the bitwise OR operator (|) to
create mode combinations. The modes are:
0400 OWNER:READ
0200 OWNER:WRITE
0100 OWNER:EXECUTE
0040 GROUP:READ
0020 GROUP:WRITE
0010 GROUP:EXECUTE
0004 WORLD:READ
0002 WORLD:WRITE
0001 WORLD:EXECUTE
The system is given the same privileges as the owner. A WRITE
privilege implies a DELETE privilege.
NOTE
To create files with OpenVMS RMS default protections using
the UNIX system-call functions umask, mkdir, creat, and
open, call mkdir, creat, and open with a file-protection
mode argument of 0777 in a program that never specifically
calls umask. These default protections include correctly
establishing protections based on ACLs, previous versions of
files, and so on.
In programs that do vfork/exec calls, the new process image
inherits whether umask has ever been called or not from
the calling process image. The umask setting and whether
the umask function has ever been called are both inherited
attributes.
. . .
An optional argument list of character strings of the following
form:
"keyword = value", . . . ,"keyword = value"
Or in the case of "acc" or "err", this form:
"keyword"
Here, keyword is an RMS field in the file access block (FAB) or
record access block (RAB); value is valid for assignment to that
field. Some fields permit you to specify more than one value. In
these cases, the values are separated by commas.
The RMS callback keywords "acc" and "err" are the only keywords
that do not take values. Instead, they are followed by a pointer
to the callback routine to be used, followed by a pointer to a
user-specified value to be used as the first argument of the
callback routine. For example, to set up an access callback
routine called acc_callback whose first argument is a pointer
to the integer variable first_arg in a call to open, you can use
the following statement:
open("file.dat", O_RDONLY, 0 ,"acc", acc_callback, &first_arg)
The second and third arguments to the callback routine must be
pointers to a FAB and RAB, respectively, and the routine must
have a return type of int. If the callback returns a value less
than 0, the open, creat, or fopen fails. The error callback can
correct the error condition and return a status greater than
or equal to 0 to continue the creat call. Assuming the previous
open statement, the function prototype for acc_callback would be
similar to the following statement:
#include <rms.h>
int acc_callback(int *first_arg, struct FAB *fab, struct RAB *rab);
FAB and RAB are defined in the <rms.h> header file, and the
actual pointers passed to the routine are pointers to the RAB
and FAB being used to open the file file.dat.
If an access callback routine is established, then it will be
called in the open-type routine immediately before the call to
the RMS function sys$create or sys$open. If an error callback
routine is established and an error status is returned from the
sys$create or sys$open function, then the callback routine will
be invoked immediately after the status is checked and the error
value is discovered.
NOTE
Any manipulation of the RAB or FAB in a callback function
could lead to serious problems in later calls to the
C RTL I/O functions.
RMS Valid Keywords and Values describes the RMS keywords and
values.
Table REF-3 RMS Valid Keywords and Values
Keyword Value Description
"acc" callback Access callback routine.
"alq = n" decimal Allocation quantity.
"bls = n" decimal Block size.
"ctx = bin" string No translation of '\n' to the terminal.
Use this for writing binary data to
files.
"ctx = cvt" string Negates a previous setting of
"ctx=nocvt". This is the default.
"ctx = string No conversion of Fortran carriage-control
nocvt" bytes.
"ctx = rec" string Forces record mode access.
"ctx = stm" string Forces stream mode access.
"ctx = string Causes records to be written only when
xplct" explicitly specified by a call to fflush,
close, or fclose.
"deq = n" decimal Default extension quantity.
"dna = string Default file-name string.
filespec"
"err" callback Error callback routine.
"fop = val, File-processing options:
val , . . . "
ctg Contiguous.
cbt Contiguous-best-try.
dfw Deferred write; only applicable to files
opened for shared access.
dlt Delete file on close.
tef Truncate at end-of-file.
cif Create if nonexistent.
sup Supersede.
scf Submit as command file on close.
spl Spool to system printer on close.
tmd Temporary delete.
tmp Temporary (no file directory).
nef Not end-of-file.
rck Read check compare operation.
wck Write check compare operation.
mxv Maximize version number.
rwo Rewind file on open.
pos Current position.
rwc Rewind file on close.
sqo File can only be processed in a
sequential manner.
"fsz = n" decimal Fixed header size.
"gbc = n" decimal The requested number of global buffers
for a file.
"mbc = n" decimal Multiblock count.
"mbf = n" decimal Multibuffer count.
"mrs = n" decimal Maximum record size.
"pmt=usr- string Prompts for terminal input. Any RMS input
prmpt" from a terminal device will be preceded
by "usr-prmpt" when this option and
"rop=pmt" are specified.
"rat = val, Record attributes:
val . . . "
cr Carriage-return control.
blk Disallow records to span block
ftn boundaries.
none Fortran print control.
prn Explicitly forces no carriage control.
Print file format.
"rfm = val" Record format:
fix Fixed-length record format.
stm RMS stream record format.
stmlf Stream format with line-feed terminator.
stmcr Stream format with carriage-return
terminator.
var Variable-length record format.
vfc Variable-length record with fixed
udf control.
Undefined.
"rop = val, Record-processing operations:
val . . . "
asy Asynchronous I/O.
cco Cancels Ctrl/O (used with Terminal I/O).
cvt Capitalizes characters on a read from the
terminal.
eof Positions the record stream to the end-
of-file for the connect operation only.
nlk Do not lock record.
pmt Enables use of the prompt specified
by "pmt=usr-prmpt" on input from the
terminal.
pta Eliminates any information in the type-
ahead buffer on a read from the terminal.
rea Locks record for a read operation for
this process, while allowing other
accessors to read the record.
rlk Locks record for write.
rne Suppresses echoing of input data on the
screen as it is entered on the keyboard.
rnf Indicates that Ctrl/U, Ctrl/R, and DELETE
are not to be considered control commands
on terminal input, but are to be passed
to the application program.
rrl Reads regardless of lock.
syncsts Returns a success status of RMS$_SYNCH if
the requested service completes its task
immediately.
tmo Timeout I/O.
tpt Allows put/write services using
sequential record access mode to occur
at any point in the file, truncating the
file at that point.
ulk Prohibits RMS from automatically
unlocking records.
wat Wait until record is available, if
currently locked by another stream.
rah Read ahead.
wbh Write behind.
"rtv=n" decimal The number of retrieval pointers that RMS
has to maintain in memory (0 to 127,255).
"shr = val, File sharing options:
val, . . . "
del Allows users to delete.
get Allows users to read.
mse Allows multistream connects.
nil Prohibits file sharing.
put Allows users to write.
upd Allows users to update.
upi Allows one or more writers.
nql No query locking (file level).
"tmo = n" decimal I/O timeout value.
In addition to these options, any option that takes a key value
(such as "fop" or "rat") can be negated by prefixing the value
with "no". For example, specify "fop=notmp" to clear the "tmp"
bit in the "fop" field.
NOTES
o While these options provide much flexibility and
functionality, many of them can also cause severe
problems if not used correctly.
o You cannot share the default VSI C for OpenVMS stream
file I/O. If you wish to share files, you must specify
"ctx=rec" to force record access mode. You must also
specify the appropriate "shr" options depending on the
type of access you want.
o If you intend to share a file opened for append, you must
specify appropriate share and record-locking options, to
allow other accessors to read the record. The reason for
doing this: the file is positioned at the end-of-file by
reading records in a loop until end-of-file is reached.
For more information on these options, see the OpenVMS Record
Management Services Reference Manual.
2 – Description
The C RTL opens the new file for reading and writing, and
returns the corresponding file descriptor.
If the file exists:
o A version number one greater than any existing version is
assigned to the newly created file.
o By default, the new file inherits certain attributes from
the existing version of the file unless those attributes are
specified in the creat call. The following attributes are
inherited:
- Record format (FAB$B_RFM)
- Maximum record size (FAB$W_MRS)
- Carriage control (FAB$B_RAT)
- File protection
o When a new version of a file is created, and the named file
already exists as a symbolic link, the file to which the
symbolic link refers is created.
If the file did not previously exist:
o It is given the file protection that results from performing
a bitwise AND on the mode argument and the complement of the
current protection mask.
o It defaults to stream format with line-feed record separator
and implied carriage-return attributes.
See also open, close, read, write, and lseek in this section.
3 – Return Values
n A file descriptor.
-1 Indicates errors, including protection
violations, undefined directories, and
conflicting file attributes.