Watcom C Library Reference : sopen, sound, spawn Functions
sopen
Synopsis : #include <io.h>
#include <fcntl.h>
#include <sys\stat.h>
#include <sys\types.h>
#include <share.h>
int sopen( const char *filename, int access, int share, ... );
Description : The sopen function opens a file at the operating system level for shared access. The name of the file to be opened is given by filename. The file will be accessed according to the access mode specified by access. When the file is to be created, the optional argument must be given which establishes the future access permissions for the file. Additionally, the sharing mode of the file is given by the share argument. The optional argument is the file permissions to be used when O_CREAT flag is on in the access mode.
The access mode is established by a combination of the bits defined in the <fcntl.h> header file. The following bits may be set:
| Mode | Meaning |
| O_RDONLY | permit the file to be only read. |
| O_WRONLY | permit the file to be only written. |
| O_RDWR | permit the file to be both read and written. |
| O_APPEND | causes each record that is written to be written at the end of the file. |
| O_CREAT | has no effect when the file indicated by filename already exists; otherwise, the file is created; |
| O_TRUNC | causes the file to be truncated to contain no data when the file exists; has no effect when the file does not exist. |
| O_BINARY | causes the file to be opened in binary mode which means that data will be transmitted to and from the file unchanged. |
| O_TEXT | causes the file to be opened in text mode which means that carriage-return characters are written before any linefeed character that is written and causes carriage-return characters to be removed when encountered during reads. |
| O_NOINHERIT | indicates that this file is not to be inherited by a child process. |
| O_EXCL | indicates that this file is to be opened for exclusive access. If the file exists and O_CREAT was also specified then the open will fail (i.e., use O_EXCL to ensure that the file does not already exist). |
When neither O_TEXT nor O_BINARY are specified, the default value in the global variable _fmode is used to set the file translation mode. When the program begins execution, this variable has a value of O_TEXT.
O_CREAT must be specified when the file does not exist and it is to be written.
When the file is to be created (O_CREAT is specified), an additional argument must be passed which contains the file permissions to be used for the new file. The access permissions for the file or directory are specified as a combination of bits (defined in the <sys\stat.h> header file).
The following bits define permissions for the owner.
| Permission | Meaning |
| S_IRWXU | Read, write, execute/search |
| S_IRUSR | Read permission |
| S_IWUSR | Write permission |
| S_IXUSR | Execute/search permission |
The following bits define permissions for the group.
| Permission | Meaning |
| S_IRWXG | Read, write, execute/search |
| S_IRGRP | Read permission |
| S_IWGRP | Write permission |
| S_IXGRP | Execute/search permission |
The following bits define permissions for others.
| Permission | Meaning |
| S_IRWXO | Read, write, execute/search |
| S_IROTH | Read permission |
| S_IWOTH | Write permission |
| S_IXOTH | Execute/search permission |
The following bits define miscellaneous permissions used by other implementations.
| Permission | Meaning |
| S_IREAD | is equivalent to S_IRUSR (read permission) |
| S_IWRITE | is equivalent to S_IWUSR (write permission) |
| S_IEXEC | is equivalent to S_IXUSR (execute/search permission) |
All files are readable with DOS; however, it is a good idea to set S_IREAD when read permission is intended for the file.
The sopen function applies the current file permission mask to the specified permissions (see umask).
The shared access for the file, share, is established by a combination of bits defined in the <share.h> header file. The following values may be set:
| Value | Meaning |
| SH_COMPAT | Set compatibility mode. |
| SH_DENYRW | Prevent read or write access to the file. |
| SH_DENYWR | Prevent write access of the file. |
| SH_DENYRD | Prevent read access to the file. |
| SH_DENYNO | Permit both read and write access to the file. |
you should consult the technical documentation for the DOS system that you are using for wore detailed information about these sharing modes.
Returns : If successful, sopen returns a handle for the file. When an error occurs while opening the file, -1 is returned. When an error has occurred, errno contains a value indicating the type of error that has been detected.
Errors : When an error has occurred, errno contains a value indicating the type of error that has been detected.
| Constant | Meaning |
| EACCES | Access denied because path specifies a directory or a volume D, or sharing mode denied due to a conflicting open. |
| EMFILE | No more handles available (too many open files) |
| ENOENT | Path or file not found |
See Also : chsize, close, creat, dup, dup2, eof, exec Functions, filelength, fileno, fstat, isatty, lseek, open, read, setmode, stat, tell, write, umask
Example :
#include <sys\stat.h>
#include <sys types.h>
#include <fcntl.h>
#include <share.h>
void main( )
{
int handle;
/* open a file for output */
/* replace existing file if it exists */
handle = sopen( "file", O_WRONLY | O_CREAT | O_TRUNC,
S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP,
SH_DENYWR );
/* read a file which is assumed to exist */
handle = sopen( "file", O_RDONLY, SH_DENYWR );
/* append to the end of an existing file */
/* write a new file if file does not exist */
handle = sopen( "file", O_WRONLY | O_CREAT | O_APPEND,
S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP,
SH_DENYWR );
}
Classification : WATCOM
Systems : All
sound
Synopsis : #include <i86.h>
void sound( unsigned frequency );
Description : The sound function turns on the PC's speaker at the specified frequency. The frequency is Hertz (cycles per second). The speaker can be turned off by calling the nosound nction after an appropriate amount of time.
Returns : The sound function has no return value.
See Also : delay, nosound
Example :
#include <i86.h>
/*
The numbers in this table are the timer divisors necessary to produce
the pitch indicated in the lowest octave that is supported by the "sound" function.
To raise the pitch by N octaves, simply divide the number in the table by 2**N since
a pitch which is an octave above another has double the frequency of the original pitch.
The frequency obtained by these numbers is given by 1193180 / X
where x is the number obtained in the table.
*/
unsigned short Notes[] = {
19327, /* C b */
18242, /* C */
17218, /* C # (D b) */
16252, /* D */
15340, /* D # (E b) */
14479, /* E (F b) */
13666, /* F (E #) */
12899, /* F # (G b) */
12175, /* G */
11492, /* G # (A b) */
10847, /* A (B b) */
10238, /* A # (C b) */
9664, /* B (C b) */
9121, /* B # */
0
};
#define FACTOR 1193180
#define OCTAVE 4
void main( )
{
/* play the scale */
int i;
for( i = 0; Notes[i]; ++i ) {
sound( FACTOR / (Notes[i] / (1 << OCTAVE) ) );
delay( 200 );
nosound( );
}
}
Classification : Intel
Systems : DOS, Win, QNX
spawn Functions
Synopsis : #include <process.h>
int spawnl( mode, path, arg0, arg1..., argn, NULL );
int spawnle( mode, path, arg0, arg1..., argn, NULL, envp );
int spawnlp( mode, file, arg0, arg1..., argn, NULL );
int spawnlpe( mode, file, arg0, arg1..., argn, NULL, envp );
int spawnv( mode, path, argv );
int spawnve( mode, path, argv, envp );
int spawnvp( mode, file, argv );
int spawnvpe( mode, file, argv, envp);
int mode; /* mode for parent */
const char *path; /* file name incl. path */
const char *file; /* file name */
const char *arg0, ..., *argn; /* arguments */
char *const argv[]; /* array of arguments */
char *const envp[]); /* environment strings */
Description : The spawn functions create and execute a new child process, named by pgm. The value of mode determines how the program is loaded and how the invoking program will behave after the invoked program is initiated:
| Mode | Meaning |
| P_WAIT | The invoked program is loaded into available memory, is executed, and then the original program resumes execution. |
| P_NOWAIT | Causes the current program to execute concurrently with the new child process. |
| P_NOWAITO | Causes the current program to execute concurrently with the new child process. The functions wait and cwait are ignored. |
| P_OVERLAY | The invoked program replaces the original program in memory and is executed. No return is made to the original program. This is equivalent to calling the appropriate exec function. P_OVERLAY is only supported on those systems that also support the exec function (see the description of the exec function for more information). |
The program is located by using the following logic in sequence:
| 1. An attempt is made to locate the program in the current working directory if no directory specification precedes the program name; otherwise, an attempt is made in the specified directory. |
| 2. If no file extension is given, an attempt is made to find the program name, in the directory indicated in the first point, with .COM concatenated to the end of the program name. |
| 3. If no file extension is given, an attempt is made to find the program name, in the directory indicated in the first point, with .EXE concatenated to the end of the program name. |
| 4. When no directory specification is given as part of the program name, the spawnlp, spawnlpe, spawnvp, and spawnvpe functions will repeat the preceding three steps for each of the directories specified by the PATH environment variable. The command path c:\my apps;d: \lib\applns indicates that the two directories C:\myapps d: \lib\applns are to be searched. The DOS PATH command (without any directory specification) will cause the current path definition to be displayed. |
An error is detected when the program cannot be found.
Arguments are passed to the child process by supplying one or more pointers to character strings as arguments in the spawn call. These character strings are concatenated with spaces inserted to separate the arguments to form one argument string for the child process. The length of this concatenated string must not exceed 128 bytes for DOS systems.
The arguments may be passed as a list of arguments (spawnl, spawnle, spawnlp and spawnlpe) or as a vector of pointers (spawnv, spawnve, spawnvp, and spawnvpe). At least one argument, arg0 or argv[0], must be passed to the child process. By convention, this first argument is a pointer to the name of the program.
If the arguments are passed as a list, there must be a NULL pointer to mark the end of the argument list. Similarly, if a pointer to an argument vector is passed, the argument vector must be terminated by a NULL pointer.
The environment for the invoked program is inherited from the parent process when you use the spawnl, spawnlp, spawnv and spawnvp functions. The spawnle, spawnlpe, spawnve and spawnvpe functions allow a different environment to be passed to the child process through the envp argument. The argument envp is a pointer to an array of character pointers, each of which points to a string defining an environment variable. The array is terminated with a NULL pointer. Each pointer locates a character string of the form
variable=value
that is used to define an environment variable. If the value of envp is NULL, then the child process inherits the environment of the parent process.
The environment is the collection of environment variables whose values that have been defined with the DOS SET command or by the successful execution of the putenv function. A program may read these values with the getenv function.
Returns : When the value of mode is P_WAIT, then the return value from spawn is the exit status of the child process.
When the value of mode is P_NOWAIT or P_NOWAITO, then the return value from spawn is the process id of the child process. To obtain the exit code for a process spawned with P_NOWAIT, you must call the wait or cwait function specifying the process id. The exit code cannot be obtained for a process spawned with P_NOWAITO.
When an error is detected while invoking the indicated program, spawn returns -1 and errno is set to indicate the error.
Errors : When an error has occurred, errno contains a value indicating the type of error that has been detected.
| Constant | Meaning |
| E2BIG | The argument list exceeds 128 bytes, or the space required for the environment information exceeds 32K. |
| EINVAL | The mode argument is invalid. |
| ENOENT | Path or file not found |
| ENOMEM | Not enough memory is available to execute the child process. |
See Also : abort, atexit, cwait, exec Functions, exit, _exit, getcmd, getenv, main, putenv, system, wait
Example :
#include <stddef.h>
#include <process.h>
spawnl( P_WAIT, "myprog", "myprog", "ARG1", "ARG2", NULL );
The preceding invokes "myprog" as if
myprog ARG1 ARG2
had been entered as a command to DOS. The program will be found if one of
myprog.
myprog.com
myprog.exe
is found in the current working directory.
#include <stddef.h>
#include <process.h>
char *env_list[] = { "SOURCE=MYDATA",
"TARGET=OUTPUT",
"lines=65",
NULL
};
spawnle( P_WAIT, "myprog", "myprog", "ARG1", "ARG2", NULL, env_list );
The preceding invokes "myprog" as if
myprog ARG1 ARG2
had been entered as a command to DOS. The program will be found if one of
myprog.
myprog.com
myprog.exe
is found in the current working directory. The DOS environment for the invoked program will consist of the three environment variables SOURCE, TARGET and lines.
#include <stddef.h>
#include <process.h>
char *arg_list[] = { "myprog", "ARG1", "ARG2", NULL };
spawnv( P_WAIT, "myprog", arg_list );
The preceding invokes "myprog" as if
myprog ARG1 ARG2
had been entered as a command to DOS. The program will be found if one of
myprog.
myprog.com
myprog.exe
is found in the current working directory.
Classification : WATCOM
Systems : spawnl - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT
spawnle - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT
spawnlp - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT
spawnlpe - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT
spawnv - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT
spawnve - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT
spawnvp - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT
spawnvpe - DOS, QNX, OS/2 1.x(all), OS/2 2.x, NT
This manual describes the WATCOM C library for DOS, Windows, and OS/2, It includes the Standard C Library (as defined in the ANSI C Standard).
WATCOM C Language Reference manual describes the ANSI C Programming language and extensions to it which are supported by WATCOM C/C++ (32bit)
