/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * COPYING NOTES
 *
 * shmtool.h -- header of functions to manage shared memory
 * 
 * Copyright (C) 1995 Scott Burkett <scottb@IntNet.net>.
 *   as heavily derived from the Chapter 6 of The Linux Programmer's Guide
 * Copyright (C) 2002 Roberto A. Foglietta <robang@libero.it>
 * Copyright (C) 2002 GEA-Automotive <fogliettar@gea-automotive.com>
 *
 *   This program is free software; you can redistribute it and/or modify
 *   it under the terms of the GNU General Public License as published by
 *   the Free Software Foundation; either version 2 of the License.
 *
 *   This program is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with this program; if not, write to the Free Software
 *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
 */

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 
 * REVISION NOTES:
 * released 17-10-2002 by Roberto A. Foglietta
 * modified 29-05-2003 by Roberto A. Foglietta
 */

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * DOCUMENTATION LINKS:
 * http://www.tldp.org/LDP/lpg/node65.html
 */ 
 
#ifndef _SHMTOOL_H
#define _SHMTOOL_H
#define SEGSIZE 10240

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/shm.h>


/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * FUNCTION SYNTAX
 */ 
 
 
/* getidshm 
 *
 * RAF 2003-05-29:
 * Get shared memory identification number from uniq key
 */
#define getidshm(key) shmget(key, 0, 0)
 
/* initshm 
 *
 * Create or open as client a shared memory. Returns identificaction number of 
 * the shared memory or an negative  number in case of failure.
 *
 * RAF 2003-05-29:
 * The 2nd argument works as flag if it's non zero and shared memory exist it
 * will mark as deleted before trying to create.
 *
 * TODO: to have a different size of shared memory modify SEGSIZE or transform
 *       it in a external variable that keeps record of the variable size.
 *          example: int initshm(key_t key, unsigned long size, int del)      
 *       but in this case you have to modify writeshm too.                 
 */
int     initshm (key_t key, int del);

/* readshm
 *
 * This function works only with only-ASCII-text contenent of the shared memory
 * because the use of strdup doesn't allow the use of character \0 inside the 
 * shared memory. It returns a just-in-time allocated buffer containing the 
 * contenent of the shared memory.
 *
 * TODO: save in the shared memory a struct that contain the length could be
 *       useful to manage binary contenents.
 *
 * N.B.: remember to free the buffer returned after you've finished to use it!
 */
char  * readshm(int shmid);

/* writeshm
 * 
 * This function overwrite completly the shared memory, it works only with 
 * ASCII-text contenent because using strncpy. The function strncpy avoid to
 * go over the share memory size defined in SEGSIZE define/variable.
 */
int     writeshm(int shmid, char *text);

/* removeshm 
 * 
 * This function delete completly the shared memory. 
 * Return 0 on success, -1 on error.
 */
int    removeshm(int shmid);

/* changemode
 * 
 * This function change the permissions of the shared memory. 
 * Return 0 on success, -1 on error.
 */
int    changemode(int shmid, char *mode);


#endif /* _SHMTOOL_H */