.\"   $Id: mbkfopen.3,v 1.1 2002/03/08 13:51:03 fred Exp $
.\" @(#)mbkfopen.2 2.11 91/08/22 ; Labo masi cao-vlsi; Author : Frederic Petrot
.if t \{\
.XS \n%
.ti 0.2i
mbkfopen
.XE
.XS4 \n%
.ti 0.2i
mbkfopen
.XE4 \}
.TH MBKFOPEN 3 "October 1, 1997" "ASIM/LIP6" "MBK UTILITY FUNCTIONS"
.SH NAME
mbkfopen \- open a file with several search pathes
.so buster/alliance/alc_origin.1.en.gz
.SH SYNOPSYS
.nf
.if n \{\
.ft B \}
.if t \{\
.ft CR \}
#include "mut.h"
FILE \(**mbkfopen(name, extension, mode)
char \(**name, \(**extension, \(**mode;
.ft R
.fi
.SH PARAMETERS
.TP 20
\fIname\fP
Name of the file to be opened
.TP
\fIextension\fP
Extension to the file name
.TP
\fImodel\fP
File opening mode
.SH DESCRIPTION
\fBmbkfopen\fP opens a file, searching it through the pathes given in the
environment variables \fBMBK_CATA_LIB\fP(1) and \fBMBK_WORK_LIB\fP(1).
Its main issue is to enable simple file access for any program that works
with mbk path environment variables.
.br
The file to be opened is called \fIname.extension\fP, if extension is not
\fBNULL\fP, else it is \fIname\fP. If \fIextension\fP is the empty string,
\fB""\fP, then the file name will be \fIname.\fP\~.
.br
The legal values for \fImode\fP are
.TP 20
\fBREAD_TEXT\fP
opens for reading
.TP
\fBWRITE_TEXT\fP
discards and opens for writting
.br
since disk access should be a straight forward operation knowing mbk's needs.
.LP
The search algorithm depends on the value of \fImode\fP.
If \fImode\fP is \fBWRITE_TEXT\fP, then the file is open for writting in
\fBMBK_WORK_LIB\fP(1). If \fImode\fP is \fBREAD_TEXT\fP then the file is first
searched through \fBMBK_WORK_LIB\fP(1), and if not found, through each directory
specified in \fBMBK_CATA_LIB\fP(1), in the order of declaration under unix.
No internal hash table is generated, in order to let the user choose its
directory priority.
As soon as the file is found, it is opened.
There is no check for redundant files in the specified pathes, since it is
neither illegal nor bad to have many files with the same names.
.SH RETURN VALUE
\fBmbkfopen\fP returns a pointer to the opened file.
If the file read or write access are violated, or the file not found,
a \fBNULL\fP pointer is returned.
.SH ERROR
.if n \{\
.ft B \}
.if t \{\
.ft CR \}
"\(**\(**\(** mbk error \(**\(**\(** mbkfopen : unknown file opening mode \fImode\fP"
.ft R
.RS
The \fImode\fP parameter is not one of the two legal values.
.RE
.SH EXAMPLE
.ta 3n 6n 9n 12n 15n 18n 21n
.nf
.if n \{\
.ft B \}
.if t \{\
.ft CR \}
#include "mut.h"
#include "mph.h"
phfig_list \(**load_vti_ph(name)
char \(**name;
{
FILE \(**file;
	if ((file = mbkfopen(name, "cp", READ_TEXT)) == NULL) {
		(void)fprintf(stderr, "Pfhhh, can't open \fIname.cp\fP\\n");
		EXIT();
	}
	ph_parse(file);
}
.ft R
.fi
.SH SEE ALSO
.BR mbk (1),
.BR MBK_CATA_LIB (1),
.BR MBK_WORK_LIB (1),
.BR loadlofig (3),
.BR loadphfig (3),
.BR savelofig (3),
.BR savephfig (3),
.BR fopen (3).


.so buster/alliance/alc_bug_report.1.en.gz