#include <stdio.h>

int scanf (

   const char *format,

   ...

);

server

scanf reads input from the standard input stream stdin. It reads characters (via getc), interprets them according to the given format and stores the resulting values in the locations pointed to by the pointer arguments following format.

The exact meaning of the arguments to scanf is the same as that of the arguments of the same name to the function fscanf.

In fact, the call scanf(format, ...); is equivalent to fscanf(stdin, format, ...);

If an end-of-file or input error occurs before any conversion is done, fscanf returns EOF. Otherwise, it returns the number of input items successfully converted and stored.

#include <sema.h>

void sema_init (

   SEMA *s,

   int   v

);

 stand-alone

stack: 0 bytes

This function initializes the semaphore variable pointed to by s to an initial state in which:

If a semaphore is left uninitialized, the first sema_signal or sema_wait operation on the semaphore will cause the system to behave unpredictably.

The server synchronisation semaphore, par_sema, is initialized for you; do not initialize it.

See also static_sema_init.

#include <sema.h>

void sema_signal (

   SEMA *s

);

 stand-alone

stack: 0 bytes

If there are threads waiting for the semaphore pointed to by s, the first one that waited is chosen and made able to execute again. The value of the semaphore under these conditions is 0, and remains unchanged.

Otherwise, when there are no threads waiting for the semaphore pointed to by s, its value is simply increased by 1.

You must use this function only with semaphores that have already been initialised (see sema_init).

#include <sema.h>

void sema_signal_n (

   SEMA *s,

   int   n

);

 stand-alone

stack: 32 bytes

This function calls the function sema_signal n times, in sequence. The parameter n must be greater than or equal to zero.

You must use this function only with semaphores that have already been initialized (see sema_init).

#include <sema.h>

int sema_test_wait (

   SEMA *s

);

 stand-alone

stack: 0 bytes

If the semaphore pointed to by s has a non-zero count value, sema_test_wait decrements the semaphore count and returns a non-zero value.

If the count in the semaphore is zero and a call to sema_wait would have blocked, sema_test_wait returns 0. This allows a task to check to see if waiting on a semaphore would cause its execution to be suspended.

You must use this function only with semaphores that have already been initialized (see sema_init).

#include <sema.h>

void sema_wait (

   SEMA *s

);

 stand-alone

stack: 0 bytes

If the value of the semaphore pointed to by s is not zero, its value is reduced by 1. If the value of the semaphore is 0, it is left unchanged and the current thread is paused and added to the list of threads waiting for the semaphore. It can be resumed only by some future call on sema_signal by a different thread.

You must use this function only with semaphores that have already been initialized (see sema_init).

#include <sema.h>

void sema_wait_n (

   SEMA *s,

   int   n

);

 stand-alone

stack: 32 bytes

This function calls the function sema_wait n times, in sequence. The calling thread may be forced to wait at any point in the sequence. The parameter n must be greater than or equal to zero.

You must use this function only with semaphores that have already been initialized (see sema_init).

#include <stdio.h>

void setbuf (

   FILE *stream,

   char *buf

);

server

setbuf is used after a stream has been opened but before it is read or written. It causes the character array buf to be used instead of an automatically allocated buffer. If buf is the constant pointer NULL, I/O is performed without any buffering being interposed by the stdio package. A macro BUFSIZ tells how big an array is needed:

char buf[BUFSIZ];

A buffer is normally obtained from malloc upon the first getc or putc on the file, except that output to the standard error stream stderr is normally not buffered.

void SetClear (

   volatile unsigned int *w,

   unsigned int           Set,

   unsigned int           Clear

);

 stand-alone

stack: 0 bytes

This function may be used to change bits in a word without allowing an interrupt to occur during the modification. It may be thought of as equivalent to the pseudo code:

unsigned int temp;

PreviousState = CurrentInterruptState;

CurrentInterruptState = DISABLED;

   temp = *w;

   temp |=  Set;

   temp &= ~Clear;

   *w = temp;

CurrentInterruptState = PreviousState;

It is common for systems to control peripheral devices through memory-mapped registers. SetClear is useful for changing the state of such registers without fear of an interrupt invalidating the change.

#include <setjmp.h>

int setjmp (

   jmp_buf env

);

 stand-alone

This function, together with longjmp, is useful for dealing with errors encountered in a low-level subroutine of the program.

longjmp restores the stack environment saved in its env argument by an earlier call on setjmp. This has the effect of resuming execution immediately after that setjmp call. setjmp's caller can distinguish between the original return from setjmp and the second return caused by longjmp by examining setjmp's return value. This is always 0 for the initial return, and the value of longjmp's val argument for subsequent returns. If val is set to 0, longjmp changes it to 1 to preserve this condition.

The function that originally called setjmp must not itself have returned before the call to longjmp. All accessible data still have their values as of the time longjmp was called.

#include <locale.h>

char *setlocale (

   int         category,

   const char *locale

);

 stand-alone

setlocale allows you to change or query all or part of the current locale. The part of the locale to affect is specified in category; the following macros are provided to do this: LC_ALL, LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC and LC_TIME.

If a locale is specified, the locale for the specified category is changed to that locale, and the new locale is returned. If NULL is specified for locale, the current value of the locale for that category is returned. If the request cannot be honoured, NULL is returned.

In the current version of Diamond, the only recognized locales are "C" and ""; these have the same characteristics, as defined in section 4.4 of the ANSI standard.

#include <stdio.h>}

int setvbuf (

   FILE  *stream,

   char  *buf,

   int    mode,

   size_t size

);

server

After the specified stream has been opened, and before any other I/O has been performed on it, the function setvbuf may be used to change its buffering method to use the specified mode. The mode argument determines how the stream should be buffered, and you should use one of the following macros, which are defined in stdio.h :

If the argument buf is not NULL, the stream may use the buffer it points to instead of one allocated internally by the run-time library. The argument size specifies the size of this buffer.

The function returns zero to indicate success, or a non-zero value if the mode argument is invalid or if the function call cannot be honoured.

#include <signal.h>

void (*signal(int sig, void (*func)(int)))(int);

 stand-alone

signal defines how a specified signal will be handled from now on. The allowed values for sig are listed in the discussion of raise.

For the second argument, func, you may specify the macros SIG_DFL or SIG_IGN, both of which result in the specified signal being ignored. Alternatively, you can specify the name of a function, called a signal handler, that is to be called when the signal is raised. During the execution of the signal handler, that signal is ignored. Execution of the signal handler may be ended by calling longjmp, exit or abort; or by executing a return, which resumes execution from the point where the signal was raised.

If there is an error in the call of signal, it returns the value of the macro SIG_ERR, and set errno to EINVAL. Otherwise it returns the value of the func argument.

In the present version of Diamond, signals may only be raised by calling the raise function. They do not happen spontaneously.

#include <math.h>

double sin (

   double x

);

 stand-alone

sin returns the sine of its radian argument.

For very large magnitudes of x (|x| greater than about 12000), the function returns 0 and sets errno to ERANGE.

Common error: If you forget to include math.h, the compiler automatically declares a function returning int and will give unpredictable results.

#include <math.h>

double sinh (

   double x

);

 stand-alone

sinh returns the hyperbolic sine of its argument.

If the magnitude of x is too large, HUGE_VAL is returned, and errno is set to the value of ERANGE.

Common error: If you forget to include math.h, the compiler automatically declares a function returning int and will give unpredictable results.

 stand-alone

An operator that returns the number of bytes that are associated with an object of the given type. You can specify the type explicitly, as in sizeof(struct foo) or sizeof(int), or implicitly by giving an instance of that type, as in:

struct foo MyStruct;

int MyInt;

size_t TheSize;

TheSize = sizeof(MyStruct);

TheSize = sizeof(MyInt);

As sizeof is an operator, the brackets are optional.

#include <stddef.h>

 stand-alone

the type of the result of sizeof and offsetof.

#include <stdio.h>

int snprintf (

   char       *pstr,

   size_t      size,

   const char *format,

   ...

);

 stand-alone

stack: 1400 bytes

snprintf writes formatted output into a character array via a pointer pstr supplied by the caller.  The number of characters written will not exceed the value of the size argument; extra characters are discarded.

The meaning of the format string and the use of the other arguments is as for fprintf. A NUL character automatically terminates the output string written to pstr unless size is zero, in which case nothing is written and pstr may be NULL.

Note that this terminator is not included in the character count returned by snprintf.

The function normally returns the number of characters (octets) actually written into the array, but if size is zero, it returns the number of characters that an equivalent call to fprintf would have output.

#include <stdio.h>

int sprintf (

   char       *pstr,

   const char *format,

   ...

);

 stand-alone

stack: 368 bytes

sprintf writes formatted output into a character array via a pointer pstr supplied by the caller. It returns the number of characters (octets) written into the array. The meaning of the format string and the use of the other arguments is as for fprintf.

A NUL character automatically terminates the output string written to pstr. Note that this terminator is not included in the character count returned by sprintf.

#include <math.h>

double sqrt (

   double x

);

 stand-alone

sqrt returns the square root of x.

sqrt returns HUGE_VAL when x is negative; errno is set to EDOM.

Common error: If you forget to include math.h, the compiler automatically declares a function returning int and will give unpredictable results.

#include <stdlib.h>

void srand (

   unsigned int seed

);

 stand-alone

The srand function uses its argument as a seed for a new sequence of pseudo-random numbers to be returned by subsequent calls to rand.

#include <stdio.h>

int sscanf (

   char       *pstr,

   const char *format,

   ...

);

 stand-alone

sscanf reads input from the string pstr. It interprets the characters it reads according to the given format string and stores the resulting values in the locations pointed to by the pointer arguments following format.

The exact meaning of the arguments to sscanf is the same as for fscanf.

If the end of the string is found before any conversion is done, sscanf returns EOF. Otherwise, it returns the number of input items successfully converted and stored.

#include <sema.h>

SEMA static_sema_init (

   SEMA S,

   int  Value

);

 stand-alone

static_sema_init is a macro that constructs a value that can be used to initialize a semaphore, most often when a static SEMA variable is being declared.

It corresponds to the dynamic initialisation:  sema_init(&S, Value);

For example:

static SEMA GlobalSema = static_sema_init(GlobalSema, 3);

#include <stdlib.h>

int system (

   const char *string

);

server

string is passed to the host command-line interpreter and executed as if it had been entered as a command. The string argument to the system function should be a valid host command line.

system returns 0 if the server accepts the command; otherwise it returns a non-zero value. Any host return code generated by the command is not passed back to the calling program.

system("dir \\mydir\\*.c");

Note that it is not normally possible to use a host command that involves the use of the system running the Diamond application. Attempting to do this normally results in the program calling system being overwritten by the requested program: when the requested command terminates, the server associated with the original program is no longer able to communicate with it and will probably appear to 'hang'.