int Set_My_Proc_Details( const char *group_name,
const char *prog_name,
const char *fifo_prefix,
const char *fifo_name,
mode_t fifo_mode,
int flags );
This call sets the base data used when registering in a shared
memory segment. The group name and program name are provide
a way to catagorise sets of programs and differentiate between
programs within a group.
The group_name parameter, if provided, is a informational parameter which gives the logical group the program belongs in.
The program_name parameter, if provided, gives the logical name of the program.
The fifo_prefix if provided, gives the directory where the pipe for the process should be created. If the parameter is NULL or empty then the routine will use
eval_config_default( "PIPE_DIR", "$HOME/pipe" )
as a default.
The fifo_name parameter, if provided, gives the full name to be used for the process fifo.
The fifo_mode parameter gives the access mode for the fifo if it has not already been created.
The flags parameter is a set of bit flags which modify the behaviour of the routine. The three values, which can be bit-wise or-ed together are
#define SHM_INHERIT_GROUP BIT(0)
#define SHM_INHERIT_PROGRAM BIT(1)
#define SHM_AUTOMAGIC_PIPE BIT(2)
If SHM_INHERIT_GROUP or SHM_AUTOMAGIC_PIPE is set
then the group_name parameter is ignored, and the value is
taken from the environment value GROUP_NAME.
If SHM_INHERIT_PROGRAM or SHM_AUTOMAGIC_PIPE is set then the program_name parameter is ignored and the value is taken from the environment value PROGRAM_NAME. If this is not set then the value unknown is used.
If SHM_AUTOMAGIC_PIPE is set then the pipe_name parameter is ignored and a string based on group name, program name and pid is used.
int Register_Process_Details( const void *hint );
int Deregister_Process_Details( const void *hint );
The Register_Process_Details routine takes a hint to describe
which segment to use. This is combined with the details
previously sent to Set_My_Proc_Details and used to
register in the segment indicated. If Set_My_Proc_Details has
not been called, it is called automatically as
Set_My_Proc_Details( NULL, NULL, NULL, NULL,
Get_SODB_Privs(hint), SHM_AUTOMAGIC_PIPE );
The Deregister_Process_Details routine takes a hint to identify the segment in question. It removes the process details from the segment.
int Inform_Process_Str( const void *hint, const char *pid_str );
int Inform_Process_Pid( const void *hint, pid_t pid );
These two routines provide the mechanism to inform another process
that there is some work for it to do. They both take a hint as to
which segment to use, and then a pid number in some form (pid_t or
string of the pid).
The routines then search the process details in the segment provided and, if found, open the fifo associated with the supplied pid and write a token to the fifo, and close the file. Both routines return 1 on success and 0 on failure (cannot find process, cannot open fifo).
int Inform_Named_Pipe( const char *pipe_name );
This routine simply perfors the last steps of the previous routines
and opens the named pipe, writes a token to it and closes the pipe.
The routine return 1 on success and 0 on failure.
int Wait_Process_Pipe( void );
This routine is used to wait for an event for oneself. It does
this by reading a single byte from its own fifo. The return value
from the routine is either 0 (unknown segment, process not registered)
with errno set to 0, or the return from the read() call,
in this case the normal errno processing should be performed.
int Get_Process_Pipe_fd( void );
This routine returns the file descriptor for the fifo
opened when the process was registered. The return value
is -1 if the process details could not be found or the file
was not opened. This routine would normally be used in conjunction
with other file descriptors in a select() call.
int Add_This_Pid_Resource( const void *hint, bpo_Node_t *nptr );
This function allows for an allocated block from a segment to be attached
to the process registration. Thus, when the process completes and
deregisters (or is cleaned up, see below) any blocks are also freed.
void *comms_shm_attach( const char *config_name, int flags );
This function provides a way to connect to a standardised shared memory
segment which can be used for core communications activity and small
application specific data blocks.
The config_nameparameter must be a non-NULL parameter and specify the name of a file containing the configuration details of the standard communications shared memory segment. Details of the required configuration variables can be found here.
The flags parameter should be zero or SODB_READ_CONFIG which causes the configuration file to read into a configuration space of the same name.
void comms_shm_detach( void );
This function provides a way to detach the standard communications shared
memory segment.
void *get_comms_hint( void );
This function returns a pointer to the standard communications
shared memory segment if it is attached or NULL otherwise.
/* Read configuration file, either some default or a
command line option
*/
read_config_file( config_file );
/* Set the process details if they will not inherit correctly */
if (getenv("PROGRAM_NAME")==NULL)
Set_My_Proc_Details( NULL, mpbasename(argv[0]),
NULL, NULL, 0600, 0 );
/* get the name of the shared memory configuration
file from the main configuration file
*/
shm_file = eval_config_default( "SHM_CONFIG",
"$HOME/config/shm.cfg" );
/* Attach to shared memory */
comms_hint = comms_shm_attach( shm_file, SODB_READ_CONFIG );
int scan_dead_pipes( const char *dir_name );
This function scans the provided directory for pipe files
whose name is of the format xxxx.nnnn. It then decodes
the nnnn and tests whether a process of that id is dead. If it
is then the pipe is removed.
int Remove_Shm_Process( const void *hint, const char *pid_str );
This function removes the details of the supplied process from
the provided segment if the process is registerd in it and appears
to be dead. In addition, any previously attached process specific
resources added above will also be freed.