TipcMsgFileCreate

Name

TipcMsgFileCreate — create a message file

Synopsis

T_IPC_MSG_FILE TipcMsgFileCreate(file_name, create_mode) 
T_STR file_name; 
T_IPC_MSG_FILE_CREATE_MODE create_mode; 

Arguments

file_name — name of file to use for message file

create_mode — how to create the file. Use one of these modes:

Return Values

A message file if successful, NULL otherwise.

Diagnostics

If TipcMsgFileCreate fails, it returns NULL and sets the global SmartSockets error number to one of:

Description

TipcMsgFileCreate creates a new message file. There are two possible formats for message files:

If create_mode is T_IPC_MSG_FILE_CREATE_READ, file_name must be the name of an existing file. The message file is opened for reading in an existing file, and TipcMsgFileRead can be used to read messages from the message file. TipcMsgFileCreate automatically tries to detect whether the file is in text or binary format.

If create_mode is T_IPC_MSG_FILE_CREATE_WRITE, the message file is created for writing in text format, and TipcMsgFileWrite can be used to write messages to the message file. If file_name already exists, it is overwritten. If file_name does not already exist, a file is created.

If create_mode is T_IPC_MSG_FILE_CREATE_WRITE_BINARY, the message file is created for writing in binary format, and TipcMsgFileWrite can be used to write messages to the message file.If file_name already exists, it is overwritten. If file_name does not already exist, a file is created.

If create_mode is T_IPC_MSG_FILE_CREATE_APPEND, the message file is opened for appending, and TipcMsgFileWrite can be used to append messages to the message file. TipcMsgFileCreate automatically tries to detect whether the file is in text or binary format. If file_name already exists, the existing file is appended to. If file_name does not already exist, a file is created.

To create a message file from an existing file (such as stdin, stdout, or stderr), use TipcMsgFileCreateFromFile.

Binary message files can be shared between dissimilar architectures (from Digital Alpha AXP to Sun SPARC, for example), and TipcMsgFileCreate automatically converts the file data.

Caution

If create_mode is T_IPC_MSG_FILE_CREATE_WRITE or T_IPC_MSG_FILE_CREATE_WRITE_BINARY, any existing file is overwritten.

If create_mode is T_IPC_MSG_FILE_CREATE_READ, the function is trying to read to an existing file. If there is no existing file, the function fails and returns an error.

See Also

TipcMsgFileCreateFromFile, TipcMsgFileDestroy, TipcMsgFileRead, TipcMsgFileWrite

Examples

This example creates a message file for reading from the existing file data.msg with TipcMsgFileCreate:

T_IPC_MSG_FILE msg_file; 
 
msg_file = TipcMsgFileCreate("data.msg", 
T_IPC_MSG_FILE_CREATE_READ); 
if (msg_file == NULL) { 
  return;  /* error */ 
}