.TH "OPENSF" 1csound CARL
.SH NAME
opensf - closesf 
- user-level commands to open/close sound files.
.SH SYNOPSIS
.B opensf 
[flags] [file] > sound_file_descriptor
.sp
.B closesf 
files
.sp
or
.sp
.B closesf
\< sound_file_descriptor
.nf
flags for 
.B opensf:
.RS .5i
-w  open file for writing
-r  open file for reading
-rw open file for read/writing
.RE
.sp
Additional flags for write mode: (default in parenthesis)
.RS .5i
-cN  channels: 1, 2, 4, (default: 1) 
-RN  sampling rate: positive integers, (default: DHISR)
-oc output packing s (short), f (float), (default: s)
-TN  file size (expressed as time in seconds), (default: approx. 3s)
-CN  file size (expressed in cylinders) (default: 1)
-tc  realtime flag: r (realtime), n (not realtime), (default: n)
-rs  remark: quoted text string
-Is  include file: unix filename
-pN  file protection: 0000 - 0666, (default: 0644)
.sp
N is a number, c is a character, s is a quoted string.
.RE
.fi
.SH DESCRIPTION
Flags for 
.B opensf 
are a subset of those for
.B sndout(1csound).
Omitted are the -i flag and -b, -e, and -d flags.
.PP
The function of
.B opensf
and
.B closesf
is to allow other than 
.I csound
programs to access the 
.I csound 
system in a controlled
way.  Ordinarily, a program's only access to 
.I csound 
files is via 
.B sndin 
and
.B sndout,
which read/write from/to the standard input/output, respectively.  However,
it is useful for non-csound 
system programs to be able to access sound files.  For instance, 
.B cmusic,
which is not a program in the
.I csound
system, can still read
.I csound 
files via its
.I sndfile
unit generator.  
.PP
.I csound 
system 
uses the UNIX file protection
scheme to assure the integrity of
.I csound
system tables and files.  At CARL, all files, directories and raw devices
associated with the 
.I csound
system are given a protection code which allows write access only to a
pseudo-user named
.I disk,
and all
.I csound
programs are made set-user-id to this pseudo-user.  Thus, all 
.I csound
i/o is done under the name of this pseudo-user.
But this mechanism does not make it easy for others to write programs
that use the 
.I csound
file management routines.
The problem is then
how to let user programs other than those owned by
.I disk
access 
.I csound 
files?
.PP
The mechanism for updating a 
.I csound
file from an unprivileged process is for that process to execute
an 
.B opensf()
or
.B closesf()
subroutine calls.  These subroutines invoke the 
.B opensf
and
.B closesf
program via 
.B fork().
Since the programs
.B opensf
and
.B closesf
have disk pseudo-user permission, then can initiate the open or close
request.
.PP
In a typical sequence,  the user process invokes the subroutine
.B opensf()
which forks an
.B opensf
process and
requests a read operation.  
.B opensf
returns the sound file descriptor 
.I (sfd) 
for the file on its
standard output which is read in by
.B opensf()
in the user process.
The user process then uses this 
.I sfd
to access the disk with
.B sndi()
or
.B fsndi().
The user process then calls
.B closesf()
which forks a 
.B closesf
process to close the sound file.
.SH FILE MODES AND ALLOCATION
New files are created by default as 
.I non-realtime.
This simply means that the system does not need to fit the file into
one contiguous block.  No space is claimed for a new file so created
until the first attempt to put something in it.  A new file will be
made 
.I realtime
by mentioning any of the following flags:
.IP -tn
sets file to realtime and claims 1 cylinder by default;
.IP -TN
sets file to realtime and claims enough cylinders for time 
in seconds requested.
.IP -CN
sets file to realtime and N cylinders.
.SH SEE ALSO
sndin(1csound), sndout(1csound),
opensf(3csound), closesf(3csound).
