Home

Ultra C Library Reference

1. become argv of child process main u intl6 prior 0 Priority of Child process 0 is same as parent f u intl16 paths 3 number of paths to inherit stdin stdout stderr u int32 edata 0 No Extra Data Space Ej process_id child_id child id number f char orphan 0 make this child a normal xj child not an orphan u_int16 type_lang type language of child a type lang mktypelang MT PROGRAM ML OBJECT argblk 0 dir Child process is dir argblk 1 e With a e option argblk 2 a And a a option argblk 3 0 Make sure end of options is a null ptr Ultra C Library Reference WX MIC ROWARE if errno _os_exec _os_fork prior paths argblk 0 argblk environ edata amp child id type lang orphan SUCCESS os exit errmsg errno Problem Creating Child s n argblk 0 If we get this far the os exec os wait 0 was successful Wait for child process to die die printf The Child s ID number was d n child id Ultra C2 Library Reference os9exec OS 9 for 68K System Call Processing Syntax int os9exec int func char modname char EAL OM char envp unsigned stacksize short priority short pathcnt Description os9exec is a high level fork chain interface that prepares the parameter and environment list bef
2. Register Processor s name Type 403 505 601 603 User Writable bar SPR s bear DCR besr DCR d br0 DCR bri DCR br2 DCR lona DCR br4 DCR br5 DCR br6 DCR bag DCR cmpa SPR cmpb SPR cmpc SPR 7 cmpd SPR 902 WX MICROWARE Table 2 12 get lt name gt Valid Names and Associated Processors continued Register Processor s name Type 403 505 601 603 User Writable cmpe SPR e cmpf SPR cmpg SPR cmph SPR id counta SPR e countb SPR Cr PREG Cer SPR dabr SPR dacl SPR e dac2 SPR dar SPR dbatOl SPR dbat0u SPR dbat1l SPR dbatlu SPR DOA Ultra C lihrary Referance EAE Ultra UG Library neterence Table 2 12 get lt name gt Valid Names and Associated Processors continued Register Processor s name Type 403 505 601 603 User Writable dbat21 SPR dbat2u SPR dbat31 SPR dbat3u SPR x dbcr SPR dbsr SPR dccr SPR dcmp SPR dear SPR dec SPR x G der SPR x dmaccO DCR dmacr0 DCR dmacrl DCR i dmacr2 DCR dmacr3 DCR d Ultra C Library Reference WX MICROWARE Table 2 12 get lt name gt Valid Names and Associated Processors continued Register Processor s name Type 403 505 601 603 User Writable dmact0 DCR s dmact1 DCR dmact2 DCR dmact3 DCR e dmada0 DCR dmadal DCR
3. alm set Set Alarm after Specified Time Interval Syntax include lt alarm h gt int alm set int sigcode int time Description alm set requests that a signal be sent to the requesting process after the specified time has elapsed For example if the request is made at time x and t ime is t the signal is sent at time X t unless the alarm request is cancelled sigcode is the signal code to be sent to the requesting process time specifies the time interval If the most significant bit of t ime is set time is assumed to be in 256ths of a second Otherwise t ime is assumed to be in units of system clock ticks refer to CLOCKS PER SEC in the time h header file The minimum t ime allowed is two system clock ticks If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno If errors do not occur a1m set returns the alarm ID For More Information Refer to your operating system technical manual for information about alarms Attributes Operating System OS 9 and OS 9 for 68K WX MICROWARE State User Threads Safe Re entrant Yes Library Sys clib 1l See Also oS alarm set asctime Convert Broken Down Time to String Format Syntax include lt time h gt char asctime struct tm tp Description asctime converts the broken down time structure into the following 26 byte string format including the terminating 0
4. u intl16 priority u intl6 group u intl16 user Description os9 id returns the caller s process ID number group and user ID and current process priority proc idis a pointer to the location where os9 id stores the process ID priority is a pointer to the location where os9 id stores the current process priority group is a pointer to the location where os9 id stores the group ID user is a pointer to the location where os9 id stores the user ID Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os initdata Initialize Static Storage from Module Syntax include lt module h gt finclude lt types h gt error code os initdata mh com mod head void statics Description _os_initdata clears the uninitialized data area copies the module header s initialized data to the specified data area and clears the remote data area if it exists It then adjusts the code and data offsets mod head is a pointer to the module header statics is a pointer to the data area Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l1 os intercept Set Up Signal Intercept Trap Syntax include signal h finclude lt types h gt include lt cglob h gt error_code _os_intercept void func void xdata_ptr Description
5. Indicates a standard ANSI header WX MIC ROWARE Table 1 2 Ultra C Header Files continued File Description regs h sbf h Used to include the proper register header file for the target processor regs h contains prototypes for the following functions change const change static got consti get static inci inl inw irq change irq disable irq enable irq maskget irq restore irq save make gdesc o8 cache OS 9 only OS firuw os irgi os9 irq OS 9 for 68K only os scache os sysid outc cut outw Used for functions using the sequential block file manager SBF sbf h contains prototypes for the following functions Oos ss erase os ss rfm OS ss reten os ss skipend os ss sSkip os ss wfm i Indicates a standard ANSI header Table 1 2 Ultra C Header Files continued File Description scf h semaphore h setjmp h f setsys h settrap h Used for functions using the sequential character file manager SCF sc h contains prototypes for the following functions s S55 dcotf os ss decont o08 55 dopbt os ss dsrtsi s ss enrts os ss fillburff 85 deoftil ss SconQ 55 desrts ss enrtsi Used for functions using binary semaphores semaphore h contains prototypes for the following functions OS sema init os sema p OS sema term os sema v Used for bypassing the normal function call a
6. Description tmpfile creates a temporary binary file that is automatically removed when it is closed or at program termination If the program terminates abnormally temporary files are not removed The file is opened for update with wb mode tmpfile returns a pointer to the stream of the file that it created If the file cannot be created tmpfile returns a null pointer Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also fopen WX MICROWARE tmpnam Generate Unique Valid Filename Syntax include lt stdio h gt char tmpnam char filename Description tmpnam generates a string The string is a valid file name and is not the same as the name of an existing file tmpnam generates a different string each time it is called up to TMP MAx times If it is called more than TMP MAX times it returns a null pointer filename is a pointer to the generated file name If filename is a null pointer tmpnam leaves its result in an internal static object and returns a pointer to that object Subsequent calls to tmpnam modify the same object e f filename is nota null pointer it is assumed to point to an array of atleast L_tmpnam chars tmpnam writes its result in that array and returns the parameter as its value Attributes Operating System OS 9 and OS 9 for 68K State User and System Thre
7. File Description sysglob h termcap h termio h time h t Defines the system global variables sysglob h contains prototypes for the following functions _getsys _os_config os getsys os setsys _setsys Used for the terminal capability functions termcap h contains prototypes for the following functions tgetent tgetflag tgetnum tgetstr tgotoi tputse 0 Contains definition to support ioct1 Used for manipulating time time h contains prototypes for the following functions asctime clock ctime difftime getime gmtime _gregorian _julian localtime mktime _os_getime os9 getime os gregorian _os_julian _os_setime os9 setime setime strftime _sysdate sys_mktime time Indicates a standard ANSI header WX MIC ROWARE Table 1 2 Ultra C Header Files continued File Description times h Contains definitions to support times times types h Defines t ypedefs for consistently sized and signed types un h Contains the sockaddr_un structure definition virtual h Contains prototype for the following functions os transadd Indicates a standard ANSI header The C Library This section includes a listing of the available C functions grouped according to functionality Each listing includes the function s name description and the header file in which it is defined Communicating with Environment Functions Th
8. If a user routine is not provided and one of these exceptions occur the program is aborted You can disable an error exception handler by calling os9 strap with an initialization table that specifies zero as the offset to the routine s to remove HM Note Beware of exceptions in exception handling routines They are usually not re entrant Attributes Operating System OS 9 for 68K State User Threads Safe Re entrant Yes Library os lib l See Also FSSTrap OS 9 for 68K Technical Manual os suspend Suspend Process Syntax finclude lt process h gt finclude lt types h gt error code os suspend process id proc id Description os suspend temporarily suspends a process A super user group ID zero may suspend any process A non super user gets an E PERMIT message returned proc id identifies the target process Note os suspend is currently not supported on OS 9 for 68K Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os sysdbg Call System Debugger Syntax finclude lt process h gt finclude lt types h gt error code os sysdbg void paraml void param2 Description _os_sysdbg calls the system level debugger if one exists parami1 and param2 are parameters passed to the debugger These are currently not used When the system level debug
9. Syntax include lt events h gt finclude lt types h gt error code _os_ev_anyclr event_id ev_id int32 value signal code signal u int32 mask Description os ev anycir waits for an event to occur It waits until an OS ev signal occurs that clears any of the bits corresponding to the set bits in the mask ev id identifies the event value is a pointer to the location where os ev anycir stores the actual event value signal is a pointer to the location where os ev anyclr stores the signal code If the process receives a signal while in the event queue it is activated even though the event has not actually occurred mask specifies the activation mask Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l See Also F EVENT OS 9 Technical Manual F EVENT EV ANYCLR OS 9 Technical Manual F EVENT EV SIGNL OS 9 Technical Manual os ev anyset Wait for Event to Occur Syntax include lt events h gt finclude lt types h gt error_code _os_ev_anyset event_id ev_id int32 value signal code signal u int32 mask Description os ev anyset Waits for an event to occur That is it waits until an OS ev signal occurs that sets any of the bits corresponding to the set bits in the mask ev id identifies the event value is a pointer to the location where os ev anyset stores the actual event value
10. buffer is a pointer to space with at least count bytes of memory from which write obtains the data to write to the path It is guaranteed that at most count bytes are written If fewer bytes are written an error has occurred write essentially performs a raw write that is the write is performed without translating characters The characters are passed to the file or device as transmitted by the program write returns the number of bytes actually written If an error occurred 1 is returned and the appropriate error code is placed in the global variable errno Note write performs a raw write to the terminal no linefeeds after returns are transmitted WX MICROWARE Note The thread enabled version of this function contains a cancel point For more information see Using OS 9 Threads Attributes Operating System State Threads Re entrant Library Sys clib 1l1 See Also creat create dup open os write writeln ISWrite J WRITE OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual writeln Write Bytes to Path Syntax include modes h int writeln int path char buffer unsigned count Description writeln writes bytes to a path path is the path number The path number is an integer which specifies one of the standard path numbers 0 1 or 2 or a path number returned
11. Note All information is contained in a static area which is overwritten by subsequent calls to these functions so it must be copied if it is to be saved Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix l 326 See Also endpwent getpwent getpw getpwuid getpwnam setpwent WX MICROWARE Ultra C Library Reference getpwnam Get Password File Name Syntax include lt UNIX pwd h gt struct passwd getpwnam char nam Description getpwnam returns a pointer to an object with the structure shown in getpwent containing the fields of a line in the password file that matches the name nam Each line in the file contains a passwd structure declared in the lt UNIX pwd h gt header file Note The above routines use the standard I O library which increases the size of programs not otherwise using standard I O more than might be expected Note All information is contained in a static area which is overwritten by subsequent calls to these functions so it must be copied if it is to be saved Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No 328 Library unix l See Also endpwent fgetpwent getpw getpwent getpwuid setpwent WX MICROWARE Ultra C Library Reference getpwuid Get Password File User ID
12. Syntax include lt UNIX pwd h gt struct passwd getpwuid unsigned int uid Description getpwuid returns a pointer to an object with the structure shown in getpwent containing the fields of a line in the password file that matches the specified user identification uid Each line in the file contains a passwd structure declared in the UNIX pwd h header file Note The above routines use the standard I O library which increases the size of programs not otherwise using standard I O more than might be expected Note All information is contained in a static area which is overwritten by subsequent calls to these functions so it must be copied if it is to be saved Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No 330 Library unix l See Also endpwent fgetpwent getpw getpwent getpwnam setpwent WX MICROWARE Ultra C Library Reference gets Get String from File Syntax include lt stdio h gt char gets char str Description gets reads characters from the standard input file into an array until end of file is encountered or a newline character is read Any newline character is discarded and a null character is written immediately after the last character read into the array str is a pointer to the array gets returns str if successful If end of file is encountered and no chara
13. The following are important files used during the compilation process These files are located in the mMwos structure under LIB for the hardware platform Libraries provided with Ultra C are listed in Table 1 1 Table 1 1 Libraries Provided with this Release Library Contains calls NE The ANSI standard library cstart r Start up code for compiled programs acstart r acstarta r ansi cstart r ansi cstarta r cstarta r sacstart r ScStart r Scstarta r Sysansi cstart r Sysansi cstarta r syscstart r with the bc option K amp R compatible source mode By default same as cstart x but compiled with ANSI defined icode linked version of the above Same as acstart r mainly for the 8 3 filenames on DOS Same as acstarta r With bc j option icode linked version backward compatibility K amp R mode ANSI version of syscstart r Used to make system state processes Version of scstart r used when j option used Same as sacstart r Same as sacstrta r Same as scstart r 8 3 format Table 1 1 Libraries Provided with this Release Library Contains syscstarta r same as scstarta r 8 3 format cpu l CPU dependent functions mq l POSIX messaging functions os lib l The system call functions Sys clib l The non ANSI C library functions termlib l The termcap database screen manipulation functions sclib l To minimize code size smaller versions of some library functions are availab
14. Ultra C Library Reference Attributes Operating System State Threads Re entrant Standards Library clib l See Also lsprirn ispunc isupper l8xd1gx OS 9 and OS 9 for 68K User and System Safe Yes ANSI WX MICROWARE _isascii isascii See If Parameter Is ASCII Syntax include lt ctype h gt int _isascii int c int isascii int c Description _isascii returns a non zero value if c is an ASCII character the value is in the range 0x00 through 0x7 Otherwise it returns zero Only isascii is available in strictly conforming ANSI mode Otherwise both are available isascii andisascii are macro definitions c is the character to test Note This routine available as a function or a macro in ct ype h does not operate well with values outside the range of an unsigned char The function checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b isascii c Ultra C Library Reference Attributes Operating System OS 9 and OS 9 for 68K State User and System
15. clearerr Clear Error Condition Syntax include lt stdio h gt void clearerr FILE stream Description clearerr clears the end of file and error indicators for a stream if compiled in strictly conforming ANSI mode Otherwise only the error indicator is cleared stream is a pointer to the stream to clear Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library ona open See Also _cleareof cleareof feof ferror fopen getc getchar clock Get Processor Time Syntax include lt time h gt clock t clock void Description clock returns a value in tick units approximating the processor time used by the current process The returned value may be divided by CLOCKS_PER_SEC to determine the processor time in seconds CLOCKS_PER_SEC is defined in the time h header file to be the number of ticks per second The era for clock is the elapsed ticks for this process since the program was forked If clock cannot determine the processor time it returns clock t 1 to indicate an error Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib l1 See Also F SetSys and F Time OS 9 for 68K Technical Manual F SETSYS and F TIME OS 9 Technical Manual WX MICROWARE close Close Path Syntax i
16. excpt stack is a pointer to the stack to use if an exception occurs If excpt_stack is zero os strap uses the current stack init tbl is a pointer to the service request initialization table If a user routine is not provided and one of these exceptions occurs the program is aborted An initialization table for a 68K platform might appear as follows strap errtab T BUSERR errtrap T ADDERR errtrap 1 NULL Note The previous example is for the 68K platform only The T_BUSERR and T_ADDERR are defined only for that platform not for the PPC or X86 platforms When a user s exception routine is executed it is passed the following WX MICROWARE void errtrap vector errno badpc badaddr u int32 vector errno error number of the vector badpc PC where exception occurred badaddr address where exception occurred You can disable an error exception handler by calling os strap with an initialization table that specifies zero as the offset to the routine s to remove Note On OS 9 for 68K the binding for this call performs conversions which allow compatibility with OS 9 If speed is a consideration see os9 strap Note Beware of exceptions in exception handling routines They are usually not re entrant Attributes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant Yes Library os lib l See Also F STrap OS 9 for 6
17. ss dcon Send Data Carrier Present Signal to Process Syntax include lt scf h gt int ss dcon int path int sigcode Description _ss_dcon sends a signal to the calling process when the data carrier detect line associated with the device is present path is the path number of the device sigcode is the signal code to send Only the lower 16 bits of sigcode are used on OS 9 for 68K If ss dcon cannot register the signal 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also o8 ss dconi ISSetStt OS 9 for 68K Technical Manual I SETSTAT SS DCON OS 9 Technical Manual Ss dsrts Disable RTS Line Syntax include scf h int ss dsrts int path Description _ss_dsrts disables the RTS line for an open device path is the path number of the device If ss dsrts cannot disable the RTS line 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System State Threads Re entrant Library Sys clib l See Also oS ss dsrts I SetsStt I_SETSTAT SS_DSRTS OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE ss enrts Enable RTS Line Syntax include scf h
18. 08 alocproci 08 aproot o059 aproci ds shadis Load and execute new module Determine process ID number Get process descriptor copy Get process table entry Send signal to process Allocate fixed length block of memory Allocate process descriptor Insert process in active process queue Enter process in active process queue Execute new primary module process h process n process n process n signal h process n process n process n process n process n Table 1 19 Process Manipulation Functions continued ANSI Function Standard Description Header File _os_dfork Fork process under dexec h control of debugger _os9_dfork Fork process under dexec h control of debugger _os_dforkm Fork process under dexec h os exec _os_findpd os fotki 0s fFarkm i os get prtbl os getstat os getsys os gprdsec _os9_gspump os id control of debugger Start child process Find process descriptor Create new process Create new process by module pointer Get copy of process descriptor block table Get file device status Examine system global variable Get process descriptor copy Return data for specified process memory map Get process ID user ID process h process h process h process h process h Sg codes h sysglob h process h process h process h Table 1 19 Process Manipulatio
19. FSPanic OS 9 for 68K Technical Manual WX MICROWARE os permit Allow Access to Memory Block Syntax finclude lt process h gt finclude lt types h gt include lt modes h gt error_code _os_permit void mem_ptr u_int32 size u_int32 perm process_id pid Description os_permit allows a process to access a block of memory The _os_permit service routine must update SSM System Security Module data structures to show that a process may access the specified memory in the requested mode Note Only super group users may use the _os_permit function mem_ptr is a pointer to the beginning of the memory area to grant access permissions size is the size of the memory area permis the permissions to grant Only the lower 16 bits of perm are used pidis the process identifier of the target process not used for OS 9 for 68K Note os permit only performs a useful function on MMU SSM systems On non MMU SSM systems os permit simply returns without allowing access to the memory block Attributes Operating System State Threads Re entrant Library os lib l See Also FSPermit F PERMIT OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE os perr Print Error Message Syntax include lt errno h gt finclude lt types h gt error_code _os_perr path_id path u_int32 e
20. Product Discrepancy Report To Microware Customer Support FAX 515 224 1352 From Company Phone Fax Email Product Name Description of Problem Host Platform Target Platform
21. Seeking to a location beyond end of file for a file open for writing and then writing to it creates a hole in the file The hole contains data with no particular value usually garbage remaining on the disk The returned value is the resulting position in the file If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno HM Note On OS 9 the file pointer is a full unsigned 32 bits Do not use 1seek on a buffered file because the buffering routines use seek to keep track of the file pointer Attributes Operating System State Threads Re entrant Library Sys clib l See Also fseek os seek ISSeek I_ SEEK OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual WX MIC ROWARE makdir Create Directory Syntax include lt modes h gt int makdir char name int mode int perm int sizel Description makdir creates a directory file name is a pointer to the name of the directory mode specifies the file access mode Only the lower 16 bits of mode are used perm specifies the file attribute permissions Only the lower 16 bits of perm are used If the FAM SIZE or S_ISIZE bit is set in mode the initial size of the directory is set to size If successful makdir returns zero Otherwise 1 is returned and the appropriate error code is placed in the glo
22. WX MICROWARE getwd Get Working Directory Path Name Syntax include UNIX os9def h char getwd char pathname MAXPATHLEN Description getwd copies the absolute pathname of the current working directory to pathname and returns a pointer to the result getwd returns NULL and global variable errno if an error occurs Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix l gmtime Convert Calendar Time to Greenwich Mean Time Syntax include lt time h gt struct tm gmtime time_t tp Description gmt ime converts the calendar time contained in a time structure to Coordinated Universal Time UTC gmt ime returns a pointer to that object or a null pointer if UTC is not available tp is a pointer to the time structure Note gmt ime returns a pointer to a static area which may be overwritten To ensure data integrity use the structure or save it immediately Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also mkt ime for more information on the time structure tp time WX MICROWARE _gregorian Convert Date Time to Gregorian Value Syntax include lt time h gt int _gregorian int time int date Description _gregorian converts the time and date from Julian format to the Gregor
23. _os_chainm os dfork and os dforkm func passes information to a new process as binary data specified by a pointer and size It is up to the forked process to interpret the data priority is the priority at which the new process is to run If priority is zero the new process receives the priority of the calling process pathcnt is the number of open paths to pass to the new process Normally pathcnt is 3 causing the 3 standard paths to be passed A pathcnt of zero passes no open paths AA MICROWARE modname is a pointer to a string naming the new primary module or to a module in the case of the functions ending in m os forkm os chainm and os dforkm argv Is a pointer to the parameter pointer list that the new process receives By convention argv 0 is the name of the new module A null pointer marks the end of the argv list envp is a pointer to the environment pointer list that the new process receives It points to environment variables A null pointer marks the end of the envp list datasize specifies the additional memory in bytes to allocate to the new process stack memory If datasize is zero the default stack size required by the process is used The first 7 parameters are identical for os fork os forkm os chain os chainm os dfork and os dforkm The remaining four parameters have different meanings depending on the function specified by unc Table 2 20 os9kexec Addition
24. erc ptr count amp accum this point the entire module less the four crc bytes has been processed crc NULL 0 amp accum this is a special case to run a null byte through the crc calculation accum accum complement the accumulator Previous calls have left the most significant byte as Oxff Functions Complementing changes this byte to zero fwrite amp accum 1 sizeof accum fp finally write out the four crc bytes Ultra C Library Reference 183 WX MICROWARE creat Create File Syntax include lt modes h gt int creat char name int mode Description creat returns a path number to a newly created file The file is available for writing name is a pointer to the newly created file If name is the name of an existing file the file is truncated to zero length and the ownership and permissions remain unchanged mode specifies the access modes for the file The modes h header file contains the valid mode values Only the lower 16 bits of mode are used If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Note You do not need to specify write access in mode to write to the file You cannot create directories with this call instead use 268 maker ri ly Note The thread enabled version of this function contains a cancel point For more
25. fopen tpurtet getc getchar 884 Ultra C Library Reference putenv Change or Add Value to Environment Syntax finclude UNIX os9def h int putenv char string Description putenv sets the value of an environment variable st ring is in the form name value where name is the name of the environment variable to set and value is the new value for the environment variable If the variable named exists its value is changed to value If the variable name does not exist a new environment list entry is created and set to the value passed putenv makes a copy of string so subsequent modifications to string do not affect the environment putenv returns non zero if it was unable to obtain enough space using malloc for an expanded environment otherwise zero Note putenv manipulates the environment pointed to by environ and can be used in conjunction with get env However envp the third argument to main is not changed This routine uses malloc to enlarge the environment Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l WX MICROWARE puts Output String to File Syntax include lt stdio h gt int puts const char strptr Description puts writes strptr to the stream pointed to by stdout and adds a newline character to the output The terminating null character is not written strptr is a po
26. int ss enrts int path Description _ss_enrts enables the RTS line for an open device path is the path number of the device If ss enrts cannot enable the RTS line 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System State Threads Re entrant Library Sys clib l1 See Also OS ss enrts ISSetStt I SETSTAT SS ENRTS OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual _ss_lock Lock Out Record Syntax include lt rbf h gt int _ss_lock int path unsigned locksize Description Ss lock locks out a section of the file open on path from the current file position up to the number of bytes specified by 1ocksize path is the path number of the file locksize specifies the number of bytes in the file to lock If locksize is zero all locks record lock EOF lock and file lock are removed If locksize is Oxffffffff the entire file is locked out regardless of the file pointer s location This is a special type of file lock that remains in effect until released by ss lock path 0 a read or write of zero bytes or the file is closed If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno For More Information Refer to your operating system technical manual for information on RBF record locking Att
27. irq save irq disable Mask Interrupts Syntax finclude lt regs h gt void irq disable void Description irq_disable masks interrupts to the highest interrupt level available on the CPU It is a system state only system call Attributes Operating System OS 9 and OS 9 for 68K State System Threads Safe Re entrant Yes Library cpu l See Also irq change irq enable irq maskget irq restore irq save WX MICROWARE irq enable Unmask Interrupts Syntax include lt regs h gt void irq_enable void Description irq enable unmasks all interrupts to the lowest interrupt level available on the CPU Attributes Operating System OS 9 and OS 9 for 68K State System Threads Safe Re entrant Yes Library cpu l See Also irq change irq disable irq maskget irq restore irq save irq maskget Mask Interrupts Return Previous Level Syntax finclude lt regs h gt status code irq maskget void Description irq maskget masks all interrupts to the highest level available on the CPU irq maskget returns the interrupt level before masking Attributes Operating System OS 9 and OS 9 for 68K State System Threads Safe Re entrant Yes Library cpu l See Also irq change irq disable irq enable irq restore irq save WX MICROWARE irq restore Restore Interrupt Level Syntax finclude lt regs h gt
28. strtok Break String into Tokens Syntax include lt string h gt char strtok char Src const char delims Description strtok breaks src into a series of tokens when a sequence of calls is made to strtok Acharacter from delims separates each token When the first call is made src is the first parameter A null pointer is the first parameter for subsequent calls src is a pointer to the string to break into tokens delims is a pointer to a string containing characters to separate each token delims may be different from call to call The first call in the sequence searches src for the first character that is not contained in the current delims If no such character is found then there are no tokens in src and st rtok returns a null pointer If a character is found it starts the first token strtok searches from that location for a character that is contained in the current delims If the character is not found the current token extends to the end of src and subsequent searches for a token return a null pointer If the character is found it is overwritten by a null character to terminate the current token The search for the next token starts with the next character st rtok saves a pointer to this location Each subsequent call behaves in the same manner strtok returns a pointer to the first character of a token or a null pointer if there is no token WX MICROWARE Attributes Opera
29. unix l See Also endpwent getpw getpwent getpwnam getpwuid setpwent 0 0 WX MICROWARE fgets Get String from File Syntax include lt stdio h gt char fgets char ptr int cnt FILE stream Description fgets reads at most one less than the specified number of characters from the stream into an array No additional characters are read after a newline character which is returned or after end of file A null character is added to the end of the string ptr is a pointer to the array into which to read the characters cnt is the number of characters to read stream is a pointer to the C I O FILE structure fgets returns ptr if successful If the end of file is encountered and no characters have been read into the array the contents of the array remain unchanged and a null pointer is returned If a read error occurs during the operation the array contents are indeterminate and a null pointer is returned Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library CLA bal See Also fgetc fileno fileno Determine Path Number from File Syntax include lt stdio h gt int _fileno FILE stream int fileno FILE stream Description _fileno returns the path number associated with the specified file pointer The path number is not valid unless stream flag amp NIT is non zero
30. 1 is returned and the appropriate error code is placed in the global variable errno Note srqcmem is identical to_srqmem with the exception of the additional color parameter Attributes Operating System State Threads Re entrant Library Sys clib l See Also free malloc os srqmem os9 srqmem os srtmem F SRqCMem F SROMEM OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE _srqmem System Memory Request Syntax include lt memory h gt char srqmem unsigned size Description _srqmem and the complementary function srtmem are provided to request and return system memory when tight control over memory allocation is required srqmem isa direct hook into the F SRqMem for OS 9 for 68K or F SROMEM for OS 9 system call size specifies the number of bytes to request The specified size is rounded to a system defined block size A size of Ox ffffff obtains the largest contiguous block of free memory in the system The global unsigned variable _srqsiz may be examined to determine the actual size of the allocated block If successful a pointer to the memory granted is returned If the request was not granted 1 is returned and the appropriate error code is placed in the global variable errno The returned pointer always begins on an even byte boundary Care should be taken to preserve t
31. Break serial connection Sg codes h Sg codes h rbf h Sg codes h Sg codes h Sg codes h Sg codes h Sg codes h funcs h sysglob h Sg codes h Sg codes h Sg codes h Sg codes h AN MICROWARE Table 1 7 GetStat SetStat Functions continued ANSI Function Standard Description Header File OS SS cache Enable disable RBF rbf h caching 0S9 ss close Notify driver that path modes h has been closed cs ss dcoft Send signal when data scf h carrier detect line goes false os ss dcon Send signal when data scf h os ss dopt os Ss dsrtsi i OS ss enrts OS ss erase os ss fal os ss fillbuftf os sS flushmap os ss hdlink os ss lockt carrier detect line goes true Set device path options Disable RTS line Enable RTS line Erase tape Write file descriptor sector Fill path buffer with data Flush cached bit map information for RBF device Make hard link to existing file Lock out record Sg codes h scf h scf h sbf h rbf h scf h rbf h rbf h rbf h Table 1 7 GetStat SetStat Functions continued Function ANSI Standard Description Header File os ss luopt os9 ss open os ss popt i OS ss relea OS ss rename 68 ss teseti OS ss reten os ss rfm OoS ss sendsig os ss size os ss skip _os_ss_skipend ps o8 picksl
32. Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix l See Also regcomp regerror remove Remove File Syntax include lt stdio h gt int remove const char filename Description remove deletes a file Subsequent attempts to open a file using that name fail unless the file is recreated filename is a pointer to the file to delete If the file is open remove returns 1 with errno set to EOS SHARE remove returns zero if the operation succeeds Otherwise it returns a non zero value Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 WX MICROWARE rename Rename File Syntax include lt stdio h gt int rename const char old const char new Description rename renames a file oldis a pointer to the name of an existing file new is a pointer to the new name for the file The file named o1d is no longer accessible by that name If a file named new exists prior to the call to rename itis overwritten rename returns zero if the operation succeeds Otherwise it returns a non zero value and the file name does not change Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 rewind Return File Pointer to Zero
33. SyS clib l For More Information The primary purpose of the sys clib 1 library is to provide a library for compatibility with the Microware K amp R C compiler For additional information refer to Appendix A Prototyping sys clib Functions Ultra C Library Reference 619 WX MICROWARE See Also chainc chain modlink modload modloadp _os_exec osvrorki osStorke i Example The following code fragment is an example call to os9exec The argb1k array contains pointers to the parameters in the order that the new program is to receive them The new process receives a copy of the parameters not the addresses of the parameters This example passes the current environment by naming the global variable environ extern int os9forkc extern char environ char argblk rename x oldname newname 0 main int pid if pid os9exec os9forkc argblk 0 argblk environ 0 0 3 gt 0 wait 0 else printf can t fork s argblk 0 os exit Terminate Calling Process Synta fincl fincl X lude lt process h gt lude lt types h gt error code os exit status code status Description os exit allows a process to terminate itself Its data memory area is dea llocated and its primary module is unlinked All open paths are automatically closed status is the status code returned to the parent process Note Thep
34. Syntax include sg codes h finclude lt types h gt error code os ss luopt path id path u int32 size void luopts Description _os_ss_luopt writes the logical unit options for a path to a buffer path is the path number size specifies the buffer size of the logical unit options area luopts is a pointer to the logical unit options Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE _os9_ss open Notify Driver that Path Has Been Opened Syntax include lt modes h gt finclude lt types h gt error_code _os9_ss_open path_id path Description _os9_ss_open Is an internal call for drivers path specifies the path number Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library os_lib l OS ss popt Write Option Section of Path Descriptor Syntax include sg codes h finclude lt types h gt error code os ss popt path id path u int32 size void user opts Description _os_ss_popt writes the option section of the path descriptor from the options buffer pointed to by user opts path is the path number size specifies the buffer size user opts is a pointer to the options buffer Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also os gs popt I Set
35. Threads Re entrant Library os lib l See Also _os9_setime F ALARM WX MIC ROWARE OS 9 for 68K User Safe Yes OS 9 for 68K Technical Manual os salarm atime Execute System State Subroutine at Specified Time Syntax include lt alarm h gt error code os salarm atime salarm id alrm id u int32 time u int32 flags u int32 func void func pb Description _os_salarm_atime executes the specified subroutine after the specified time interval has elapsed The alarm time is an absolute time not a relative time The time value is considered to be a value in seconds since a date specified in Greenwich Mean Time To determine the specified date reference the applicable manual OS 9 for 68K Technical Manual or OS 9 Technical Manual alrm idis a pointer to the location where os salarm atime stores the alarm ID t ime specifies the time when the alarm expires flags specifies the alarm flags func is a pointer to a function to execute func pb is a pointer to the function s parameter block Attributes Operating System OS 9 State User Threads Safe Re entrant Yes Library os lib l See Also os salarm set F ALARM OS 9 Technical Manual WX MICROWARE _os9_salarm_atjul Execute System State Subroutine at Julian Date Time Syntax finclude lt regs h gt include lt alarm h gt finclude lt types h gt error code _os9_salarm_atjul alarm_id alrm id u
36. arent must perform an os wait Oran os exit before the process descriptor is returned to free memory Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE See Also 08 aproci os close Db5 Fungpat os Fork o089 retpai os srtmem os unlink os wait FSExit OS 9 for 68K Technical Manual F_EXIT OS 9 Technical Manual os findpd Find Process Descriptor Syntax finclude process h finclude lt types h gt error code os findpd process id proc id pr desc proc desc Description _os_findpd converts a process number to the absolute address of its process descriptor data structure proc id specifies the process ID proc desc is a pointer to the location where os findpd stores the pointer to the process descriptor Attributes Operating System OS 9 and OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l See Also se alocproe Loe TrLnpreci FSFindPD OS 9 for 68K Technical Manual F_FINDPD OS 9 Technical Manual WX MICROWARE os9 findpd Find Fixed Block of Memory Syntax finclude lt process h gt finclude lt types h gt error code os9 findpd u int32 number void address void table Description _os9_findpd converts a table index to the absolute address of its data structure number i
37. sig is executed func may terminate by executing a return statement or by calling abort exit or long jmp If func executes a return statement and sig was exception related the program exits with the appropriate vector for a status Otherwise the program resumes execution at the point it was interrupted Asynchronous Signals Signals that occur by means other than abort or raise are called asynchronous Signal handlers dealing with asynchronous signals should be careful about the following Calling any function in the library except signal with the occurring signal that may be working with static storage structures Modifying any static storage structure other than a variable of type volatile sig atomic t If the signal call can be honored it returns unc for the most recent call to signal for the specified signal sig Otherwise SIG ERR is returned and a positive value is stored in errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 See Also abort exit intercept os intercept raise WX MICROWARE sin Sine Function Syntax include lt math h gt double sin double x Description sin returns the sine of x as a double float x is in radians Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards
38. waits for an event to occur The event variable is ANDed with the value in mask If the result is not zero the calling process is suspended in a FIFO event queue until an oS ev signal occurs that clears all of the bits corresponding to the set bits in the mask Then the bits corresponding to the set bits in the mask are set ev id identifies the event value is a pointer to the location where os ev tstset stores the actual event value signal is a pointer to the location where os ev tstset stores the signal code If a process in the event queue receives a signal it is activated even though the event has not actually occurred mask specifies the activation mask Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MIC ROWARE See Also F EVENT OS 9 Technical Manual F EVENT EV TSTSET OS 9 Technical Manual F EVENT EV SIGNL OS 9 Technical Manual os ev unlink Unlink Event Syntax include lt events h gt finclude lt types h gt error code os ev unlink event id ev id Description os ev unlink decrements the use count of an event When the use count reaches zero you can delete the event using OS ev delete ev id identifies the event Attributes Operating System State Threads Re entrant Library os lib l See Also os ev delete os ev link FSEvent F EVENT F EVENT EV UNLNK
39. 101 151 capability ID check 1045 get 1046 1047 tgetflag 1045 tgetnum 1046 tgetstr 1047 capability string output 1060 tputs 1060 cbrt 153 cdi h 15 CDT 84 ceil 60 154 ceiling function 154 CET 84 chain 155 chainc 76 103 155 change current constant data pointer 158 current data directory 160 current execution directory 166 current static storage pointer 159 file access permissions 162 module directory 534 owner of file 164 permissions of module directory 537 system global variable 942 working directory 530 change_static 65 159 CHAR_MAX 425 426 character get from file 245 get from I O address 360 get next from file stdin 303 multibyte 446 448 450 1083 1085 output to file 267 push back 1064 put next to file stdout 883 ABCDEFGHIJKLMNOPQRSTUVWXYZ rindex 907 search for 361 907 standard white space 405 unget 1064 ungetc 1064 write to I O address 864 character classification _isascii 36 380 _isjis_kana 36 387 389 393 _issjis1 37 401 _issjis2 37 403 isalnum 36 376 isalph 378 isalpha 36 isascii 380 iscntrl 36 383 isdigit 36 385 isgraph 36 391 islower 36 395 isprint 36 397 ispunct 36 399 isspace 37 405 isupper 37 407 isxdigit 37 409 list of functions 36 test for alphabetic 36 378 alphanumeric 36 376 ASCII 36 380 control code 36 383 digit 36 385 Hankaku kana 36 387 389 393 hexadecimal 37 409 Kanji 37
40. 1067 from module 494 module 849 850 unlink 51 109 1066 unlinkx 51 109 1067 unload module 495 unmask interrupts 372 signals 777 user accounting 848 user ID os id 675 os setuid 771 os9 id 677 determine 338 get 675 677 set 771 944 setuid 944 user addr 1069 UTC 84 341 va arg 67 1070 va end 68 1071 va start 68 1072 valid file access modes 239 validate module 852 variable parameter list end references to 1071 get parameter 1070 initialize 1072 va_arg 1070 va_end 1071 ABCDEFGHIJKLMNOPQRSTUVWXYZ va start 1072 verify attached device 143 module 851 852 vfprintf 51 1073 VIDEO1 442 464 709 966 VIDEO2 442 464 709 966 vprintf 51 1075 vsprintf 51 1077 wait for child process to terminate 854 for event to occur 221 601 604 606 for process termination 1079 for record release 990 for relative event to occur 223 607 609 for signal 869 specified number of ticks 823 wait 79 109 1079 wcstombs 72 1083 wctomb 72 1085 WET 84 write 864 bytes to path 1087 1089 data 290 859 file descriptor sector 805 fwrite 290 integer to I O address 865 line of text 861 logical unit options 811 option section of path descriptor 813 string to file 268 tape marks 824 track 825 992 word to I O address 866 write iovcnt buffer data 1091 write 51 109 1087 writeln 51 109 1089 writev 1091 ABCDEFGHIJKLMNOPQRSTUVWXYZ YST 84 1194 Ultra C Library Reference
41. 422 limits h 18 link 697 to existing event 208 585 to memory module 467 469 471 697 699 702 load memory module 155 469 471 700 702 module into colored memory 464 locale control 935 locale h 18 localeconv 65 425 localtime 87 429 locate first occurrence of string 1013 1016 last occurrence of string 1014 string 999 lock _os_acqlk 502 Os caglk 525 OS crlk 549 os ddlk 552 Os dellk 557 _os_rellk 729 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z os waitlk 857 acquire 502 activate next 857 conditionally acquire ownership of 525 create 549 deadlock situation 552 delete descriptor 557 get ownership 502 out record 810 979 release ownership 729 lock h 19 log 61 430 log10 61 431 logarithm base ten 431 natural 430 logical file pointer Os seek 753 reposition 753 logical unit os gs luopt 668 os ss luopt 811 read options 668 write options 811 longjmp 65 432 Iseek 107 436 M m tmzone 387 102 macro bypass replacement 8 defined 8 makdir 48 105 438 make directory 704 global descriptor table entry 439 interrupt descriptor table entry 440 make gdesc 89 439 make idesc 89 440 make module 68 105 441 ABCDEFGHIJKLMNOPQRSTUVWXYZ malloc 63 101 444 map error number 871 mask interrupts 371 373 signals 777 matching failures defined 282 math h 19 mathematical functions abs 60 115 acos 60 117 arc cosine 60 117 sine 60 131 tangent 60 134 135 asin 60 1
42. 43 825 Os strap 66 827 os suspend 78 831 os sysdbg 73 832 Os sysid 67 833 _os tlink 71 840 os tlinkm 71 842 os tranpn 843 os uacct 67 848 os unlink 71 849 os unload 71 850 os vmodul 71 851 os wait 78 854 os waitlk 80 857 OS write 50 859 os writeln 50 861 os9 alarm atdate 53 504 os9 alarm atjul 53 507 _osQ allbit 65 514 os9 allpd 76 515 Os9 aproc 76 520 _os9 create 48 547 _os9 delbit 66 554 OS9 dfork 77 567 _os9 ev wait 56 606 _os9 ev waitr 56 609 _os9 findpd 66 624 _os9 getime 88 640 _os9 gs cdfd 40 653 _os9 gs free 41 667 _os9_gspump 77 672 os9 id 78 677 _os9 ioqueue 49 685 os9 irq 59 688 _os9 panic 66 715 ABCDEFGHIJKLMNOPQRSTUVWXYZ _os9 retpd 66 730 _os9_salarm_atdate 56 733 _os9_salarm_atjul 56 736 _os9_salarm_cycle 57 740 _os9 salarm set 57 746 OS9 schbit 66 751 OS9 setime 88 762 OS9 setsvc 66 768 OS9 sleep 78 784 _os9_srqmem 64 792 _os9 ss open 43 812 OS9 strap 67 829 _os9 translate 64 846 os9 vmodul 71 852 _parsepath 67 106 867 prgname 67 107 879 prsnam 67 107 882 REAL 140 Set name 916 _setcrc 71 108 927 _setsys 73 108 942 _srqcsiz 966 _srqmem 64 109 968 _srqsiz 968 _srtmem 64 109 970 Ss _attr 44 109 971 Ss dcoff 44 109 975 Ss dcon 44 109 976 Ss dsrts 44 110 977 Ss enrts 44 107 9
43. 754 os sema p 57 755 Os sema term 57 os sema v 57 757 Os send 758 os send 57 _os_sigmask 58 777 Os sigrs 58 781 ABCDEFGHIJKLMNOPQRSTUVWXYZ os9 alarm atdate 53 504 os9 alarm atjul 53 507 _os9 ev wait 56 606 _os9 ev waitr 56 609 os9 salarm atdate 56 733 os9 salarm atjul 56 736 os9 salarm cycle 57 740 _os9 salarm set 57 746 alarm 118 alm atdate 52 120 alm atjul 52 122 alm cycle 52 124 alm delete 52 126 alm set 52 127 clear process signal queue 54 536 control process signal handling 58 947 create event 52 54 203 579 delete event 52 55 205 581 execute system state subroutine after specified time interval 57 746 at Gregorian date time 56 733 at Julian date time 56 736 at specified time interval 56 every nticks second 57 740 get event information 52 206 initialize semaphore data structure 57 intercept 53 364 link to existing event 53 55 208 585 list of functions 52 mask signals during critical code 58 777 pause 58 869 raise 58 889 read event without waiting 53 55 211 588 release semaphore 57 remove pending alarm request 52 54 57 126 510 742 743 reserve semaphore 57 reset alarm clock 57 744 request 54 511 resize current process signal queue block 58 781 ABCDEFGHIJKLMNOPQRSTUVWXYZ return event information 55 582 send signal after specified time interval 52 54 127 512 at Gregorian date time 52 53 120 504
44. 87 341 Greenwich Mean Time 341 1031 Gregorian gregorian 342 OS gregorian 652 convert to 342 group identification getgid 309 hard link Os ss hdlink 808 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z create 808 header files 14 alarm h 14 assert h 14 aton h 15 cache h 15 cdi h 15 ctype h 15 dirh 16 direct h 16 errno h 16 events h 17 floath 17 funcs h 17 io h 18 ioctl h 18 ioedt h 18 limits h 18 locale h 18 lock h 19 math h 19 memory h 20 moddir h 20 modes h 21 module h 22 543 os9def h 23 os9time h 23 process h 24 procid h 25 rbf h 25 regexp h 25 regs h 26 sbf h 26 scf h 27 semaphore h 27 setjmp h 27 setsys h 27 settrap h 27 sg_codes h 28 sgstat h 28 signal h 29 ABCDEFGHIJKLMNOPQRSTUVWXYZ stdarg h 29 stddef h 29 stdio h 30 stdlib h 31 string h 32 strings h 32 svctbl h 32 sysglob h 33 termcap h 33 termio h 33 time h 33 34 un h 34 hyperbolic cosine 178 sine 959 tangent 1040 hypot 61 106 357 I O address get character from 360 integer from 363 word from 369 inc 360 inl 363 inw 369 outc 864 outl 865 outw 866 write character to 864 integer to 865 wordto 866 I O device _os_getdl 637 attach 521 get system pointer for list 637 I O device functions get from I O address ABCDEFGHIJKLMNOPQRSTUVWXYZ character 45 360 integer 45 363 word 45 369 inc 45 360 inl 45 363 inw 45 369 list of 45 outc 45 864 outl 45 865 outw 45 866 write to I O
45. 973 insert process in active process queue 519 install system state trap handling module 840 user Subroutine library module 788 user subroutine module 786 user trap handling module 842 integer return random 890 write to I O address 865 integerget from I O address 363 intercept trap Os intercept 679 setup 679 intercept 53 107 364 interprocess communication ev creat 52 203 ev delete 52 205 ev info 52 206 ev link 53 208 ev pulse 53 209 ev read 53 211 ev set 53 213 ev setr 53 215 ev signal 53 217 ev unlink 53 219 ev wait 53 221 ev waitr 53 223 ABCDEFGHIJKLMNOPQRSTUVWXYZ os alarm atime 54 506 os alarm cycle 54 509 os alarm delete 54 510 os alarm reset 54 511 os alarm set 54 512 os clrsigs 54 536 os ev allcir 54 573 os ev allset 54 575 os ev anycl 54 576 os ev anyset 54 577 os ev change 54 578 OS ev creat 54 579 os ev delete 55 581 os ev info 55 582 os ev link 55 585 Os ev pulse 55 586 os ev read 55 588 OS ev set 55 589 os ev setand 55 591 OS ev setor 55 593 OS ev setr 55 595 Os ev setxor 55 597 os ev signal 55 599 OS ev tstset 56 601 os ev unlink 56 603 os ev wait 56 604 os ev waitr 56 607 os intercept 56 679 os salarm atime 56 735 os salarm cycle 56 738 os salarm delete 57 742 743 os salarm reset 57 744 os salarm set 57 745 os sema init 57
46. ANSI Library clib 1 sinh Hyperbolic Sine Function Syntax include lt math h gt double sinh double x Description sinh returns the hyperbolic sine of x as a double float x is in radians A range error occurs ERANGE stored in errno if the magnitude of x is too large In this case the appropriately signed HUGE VAL Is returned Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib i Possible Error ERANGE AA MICROWARE sleep Suspend Execution for Specified Time Syntax include signal h int sleep unsigned seconds Description sleep suspends the calling process for the specified time A sleep time of zero seconds sleeps indefinitely sleep returns the number of ticks remaining to sleep if awakened prematurely by a signal seconds specifies the length of time for the process to sleep Note The thread enabled version of this function contains a cancel point For more information see Using OS 9 Threads Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l1 See Also os sleep os9 sleep FSSleep OS 9 for 68K Technical Manual F_SLEEP OS 9 Technical Manual _sliblink Link to Subroutine Module Syntax include lt module h gt mh com sliblink int slib num char slib name D
47. Description OS gs cstats returns a copy of the current cachestats structure path specifies the number of a path open on the device cache inf is a pointer to the location where os gs cstats stores the structure containing information about RBF caching Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os gs devnm Return Device Name Syntax include sg codes h finclude lt types h gt error code os gs devnm path id path char name Description OS gs devnm returns the name of the device associated with the specified path path specifies the path number name is a pointer to the location where os gs devnm stores the device name Some networked devices using NFM may require a buffer size of 128 or 256 bytes for the device name Note On OS 9 the buffer pointed to by name should be at least 64 bytes to accommodate a device name On OS 9 for 68K the buffer pointed to by name is a fixed 32 bytes Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l _os gs devtyp Return Device Type Syntax include sg codes h finclude lt types h gt error code os gs devtyp path id path u intl16 type u intl6 class Description os gs devtyp returns the type and class of the device associated
48. Description difftime returns the difference in seconds between t ime1 and timeO This value is returned as a double If you could subtract the time t values the return value would be timel timeO0 Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library Glrb l See Also time div Compute Quotient and Remainder Syntax include lt stdlib h gt div t div int numer int denom Description div returns the quotient and remainder of the division of the numerator by the denominator numer is the numerator denom is the denominator If the division is inexact the resulting quotient is the integer of lesser magnitude that is the nearest to the algebraic quotient If the result cannot be represented the behavior is undefined Otherwise quot denom rem equals numer div returns a structure of type div t comprising both the quotient and the remainder The div t structure contains the quot and rem fields Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clagb l WX MICROWARE dtoa Double to ASCII Conversion Syntax include lt stdlib h gt int _dtoa double fnum char buft int tot_digs int frac_digs int sign Description _dtoa converts a floating point number of type double to the ASCII string equiv
49. Expand Value to Integral Constant Expression Syntax include lt stddef h gt int offsetof type mbr_desig Description offsetof expands to an integral constant expression The integral constant expression has a type of size t the value of which is the offset in bytes to the structure member from the beginning of the structure type specifies the type of the structure mbr desig specifies the member name of the structure for which you want to compute the offset If the member is a bit field the behavior is undefined Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library elab l WX MICROWARE open Open File Syntax include lt modes h gt int open char name int mode Description open opens an existing file name is a pointer to the name of the file mode specifies the access mode for the file The values for mode are defined in the modes h header file Only the lower 16 bits of mode are used open returns a path number identifying the file when I O is performed If the open fails 1 is returned and the appropriate error code is placed in the global variable errno Note The thread enabled version of this function contains a cancel point For more information see Using OS 9 Threads Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Libr
50. Function Declarations and K amp R Compiler vs Prototypes and ANSI C In the old days when K amp R C ruled the earth the concept of a function protoype did not exist The closest equivalent concept was a function declaration The purpose of the function declaration was to pre define what the return type of a function was so that some degree of type checking could be done on its use An example of a function declaration is struct direct readdir This shows that the function readdir returns a pointer to a structure of the type direct found in dir h NOTE There is nothing in the declaration which mentions what type or even how many arguments the readdir function takes As a result no type checking was ever done on these functions parameters The standard promotion of arguments was always assumed to have occurred The standard promotion rules are quite simple all types being passed in that are narrower than an int type are widened to an int type and all arguments that are of floating point type are widened to a double precision As a natural consequence all functions which are compiled in K amp R mode for instance all the sys_clib 1 functions assume that the calling function has already promoted the function arguments to their widened forms ANSI C prototypes are somewhat different An example of a prototype is int os9fork char int char short short int short This shows that the function os9
51. OS 9 Technical Manual ev delete Delete Event Syntax include lt events h gt int ev delete char ev name Description ev delete deletes an event The use count for the event must be zero before the event can be deleted ev name is a pointer to the name of the event If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno For More Information Refer to your operating system technical manual for more information about events Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also oS ev delete FSEvent OS 9 for 68K Technical Manual F_EVENT EV_DELET OS 9 Technical Manual WX MICROWARE ev info Get Event Information Syntax include lt events h gt int ev info JE ev index int ev infostr int ev buffer Description ev info returns information about an event The event table is indexed from zero to one less than the maximum number of events allowed on the system ev index corresponds to the starting point in the event table to search for an event ev buffer is a pointer to the event structure buffer used to hold the event information if found If ev index is greater than all active events in the table 1 is returned and the appropriate error code is placed in the global variable errno For More Information
52. OoS ev signal FSEvent OS 9 for 68K Technical Manual F_EVENT OS 9 Technical Manual EV_CREAT OS 9 Technical Manual EV_LINK OS 9 Technical Manual EV_SIGNL OS 9 Technical Manual ev unlink Unlink Event Syntax include lt events h gt int ev unlink int ev id Description ev unlink decrements the link count of an event When the link count becomes zero you can delete the event using ev delete or os ev delete ev id specifies the event ID If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno For More Information Refer to your operating system technical manual for more information about events Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l1 See Also ev delete OS delete os ev unlink FSEvent F EVENT EV EV DELET UNLNK WX MICROWARE OS 9 for 68K Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual ev wait Wait for Event Syntax include lt events h gt int _ev_wait int ev_id int ev_min int ev max Description ev wait waits for an event to occur The event value is compared to the range values specified by ev min and ev max If the event value is not in the specified range the process waits until some other process places the value within the range Once in ran
53. Refer to your operating system technical manual for more information about events Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also os ev info FSEvent F_EVENT EV_INFO OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE ev link Link to Existing Event Syntax include lt events h gt int ev link char ev name Description ev link links to an existing event An event ID number is returned if the event is successfully linked ev name is a pointer to the name of the event If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno For More Information Refer to your operating system technical manual for more information about events Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l1 See Also os ev link FSEvent OS 9 for 68K Technical Manual F_EVENT EV_LINK OS 9 Technical Manual ev pulse Signal Event Occurrence Syntax include lt events h gt int ev pulse int ev id int ev value int allflag Description ev pulse indicates that an event has occurred The current event value is saved The event variable is set to the value given by ev value and the normal signal increment is not applied The saved event v
54. Reset existing alarm alarm h request os alarm set Send signal after alarm h specified time interval ps clraeigqgst Clear process signal signal h queue os ev allclr Wait for all bits events h defined by mask to become clear Jos ev allset Wait for event to events h occur _os_ev_anyclr Wait for event to events h occur _os_ev_anyset Wait for event to events h occur _os_ev_change Wait for event to events h occur _os_ev_creat Create new event events h Table 1 10 Interprocess Communication Functions continued Function ANSI Standard Description Header File os ev delete os ev info oS ev link _os_ev_pulse oS ev read OoS ev set oS ev setand oS ev setor oS ev setr OS ev setxor _os_ev_signal Delete existing event Return event information Link to existing event by name Signal event occurrence Read event value without waiting Set event variable and signal event occurrence Set event variable and signal event occurrence Set event variable and signal event occurrence Set relative event variable and signal event occurrence Set event variable and signal event occurrence Signal event occurrence eve eve eve eve eve eve nts h nts h nts h nts h nts h nts h events h events h events h events h events h WX MICROWARE Table 1 10 Interprocess Com
55. The terminating null character is considered part of the string src is a pointer to a string chr is the character to search for in src strrchr returns a pointer to the character or a null pointer if chr does not occur in the string Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 strspn Compute String Length Syntax include lt string h gt char strspn const char Ssrc const char pattern Description strspn returns the length of the maximum initial segment of src which consists entirely of characters from pattern src is a pointer to a string pattern is a pointer to a string Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library lab 1 WX MICROWARE strstr Locate First Occurrence of String Syntax include lt string h gt char strstr const char Src const char pattern Description strstr locates the first occurrence in src of the sequence of characters excluding the terminating null character in pattern src is a pointer to a string pattern is a pointer to a string containing a sequence of characters to search for in src strstr returns a pointer to the located string or a null pointer if the string is not found If pattern is a pointer to a string with zero length strstr re
56. Threads Safe Re entrant Yes Library Sys clib l See Also tmpnam tmpfile WX MICROWARE mktime Convert Broken Down Time to Calendar Time Syntax include lt time h gt time_t mktime struct tm tp Description mkt ime converts the broken down time expressed as local time into a calendar time value with the same encoding as the values returned by t ime The original values of the tm_wday and tm_yday fields of the structure are ignored and the original values of the other fields are not restricted to the indicated ranges tp is a pointer to the broken down time structure On successful completion the tm_wday and tm_yday fields of the structure are set appropriately The other fields are set to represent the specified calendar time but with their values forced to the indicated ranges The final value of tm_mday is not set until tm mon and tm year are determined mktime returns the specified calendar time encoded as a value of type time_t If the calendar time cannot be represented mkt ime returns the value time t 1 Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also asctime getenv gmt ime localtime time Ultra C Library Reference 463 WX MICROWARE modcload Load Module into Colored Memory Syntax include lt memory h gt include lt module h gt
57. UNIX os9def h int execv char path char argv l char envp 1 Description execve is a UNIX like interface to the os chain system call The argument to execve is an argument vector to pass to the chained process and the path to the program to chain to The last argument should be a NULL entry argv 0 is conventionally the name of the program being chained to The argument envp is a pointer to a null terminated array of character pointers to null terminated strings Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l See Also execl execle execvp execvp Calls a File With an Argument Vector Syntax finclude UNIX os9def h int execvp char 1le char argv Description execvp is a UNIX like interface to the os chain system call The argument to execvp is an argument vector to pass to the chained process and the path to the program to chain to The last argument should be a NULL entry argv 0 is conventionally the name of the program being chained to Note os chain does not do the normal PATH searching that the sne11 does Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l See Also execl execle execv WX MICROWARE _exit Task Termination Syntax include lt stdlib h gt
58. cache Bit 1 C DISDATA If set disables the data cache Bit 2 C FLDATA If set flushes the data cache WX MIC ROWARE Table 2 21 control Parameter Bits Defined for os scache Bit Name Description Bit 3 Bit 4 Bit 5 Bit 6 Bit 7 Bit 8 Bits 9 14 Bit 15 Bit 16 Bits 17 31 C_INVDATA C_ENINST C_DISINST C_FLINST C_INVINNST C_GETCCTL C_STODATA If set invalidates the data cache if supported by hardware If set enables the instruction cache If set disables the instruction cache If set flushes the instruction cache If set invalidates the instruction cache If set flags a target address for flush operation Reserved for future use by Microware If set returns a pointer to the cache control routine and cache static global data If set stores the data cache if supported by hardware Reserved for future use by Microware Note All other bits are reserved If any reserved bit is set an EOS PARAM error is returned By OS 9 convention the terms flush invalidate and store are defined as follows Flush Operation by which a cache line is written to main memory and marked as invalid Invalidate Operation by which a cache line is marked as invalid No write of cache line to main memory is performed Store Operation by which a cache line is written to main memory The
59. changes the execution directory only for the program containing the function call not the shell that executes the program Use the built in shell command chx to change the shell s execution directory Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l1 See Also bo amp echditi I ChgDir OS 9 Technical Manual _CHDIR OS 9000 Technical Manual chx Using OS 9 for 68K and Using OS 9 WX MICROWARE cleareof cleareof Clear End of File Condition Syntax include lt stdio h gt void _cleareof FILE stream void cleareof FILE stream Description cleareof is a macro that resets the end of file condition that causes feof to return a non zero value stream is a pointer to the stream You can use this to retry an input operation on a terminal after end of file is encountered getc does not read characters until the end of file condition is cleared Note If you are executing the compiler in strictly conforming ANSI mode only _cleareof is available Otherwise both calls are available Note These calls are implemented as macros in the stdio h header file Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Functions Library Sys clib l See Also feof getc getchar Ultra C Library Reference 169 WX MICROWARE
60. include lt ctype h gt int _issjis2 int c Description issjis2 isa C macro that returns a non zero value if c is the second byte of a Shift JIS Japanese Industrial Standard Kanji character Otherwise it returns zero The valid range for Shift JIS second bytes are between 0x40 and Oxfc c is the character to test c cannot equal 0x7 f Note This routine available as a function or a macro in ctype h does not operate well with values outside the range of an unsigned char The function checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b issjis2 c Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Reference 403 WX MICROWARE Library ctype h See Also isalnum isalpha TSCHLETI isdigit isgraph islower Sprit ispunct _issjis1 isspace isupper lgxdieniti 404 Ultra C Library Reference isspace See If Parameter Is White Space Syntax include lt ctype h gt int isspace in
61. include lt stdio h gt int vfprintf FILE stream const char format va list arg Description vfprintf performs formatted output to a stream It converts formats and prints any parameters as indicated by the control string vfprintf is similar to printf However arg replaces the variable parameter list stream is a pointer the C I O FILE structure format is a pointer to a control string arg is initialized by va start and possibly subsequent va arg calls vfprintf does not call va end vfprintf returns the number of characters transmitted If an output error occurs a negative value is returned For More Information The sclib 1 and sclib il libraries contain a smaller version of the vfprintf function Refer to the Using Ultra C C manual for more information about the small library functions WX MICROWARE Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib l Example The following shows the use of v printf in a general error reporting routine include lt stdarg h gt include lt stdio h gt void error char function_name char format va_list args va_start args format print out name of function causing error fprintf stderr ERROR in s function name print out remainder of message Ef vfprintf stderr format args va end
62. is useful for preventing a deadlock situation when protecting multiple resources from simultaneous accesses The deadlock list usually represents the list of processes waiting to acquire access to an associated resource Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library lock 1 See Also F ACQLK OS 9 Technical Manual F CAQLK OS 9 Technical Manual F CRLK OS 9 Technical Manual F DDLK OS 9 Technical Manual F DELLK OS 9 Technical Manual F RELLK OS 9 Technical Manual F WAITLK OS 9 Technical Manual A MICROWARE _os9 delbit Deallocate in Bit Map Syntax include lt memory h gt finclude lt types h gt error_code _os9_delbit u_int32 bit_number u_int32 count void address Description _os9_delbit clears bits in a buffer that represents a bit map Bit numbers range from 0 ton 1 where nis the number of bits in the bitmap bit number specifies the bit number of the first bit to clear Only the lower 16 bits of bit number are used count specifies the number of bits to clear Only the lower 16 bits of count are used address is a pointer to the base address of a bitmap Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also o59 _ allbat 0 os cpymem 089 schbit F DelBit OS 9 Technical Manual os delete Delete File Synta finc finc X
63. loadp os mkmodule os modaddr os setcrc 65 Slinki i Gs slinkmi oB tilnkmi os tlink s unilink os unloadt os vmodul os9 vmodulf prgname setcrc _sliblink _subcall POSIX messaging data structures and functions mqueue h contains prototypes for the following functions mq close mq getattr mq notify mq notify write mq open mq receive mq send mq setattr mq unlink Indicates a standard ANSI header Table 1 2 Ultra C Header Files continued File Description os9def h os9time h os9types h A series of macros mapping UNIX macros and function calls to their OS 9 versions alarm alloca bemp bcopy buildpath bzero Soret Creole t cdup2 execl 7 execle execv execve execvp ffs getgid getopt getppid getwd ioctl isattyi lftocri pclose pipe popen putenv readv setgid tempnam writev Defines interval timer support for OS 9 gettimeofday Synchronous I O multiplexing os9types h contains a prototype for the following function select Indicates a standard ANSI header WX MICROWARE Table 1 2 Ultra C Header Files continued File Description process h Process descriptor and functions that manipulate processes process h contains prototypes for the following functions chainc chain _cpymem getpid get process desc get process table
64. lt events h gt int ev signal int ev id int allflag Description ev signal indicates that an event has occurred The current event variable is updated by the signal increment which was given when the event was created ev idis the event ID returned from a call to ev creat ev link os ev creat Ofr os ev link allflag specifies the process es to activate Only the lower 16 bits of allflag are used e Ifallflag is zero the first process waiting for the event is activated e Ifallflag is 0x8000 all processes waiting for the event that have a value in range are activated OS 9 for 68K ev signal returns the value of the event before incremented by the signal increment If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Clear the global variable errno prior to calling ev signal to distinguish between return of a prior event value of 1 and an error OS 9 ev signal returns zero If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno WX MICROWARE For More Information Refer to your operating system technical manual for more information about events Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also ev creat exv iirnkti os ev creat Jos ev link
65. lt signal h gt int tsleep unsigned svalue Description tsleep deactivates the calling process for a specified interval svalue specifies the interval e f svalue is 0 the process sleeps indefinitely e fsvalueis 1 the process gives up the current time slice For values greater than one svalue is considered a tick count to sleep if the high bit is clear If the high bit of svalue is set the remaining 31 bits are considered the number of 256ths of a second to sleep If the sleeping process is awakened prematurely by a signal tsleep returns the number of ticks remaining to sleep Note The thread enabled version of this function contains a cancel point For more information see Using OS 9 Threads Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l1 See Also os sleep os9 sleep FSSleep OS 9 for 68K Technical Manual F_SLEEP OS 9 Technical Manual WX MICROWARE ungetc Unget Character Syntax include lt stdio h gt int ungetc int C FILE stream Description ungetc pushes a character converted to an unsigned char back onto the input stream The pushed back character is returned by subsequent reads on that stream in the reverse order of their pushing A successful intervening call with the stream pointed to by stream to a file positioning function fseek setpos Or rewind discards
66. named message queue already exists The mq open operation was interrupted by a signal The mq open operation is not supported for the given name The implementation shall document under what circumstances this error may be returned O CREAT was specified in o 1ag the value of attr is not NULL and either mq maxmsg Of mq msgsize was less than or equal to zero Too many message queue descriptors or file descriptors are currently in use by this process The length of the name string exceeds PATH MAX or a pathname component is longer than NAME MAX while POSIX NO TRUNC is in effect Too many message queues are currently open in the system O CREAT is not set and the named message queue does not exist There is insufficient space for the creation of the new message queue mq open not supported Attributes Operating System OS 9 State User Threads Safe Re entrant No Standards POSIX Library mq l See Also mq_close mq receive mq send Jc SOULHULI mo dqetattr mq unlink WX MICROWARE mq receive Receive a Message From a Message Queue Syntax finclude lt mqueue h gt size t mq receive mqd t mqdes char msg ptr size t msg len unsigned int msg prio Description mq receive is used to receive the oldest of the highest priority message s from the message queue specified by mqdes If the size of the buffer in bytes specified by the msg 1en argument is less than the mq m
67. of 128 or 256 bytes for the gs devn Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l1 See Also OS gs devnm ISGetStt OS 9 for 68K Technical Manual I GETSTAT SS DEVNAME OS 9 Technical Manual WX MICROWARE gs eof Check for End of File Syntax include sg codes h int gs eof int path Description gs eof determines if the file open on path is at the end of file If it is at the end of file 1 is returned Otherwise 0 is returned path specifies the path number of the open file If path is invalid 1 is returned and the appropriate error code is placed in the global variable errno Note gs eo cannot determine end of file on SCF devices SCF devices return an EOS EOF error when the EOF character is read Do not use this call if you are using the buffered I O facility on the path Instead use feof Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also feotf os gs eof ISGetStt OS 9 for 68K Technical Manual I GETSTAT OS 9 Technical Manual SS EOF OS 9 Technical Manual A MICROWARE _gs_gfd Get File Descriptor Sector Syntax include lt rbf h gt int _gs_gfd THE path struct fd buffer int count Description _gs_gfd places a copy of the RBF file descriptor se
68. os id Get Process ID User ID Syntax finclude lt process h gt finclude lt types h gt error code os id process id proc id u intl16 priority u intl6 age int32 schedule u intl6 group u intl6 user Description os id returns the caller s process ID number current process priority and age scheduling constant and owner ID proc idis a pointer to the location where os id stores the current process ID number priority is a pointer to the location where os id stores the priority of the current process age is a pointer to the location where os id stores the age of the current process schedule is a pointer to the location where os id stores the scheduling constant of the current process group is a pointer to the location where os id stores the group number of the current process user is a pointer to the location where os id stores the user number of the current process WX MICROWARE HM Note On OS 9 for 68K the binding for this call performs conversions which allow compatibility with OS 9 If speed is a consideration see eo xS Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also o9 ad 676 Ultra C Library Reference _os9_id Get Process ID User ID Syntax finclude lt process h gt finclude lt types h gt error_code _os9_id process_id proc id
69. os lib l mt os lib l1 See Also oS8 thexit os thread WX MICROWARE OS 9 User and System Safe Yes os thread Set Thread Parameters Syntax include lt funcs h gt include lt threads h gt error code os thread u int32 code thread t thread id void arg Description _os_thread sets thread parameters for the thread specified by thread id code is the subfunction to perform The legal values for code are TH ORPHAN to orphan the thread and TH TSDATA to set the thread specific data for the thread If code is TH TSDATA arg is the thread specific data pointer Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l1 mt os lib l See Also os thexit 6 thfork WX MICROWARE os tlink Install User System State Trap Handling Module Syntax include lt module h gt finclude lt types h gt error code _os_tlink u_int32 trap_num char mod_name void ib exec mh trap mod head void params u int32 mem size Description os tlink attempts to link or load the specified module If a trap module already exists for the specified trap number an error is returned If static storage is required for the trap handler it is allocated and initialized trap num Specifies the user trap number 1 through 15 mod name is a pointer to the name of the trap module If mod name is zero or points to a null string
70. os rtnprc deallocates a process descriptor previously allocated by os alocproc You must ensure that the process system resources are returned before calling os rtnprc proc id identifies the process descriptor Attributes Operating System OS 9 and OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l See Also ps aloecproet Da f1ndpdti os9 salarm atdate Execute System State Subroutine at Gregorian Date Time Syntax finclude lt regs h gt include lt alarm h gt finclude lt types h gt error_code _os9_salarm_atdate alarm_id alrm id u int32 time u int32 date REGISTERS regs Description os9 salarm atdate executes a system state subroutine at a specific date and time The alarm subroutine executes anytime the system date time becomes greater than or equal to the alarm time alrm idis a pointer to the location where os9 salarm atdate stores the alarm ID time is the time for the alarm to go off in the form 00hhmmss date is the date for the alarm to go off in the form yyyymmda regs is a pointer to the register image to pass to the function The address of the system state subroutine to execute should be set in regs pc Note os9 salarm atdate only allows you to specify the time to the nearest second However it does adjust if the system s date and time have changed using os9 setime Attributes Operating System State
71. path struct stat buf Description stat obtains information about the file named by path Read write or execute permission of the named file is not required but all directories leading to the file must be searchable buf is a pointer to a stat structure into which information about the file is placed A stat structure includes the following members unsigned short st mode attributes unsigned short st nlink nhard links unsigned short st uid user ID of owner unsigned short st gid group ID of owner unsigned long st size file size time t st atime last access time time t st mtime last modify time time t st ctime last status change time long st ino undefined long st dev undefined long st rdev undefined If an error occurs stat returns 1 and sets the global variable errno to indicate the error Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l1 See Also fstat WX MICROWARE Ultra C Library Reference _strass Structure Assignment Syntax include lt strings h gt void _strass void to void from int count Description _strass is available to maintain source code compatibility count bytes are copied from the memory pointed to by from to the memory pointed to by t o regardless of contents to is a pointer to the de
72. repeated searches Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix l See Also endpwent fgetpwent getpwent getpwnam getpwuid WX MICROWARE setstat Set File Status Syntax include sg codes h finclude lt sgstat h gt int setstat int code THE path char buffer code 0 int setstat int code int path long size code 2 Description setstat sets the path options or the file size of the file open on path If code is 0 the buffer is copied to the path descriptor options section The sgstat h header file contains the definitions for the path options If code is 2 size should be an int specifying the new file size Only the lower 16 bits of code are used path is the path number of the open file buffer is a pointer to the buffer containing the path descriptor options size is the size of the new file If an error occurs both forms of the call return 1 and place the appropriate error code in the global variable errno Note This call exists for 6809 portability The os ss functions are the preferred versions of these function calls Attributes Operating System State Threads Re entrant Library Sys clib l See Also getstat DS SS sbtr os9 ss close e cs OOONU Dm 23 Sort 08 58 dsrts O3 Ang cnra OS SS erase coe cm Tull os 58 look s 5s
73. segment attr specifies the segment attributes selector specifies the selector entry value Note make idesc is only supported by the 80x86 family of processors version of the compiler Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library epou l make module Create Module Syntax include lt memory h gt include lt module h gt mh_com make_module char name int size int attr int perm int typelang int color Description make module creates a memory module with the specified name and attributes in the specified memory make module is similar to mkdata module However make module allows you to specify the type language of the module and color of memory in which to make the module mod exec is defined in the module h header file name is a pointer to the name of the module size specifies the desired memory size of the module in bytes The size value does not include the module header and CRC bytes size is the amount of memory available for actual use The memory in the module is initially cleared to zeroes attr specifies the module s attribute and revision level Only the lower 16 bits of attr are used perm specifies the module permissions Only the lower 16 bits of perm are used typelang specifies the type and language of the module Only the lower 16 bits of typelang are used WX MICROWARE color indicat
74. the existing registration is removed The message queue is then available for registration If a process has registered for notification of a message queue and some thread is blocked in mg send waiting to send a message when the message queue transitions to nonfull the arriving message will satisfy the appropriate mg send The resulting behavior is as if the message queue remains full and no notification is sent Errors EBADF The mqdes argument is not a valid message queue descriptor EBUSY A process is already registered for notification by the message queue ENOSYS mq notify not supported Attributes Operating System State Threads Re entrant Standards Library mq 1 See Also mq open mq send fug setattr AA MICROWARE OS 9 User Safe POSIX MQ O0 NOTIFY MME mq open Open a Message Queue Syntax finclude mqueue h mqd t mq open const char name int oflag Description mq open establishes the connection between a process and a message queue with a message queue descriptor It creates an open message queue description that refers to the message queue and it creates a message queue descriptor that refers to that open message queue description The name argument points to a string naming a message queue It is unspecified whether the name appears in the file system and is visible to other functions that take pathnames as arguments The name arg
75. the shift state of mot owc is unaffected mbtowc wchar t 0O s n str is a pointer to a multibyte character num is the number of bytes to search If str is a null pointer molen returns a non zero value if the multibyte character encodings have state dependent encodings or returns a zero value If str is not a null pointer molen returns e Oif str points to the null character The number of bytes contained in the multibyte character if the next num or fewer bytes form a valid multibyte character e 1 if they do not form a valid multibyte character mblen is supported for both the c and JAPAN locales Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 See Also mbtowc Ultra C Library Reference 447 WX MICROWARE mbstowcs Convert Sequence of Multibyte Characters Syntax include lt stdlib h gt size t mbstowcs wchar t pwcs const char Str size t num Description mbstowcs converts a sequence of multibyte characters that begins in the initial shift state into a sequence of corresponding codes and stores not more than num codes in an array No multibyte characters that follow a null character are examined or converted A null character is converted into a code with value zero Each multibyte character is converted as if by a call to mbt owc except that the shift state of mbto
76. values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b iseucl c Ultra C Library Reference 389 WX MICROWARE Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library ctype h See Also isalnum isalpha lsecmurli isdigit isgraph islower isprint lepunct isspace isupper l8 151 isgraph See If Parameter Is Printing Character Syntax include lt ctype h gt int isgraph int c Description isgraph is a C macro that returns a non zero value if c is any printing character except a space Otherwise it returns zero c is the character to test Note This routine available as a function or a macro in ctype h does not operate well with values outside the range of an unsigned char The function checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it
77. void irq restore status code stat reg Description irq restore sets the interrupt level stat code specifies the value to put in the processor status register Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library Cpu See Also irq change irq disable irq enable irq maskget irq save irq save Return Current Interrupt Level Syntax include regs h status code irq save void Description irq save returns the current value of the status register Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library GOD See Also irq change irq disable irq enable irq maskget irq restore o WX MICROWARE isalnum See If Parameter Is Alphanumeric Syntax include lt ctype h gt int isalnum int c Description isalnum returns a non zero value for any character for which isalpha or isdigit is true c is the character to test Note This routine available as a function or a macro in ctype h does not operate well with values outside the range of an unsigned char The function checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the u
78. xxx mmm dd hh mm ss yyyy n 0 xxx is one of the following days of the week Table 2 1 Days of Week Sun Mon Tue Wed Thu Fri Sat mmm is one of the following months of the year Table 2 2 Months of Year Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec dd specifies the day of the month hh mm ss specifies the time in hours minutes and seconds yyyy specifies the year tp is a pointer to the broken down time structure PF ru Inctions m WX MICROWARE Note asctime returns a pointer to a static area which may be overwritten To insure data integrity use the string or save it immediately Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library cITb l See Also ctime localtime gmtime sys mktime strftime lita V 1 3svram Bst5rnma Ultra C Library Heference asin Arc Sine Function Syntax include lt math h gt double asin double x Description asin returns the arc sine of x in the range x 2 m 2 radians A domain error EDOM stored in errno occurs for parameters not in the range 1 1 On error asin returns HUGE VAL Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 Possible Error EDOM WX MICROWARE assert Place Diagnostics in Programs Syntax in
79. 1 memmove Move Memory Syntax include lt string h gt void memmove void dest const void source size t num Description memmove copies characters from one location to another Copying takes place as if the characters from the original location are first copied into a temporary array of num characters that does not overlap dest and source and then the num characters from the temporary array are copied into dest dest is a pointer to the destination in memory source is a pointer to the memory to copy into dest num is the number of characters to copy memmove returns the value of dest Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clas WX MICROWARE memset Fill Memory Syntax include lt string h gt void memset void mem int Erll size t size Description memset copies the value of 111 converted to an unsigned char into each of the first size characters of mem memset returns the value of mem mem is a pointer to the memory to fill fill is the value with which to fill an area of memory size is the number of characters to fill with 111 Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 _mkdata_module Create Data Memory Module Syntax include lt module h gt c
80. 35 strftime Conversion Values continued Value Replaced By oo oe X o Pas o kK oo lt oo N oo oo The week number of the year the first Monday as the first day of week 1 as a decimal number 00 53 The locale s appropriate date representation The locale s appropriate time representation The year without century as a decimal number 00 99 The year with century as a decimal number The time zone name or abbreviation or by no characters if no time zone is determinable If a conversion specifier is not one of the above the behavior is undefined If the total number of resulting characters including the terminating null character is not more than maxsize strftime returns the number of characters placed into array dest not including the terminating null character Otherwise zero is returned and the contents of the array are indeterminate Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 WX MICROWARE strhcpy Copy Old OS 9 for 68K Strings Syntax include lt strings h gt char strhcpy char dest char rS Description strhcpy makes a copy of src in dest dest is a pointer to the destination string src is a pointer to the source string to copy src is assumed to have the high order bit set on the character byte indicating the last character strhcpy c
81. 37 sys clib Function Equivalents continued sys clib Function Corresponding Function alm atjul os alarm atime os9 alarm atjul dup os dup alm cycle os alarm cycle ebrk malloc alm delete 09 alarm delete errmsg strerror alm set 0s alarm set ev oreat Do amp ev creati attach OS strtachi ev delete i o amp ev delere ev info os ev info chainc chain 5s chain _ev_link _os_ev_link ends 0 pe chdgarfj ev pulse os ev pulse chmod Da ms attri ev readt t 08 ey read chown 1608 om I0 Ultra C Library Reference 103 1 Overview WX MICROWARE Table 1 37 sys clib l Function Equivalents continued Sys clib I Function Corresponding Function ev set chxdir ev setr _cleareof cleareof ev signal ev unlink close ev wait closedir ev waitr cmpnam exit cpymem fdopen eren findnstr creat findstr 104 JO Ev SEE os chgdari Ds ew setrij clearerr os ev signal os ev unlink IOS closet os ev wait os9 ev wait pDs closet os ev waitr os9 ev waitr _os_cmpnam _os_exit _os_cpymem none Da CPGT Strstrn oS create gtrstreli Ultra C Library Reference Overview Table 1 37 sys clib Function Equivalents continued sys clib l Function Corresponding Function get
82. 40 664 os gs fdinf 40 665 os gs luopt 41 668 Os gs parity 41 669 os gs popt 41 670 os gs pos 41 671 os gs ready 41 673 os gs size 41 674 os sgetstat 41 772 os sgs devnm 41 _os9 gs cdfd 40 653 _os9_ gs free 41 667 calculate parity of file descriptor 41 669 check for end of file 39 346 copy contents of path descriptor 40 654 examine system global variable 40 649 get cache status information 40 655 current file position 39 41 352 671 current file size 39 355 device name 39 344 device status 40 648 file descriptor block address for open file 40 664 descriptor sector 39 40 348 status 40 332 648 I O interface edition number 40 661 path options 39 350 size of SCSI device 40 660 specified file descriptor sector 665 GetStat call using system path number 41 772 getstat 332 ABCDEFGHIJKLMNOPQRSTUVWXYZ list of functions 39 read device path options 40 659 file descriptor sector 40 663 logical unit options 41 668 path descriptor options section 41 670 return amount of free space on device 41 667 current file size 41 674 device name 40 41 656 device type 40 657 file descriptor 40 653 test for data available 39 353 for data ready 41 673 for end of file 40 662 getstat 105 332 gettimeofday 337 getuid 65 105 338 getw 48 105 339 getwd 340 global descriptor make entry in table 439 make gdesc 439 set pointer 930 set gdtr 930 globals 12 GMT 84 gmtime
83. 401 403 lowercase 36 395 printable character 36 397 printing character 36 391 punctuation character 36 399 uppercase 37 407 white space 37 405 character conversion ABCDEFGHIJKLMNOPQRSTUVWXYZ aton 37 140 atou 38 142 _dtoa 38 194 _toascii 38 1055 _tolower 38 1056 _toupper 38 1058 alpha to floating 37 137 integer 37 138 long 37 139 numeric 37 140 unsigned 38 142 atof 37 137 atoi 37 138 atol 37 139 convert double to ASCII 38 to lowercase 38 1056 1057 to uppercase 38 1058 1059 double to ASCII 194 list of functions 37 toascii 1055 tolower 38 1057 toupper 38 1059 translate 38 1055 chdir 103 160 check buffered file for end of file 241 error condition 242 for deadlock situation 552 end of file 346 use of I O module 682 memory block s accessibility 532 terminal capability presence 1045 chmod 103 162 chown 103 164 chxdir 46 104 166 clear end of file condition 168 ABCDEFGHIJKLMNOPQRSTUVWXYZ error condition 170 process signal queue 536 cleareof 168 clearer 46 170 clib J 10 102 clock 87 171 erafor 102 CLOCKS PER SEC 124 127 171 close file 237 named directory stream 174 path 172 535 798 close 46 104 172 closedir 104 174 colored memory allocate 966 load module into 464 modcload 464 srqcmem 966 compare memory 453 names 538 strings 175 1000 1001 1011 compute absolute value 415 floating point remainder 255 Idiv 419
84. 58 92 98 950 957 signal h 29 signals asynchronous 956 available 952 default handling 951 function handling 956 ignore handling 952 SIGNMI 96 955 SIGPIPE 94 953 SIGPRIV 95 97 954 956 SIGQUIT 94 953 SIGSEGNP 96 955 SIGSEGV 93 952 SIGSTACK 96 955 SIGTERM 93 952 SIGTRACE 95 954 SIGTRAPV 95 954 SIGUNIRQ 954 SIGUSR1 94 953 SIGUSR2 94 953 SIGWAKE 94 953 sin 61 958 ABCDEFGHIJKLMNOPQRSTUVWXYZ sine function 958 arc 131 hyperbolic 959 sinh 61 959 skip blocks 821 tape marks 818 to end of tape 822 sleep os sleep 782 OS9 sleep 784 current process 782 for specified interval 1062 tsleep 1062 sleep 78 109 specify signal handling 950 sprintf 51 962 sqrt 61 964 square root function 964 srand 61 965 srqcmem 64 109 966 sscanf 51 973 stack _freemem 272 _stacksiz 994 determine size of area 272 freemem 272 get size of 994 stacksiz 994 stack frame allocate space alloca 119 stacksiz 994 standard white space characters 405 start next process 712 system debugger 1036 stat 995 static storage os initdata 678 ABCDEFGHIJKLMNOPQRSTUVWXYZ change current pointer 159 get static 335 initialize 678 return current pointer 335 status functions gs devn 344 gs eof 346 gs gfd 348 gs opt 350 gs pos 352 gs rdy 353 gs size 355 OS getstat 648 OS getsys 649 OS gs cpypd 654 OS gs cstats 655 _os gs devnm 656 Os gs devtyp
85. 657 OS gs dopt 659 OS gs dsize 660 OS gs edt 661 OS gs eof 662 Os gs fd 663 Os gs fdaddr 664 Os gs fdinf 665 Os gs luopt 668 OS gs parity 669 OS gs popt 670 OS gs pos 671 Os gs ready 673 OS gs size 674 OS setstat 765 OS setsys 770 OS sgetstat 772 os sgs devnm 773 OS ss attr 795 OS ss break 796 Os ss cache 797 OS ss close 798 OS ss dcoff 799 Os ss dcon 800 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z os ss dopt 801 OS ss dsrts 802 OS ss enrts 803 _os_ss erase 804 os ss fd 805 os ss fillbuff 806 os ss flushmap 807 os ss hdlink 808 os ss lock 810 os ss luopt 811 OS ss popt 813 os ss relea 814 os ss rename 815 OS Ss reset 816 os ss reten 817 os ss rfm 818 Os ss sendsig 819 OS SS size 820 os ss skip 821 OS ss skipend 822 OS ss ticks 823 os ss wfm 824 OS Ss wtrack 825 os9 gs cd d 653 _os9_ gs free 667 _os9 ss open 812 Ss attr 971 Ss dcoff 975 _ss dcon 976 Ss dsrts 977 Ss enrts 978 Ss lock 979 Ss opt 981 Ss pfd 983 Ss rel 985 Ss rest 986 Ss size 987 Ss ssig 988 Ss tiks 990 _ss_wirk 992 break serial connection 796 ABCDEFGHIJKLMNOPQRSTUVWXYZ calculate parity of file descriptor 669 check for end of file 346 disable RBF caching 797 RTS line 802 977 enable RBF caching 797 RTSline 803 978 erase tape 804 examine system global variable 649 fill path buffer with
86. 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI co o w Ultra C Library Reference WX MICROWARE Library ctype h See Also isalnum isalpha lSCUDEL isspace isupper H n Oo K H 5 E ct nd ee es a ee 396 Ultra C Library Reference isprint See If Parameter Is Printable Character Syntax include lt ctype h gt int isprint int c Description isprint is aC macro that tests for printing characters It returns a non zero value for ASCII characters with values from 0x20 to 0x7e c is the character to test Note This routine available as a function or a macro in ctype h does not operate well with values outside the range of an unsigned char The function checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b isprint c Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Ultra C Library Reference 397 WX MICROWARE Library ctype h See Also isalnu
87. Both memory areas are assumed to be the given length len If Len is zero the function returns zero Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l See Also bcopy bzero ffs WX MICROWARE bcopy Copies Bytes from One Memory Area to Another Memory Area Syntax finclude UNIX os9def h void bcopy void addrl void addr2 unsigned int len Description bcopy copies bytes of length Len from one memory area addr1 to another addr2 Overlapping memory areas are handled correctly Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library unix l See Also bcmp bzero ffs bsearch Search Array Syntax include lt stdlib h gt void bsearch const void key const void base size t nmemb size t size int compar const void const void Description bsearch searches an array of nmemb objects for an element that matches key key is a pointer to the key object base is a pointer to the initial element of the array nmemb specifies the number of array elements size specifies the size of each array element compar is a pointer to a comparison function compar is called with two parameters that point to the key object and to an array element in that order compar returns an integer that is Negat
88. CRC module h _get_module_dir Get module directory module h entry make_module Create module module h _mkdata_module Create data memory module h module modcload Load module into module h colored memory modlink Link to memory module module h Table 1 15 Module Manipulation Functions continued ANSI Function Standard Description Header File modload Load and link to module h memory module modloadp Load and link to module h memory module using PATH munlink Unlink from module module h munload Unload module module h _os_altmdir Set alternate working moddir h os chainm os chmdir os cmdperm 05 ore os datmod os delmdir os fmod module directory Execute new primary module given pointer to module Change process current module directory Change permissions of module directory Generate CRC Create data module Delete existing module directory Find module directory entry process h moddir h moddir h module h module h moddir h module h WX MICROWARE Table 1 15 Module Manipulation Functions continued ANSI Function Standard Description Header File _os_get_mdp Get current and moddir h alternate module directory pathlists _os_get_moddir Get copy of module module h directory _os_initdata Initialize static storage module h from module os link Link to memory module module h oe li
89. EVENT EV CHANGE OS 9 Technical Manual F EVENT EV SIGNL OS 9 Technical Manual 0S ev creat Create New Event Syntax include lt events h gt finclude lt types h gt error_code _os_ev_creat int32 winc int32 sinc u_int32 perm event_id ev id char name int32 value u int32 color Description os ev creat allows you to create events dynamically as needed When an event is created an initial value is specified as well as increments to apply each time the event is waited for or an event signal occurs Subsequent os event calls use the returned ID number to refer to the created event winc specifies the auto increment value for os ev wait Only the lower 16 bits of winc are used sinc specifies the auto increment value for os ev signal Only the lower 16 bits of sinc are used perm specifies the access permissions Only the lower 16 bits of perm are used Note OS 9 for 68K ignores perm ev idis a pointer to the location where os ev creat stores the event identifier WX MICROWARE name is a pointer to the event name string value specifies the initial event variable value color specifies the memory type for the event structure Only the lower 16 bits of color are used Note OS 9 for 68K ignores color Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also os ev
90. F CCTL OS 9 Technical Manual os caglk Conditionally Acquire Ownership of Resource Lock Syntax incl incl lude lt lock h gt lude lt types h gt error code os caqlk lk desc lock Description lock os caqlk is used to conditionally acquire ownership of a resource lock is a pointer to the lock If another process does not own the lock the calling process is granted ownership and the call returns without error If the lock is already owned the calling process is not suspended Instead it returns from the os caql1k call with an EOS NOLOCK error and is not granted ownership of the resource lock Attributes Operating System State Threads Re entrant Library lock 1 See Also F_ACQLK F_CAQLK F_CRLK FE E F RELLK F WAITLK DDLK DELLK OS 9 System Safe Yes OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual WX MICROWARE os chain Execute New Primary Module Syntax finclude lt process h gt include lt module h gt finclude lt types h gt error_code _os_chain u_int32 priority u int32 path cnt char mod name void params u int32 param size u int32 mem size u int32 type lang Description oS chain executes a new program without the overhead of creating a new process It is functionally similar to a
91. First Byte of SUIS Kanji Syntax include lt ctype h gt int _issjisl int c Description _issjisi1 is a C macro that returns a non zero value if c is the first byte of a Shift JIS Japanese Industrial Standard Kanji character Otherwise it returns zero The valid ranges for Shift JIS first bytes are between 0x81 and 0x9f or between 0xe0 and Oxfc c is the character to test Note This routine available as a function or a macro in ctype h does not operate well with values outside the range of an unsigned char The function checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b issjis1 c Ultra C Library Reference 401 Attributes Operating System State Threads Re entrant Library ctype h See Also isalnum isalpha lsenmurli isdigit t isgraph islower Lepr Lie l8punct issjis2 isspace isupper lsxdiqiti WX MICROWARE OS 9 and OS 9 for 68K User and System Safe Yes Ultra C _issjis2 See If Parameter Is Second Byte of SJIS Kanji Syntax
92. Fork command followed by an Exit os chain effectively resets the calling process program and data memory areas and begins executing a new primary module Open paths are not closed or otherwise affected priority is the priority of the process Only the lower 16 bits of priority are used path cnt specifies the number of I O paths to copy Only the lower 16 bits of path cnt are used mod name is a pointer to the new program to execute params is a pointer to the parameter block param size specifies the size of the parameter block mem size specifies the additional memory size in bytes type lang specifies the desired module type language type lang must be either program object MT PROGRAM MI OBJECT or zero for any Only the lower 16 bits of type 1ang are used Note On OS 9 for 68K os chain never returns to the calling process On OS 9 an error is returned only if there is not enough memory to hold the parameters If an error occurs during the chain it is returned as an exit status to the parent of the process performing the chain Attributes Operating System State Threads Re entrant Library os lib l See Also oS ros 08 load FSChain F_CHAIN OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE os chainm Execute New Primary Module Given Pointer to Module Syntax finclude lt process h gt finclude
93. I O operation when signals arrive but the signal handling routine is not executed until the signals are unmasked The process signal mask is automatically incremented while the intercept routine is executing This prevents the intercept routine from being accidentally re entered if a new signal arrives The process may use sigmask within its intercept routine to allow re entrant signals or to force the signal mask to remain non zero when normal program execution resumes WX MICROWARE When a process makes an F S1eep or F Wait for OS 9 for 68K or F SLEEP or F WAIT for OS 9 system call its signal mask is automatically cleared If any signals are pending the process returns to the intercept routine without sleeping The S KILL and S WAKE signals ignore the state of the signal mask and are never queued 8 KILL terminates the receiving process and S WAKE ensures that the receiving process is active If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno If errors do not occur sigmask returns zero Note I O operations using the cio library should not be performed by both the main program and the intercept routine If an intercept routine is exited with long jmp the signal mask is still set to one Generally the destination of the long jump should unmask signals immediately OS 9 for 68K The depth to which signals may be queued is limited only b
94. Library clib 1 Idiv Compute Quotient and Remainder Syntax include lt stdlib h gt ldiv t ldiv long int numer long int denom Description ldiv returns the quotient and remainder of the division of the numerator by the denominator The parameters and member of the returned structure are all of type Long int numer is the numerator denom is the denominator Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 See Also div WX MIC ROWARE Ifree Return Memory Low Overhead Syntax include lt stdlib h gt void _lfree void OUr unsigned long size Description _lfree returns a block of memory granted by 1calloc or lmalloc The memory is returned to a pool of memory for later re use by calloc lcalloc lmalloc O0rmalloc ptr is a pointer to the memory block size specifies the size of the memory block lfree never returns an error Note Use of the low overhead allocation functions _lcalloc lmalloc and _1lrealloc instead of the general allocation functions calloc malloc and realloc saves 8 bytes per allocation because the low overhead functions do not save the allocation size or the 4 byte check value Note If 1free is used with something other than a pointer returned by lcalloc Or 1malloc the memory lists maintained b
95. OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library elabsL WX MICROWARE tanh Hyperbolic Tangent Function Syntax include lt math h gt double tanh double x Description tanh returns the hyperbolic tangent of x Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 telldir Return Current Location Syntax include lt dir h gt long telldir DIR dirp Description telldir returns the current location associated with the named directory stream dirp is a pointer to the directory stream Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also closedir opendir readdir rewinddir seekdir WX MICROWARE tempnam Create Names for Temporary Files Syntax include UNIX os9def h char tempnam char dt char pfx Description tempnam generates names that can safely be used for temporary files tempnam allows the user to control the choice of a directory The argument dir points to the name of the directory in which the file is to be created If dir is NULL or points to a string which is not a name for an appropriate directory is used This entire sequence can be preempted by setting the environment variable
96. OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual WX MICROWARE setuid Set User ID Syntax finclude lt process h gt int setuid int uid Description setuid sets the group user ID of the process to uid The following restrictions govern the use of setuid User number 0 0 may change his her ID to anything without restriction e A primary module owned by user 0 0 may change the process user ID to anything without restriction e Any primary module may change the process user ID to match the module s owner If the call fails 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also getuid setvbuf Set Up Buffer for I O Stream Syntax include lt stdio h gt int setvbuf FILE stream char buf int mode size t size Description setvbuf sets up buffering for an I O stream It may be used only after the st ream has been associated with an open file and before any other operation is performed on the stream stream is a pointer to the C I O FILE structure buf is a pointer to a buffer If buf is not a null pointer the library may use the array it points to instead of a buffer allocated by setvbuf mode determines how stream is buffered Table 2 27 setvbug Parameter M
97. Pointer to floating point register stack for child process _os9_dfork addl Child process ID returns to the location of the add1 pointer add2 Type language of the new process add3 Pointer to register stack for child process WX MICROWARE Table 2 18 _os_exec Additional Parameters continued Call Parameter Definition os dforkm addl Child process ID returns to the location of the add1 pointer add2 Pointer to register stack for child process add3 Pointer to floating point register stack for child process On OS 9 for 68K the orphan flag must be set to zero Note If you are using _os_exec when func indicates a chain function you must provide a full pathlist for the module or verify that the module is already in memory _os_exec returns the value of func It returns 0 if successful Otherwise it returns an error number Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os_lib l See Also os chain os chainm o05 dforki cB arorkm oS fork oS forkm os9fork i osOforko t os9exec os9kexec Example include lt process h gt include lt dexec h gt include lt errno h gt include lt cglob h gt include lt types h gt char argblk 0 050 4 0 07 0 Use the environment pointer given to you by the shell Create an array of pointers to
98. Process That a Message is Available on a Queue Syntax finclude mqueue h int mq notify mqd t mqdes const struct sigevent notification Description If the argument notification is not NULL this function registers the calling process to be notified of message arrival at an empty message queue associated with mqdes the specified message queue descriptor The notification specified by the notification argument is sent to the process when the message queue transitions from empty to nonempty At any time only one process can be registered for notification by a message queue If the calling process or any other process has already registered for notification of message arrival at the specified message queue subsequent attempts to register for that message queue fail If notification is NULL and the process is currently registered for notification by the specified message queue the existing registration is removed When the notification is sent to the registered process its registration is removed The message queue is then available for registration If a process has registered for notification of message arrival at a message queue and some thread is blocked in mq receive waiting to receive a message when a message arrives at the queue the arriving message satisfies the appropriate mq receive The resulting behavior is as if the message queue remains empty and no notification is sent Upon successful completion mq n
99. Re en trant Library os lib l See Also OS salarm set F ALARM OS 9 System Safe Yes OS 9 Technical Manual os salarm set Set Alarm Clock Syntax include lt alarm h gt finclude lt types h gt error_code _os_salarm_set alarm_id alrm id u int32 time u int32 flags u int32 func void func pb Description os salarm set executes the specified subroutine after the specified time interval has elapsed alrm idis a pointer to the location where os salarm set stores the alarm ID t ime specifies the alarm s time interval or a time time may be specified in system clock ticks or if the high order bit is set the low 31 bits are considered a time in 256ths of a second Usually the minimum time interval allowed is 2 system clock ticks flags specifies the alarm flags func is a pointer to the function to execute func pb is a pointer to the function s parameter block Attributes Operating System OS 9K State System Threads Safe Re entrant Yes Library os lib l See Also F ALARM OS 9 Technical Manual WX MICROWARE os9 salarm set Execute System State Subroutine after Specified Time Interval Syntax finclude lt regs h gt include lt alarm h gt finclude lt types h gt error_code _os9_salarm_set alarm_id alrm id u int32 time REGISTERS regs Description os9 salarm set executes a system state subroutine after the specified time
100. Standards ANSI Library clib 1 localtime Convert Calendar Time to Local Time Syntax include lt time h gt struct tm localtime time_t timer Description localtime converts a calendar time into a broken down time expressed as local time timer is a pointer to the calendar time Note localtime returns a pointer to a static area which may be overwritten To ensure data integrity use the value or save it immediately Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also mktime for more information on the time structure tm t ime WX MIC ROWARE log Natural Logarithm Syntax include lt math h gt double log double x Description log returns the natural logarithm of x A domain error occurs EDOM stored in errno if x is negative A range error ERANGE stored in errno occurs if x is zero 1og returns HUGE VAL for both errors Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library Clin l Possible Errors EDOM ERANGE log10 Base Ten Lo garithm Syntax include lt math h gt double logl0 double x Description log10 returns the base ten logarithm of x A domain error Ei DOM stored in errno occurs if x is negative A range error ERANGE stored i
101. State User and System Threads Safe Re entrant Yes Library Sys clib l WX MICROWARE WX MICROWARE ibrk Request Internal Memory Syntax include lt stdlib h gt char ibrk unsigned size Description ibrk returns a pointer to a memory block The returned pointer is aligned to a word boundary The memory from which ibrk grants requests is the area between the end of the data allocation and the stack Figure 2 4 ibrk Memory Stack Diagram Highest Addres Grows toward Stack Area ibrk Area Stack Pointer Stack Limit t a eres pee Ara Grows toward area grows stack Program Data Area Lowest Address size specifies the size in bytes of the memory block If the requested size would cause the ibrk area to cross the stack pointer the request fails You can use freemem to determine the amount of stack remaining which is also the remaining ibrk area ibrk is useful to request memory from a fixed size area of memory unlike ebrk whose available memory is that of the entire system The C I O library functions request the first 2K of I O buffers from this area the remainder from ebrk If successful ibrk returns zero Otherwise 1 is returned and the appropriate error code is placed in the global variable errno Note Be very careful not to crowd out the stack with ibrk calls When stack checking is in effect the program aborts with a Stack Overflow mes
102. State Threads Compatibility Reentrant OS 9 for 68K User Safe Yes Description os9 alarm atdate sends a signal to the caller at a specific date and time The alarm signal is sent anytime the system date time becomes greater than or equal to the alarm time alrm idis a pointer to the location where os9 alarm atdate stores the alarm ID signal specifies the signal code date is in the format yyyymmdd time is in the format 00hhmmss Note U a TRE Itra C Lib os9 alarm atdate only allows you to specify the time to the nearest second However it does adjust if the system s date and time have changed using _os9_setime Attributes Operating System OS 9 for 68K State User Threads Safe Re entrant Yes Library os lib l See Also FSAlarm OS 9 for 68K Technical Manual ary Referen EQ rary Reference 505 WX MICROWARE os alarm atime Send Signal at Specified Time Syntax include lt alarm h gt finclude lt types h gt error_code _os_alarm_atime alarm_id alrm id signal code signal u int32 time Description os alarm atime sends a signal when the system time reaches or passes the specified time The time value is considered to be an absolute value in seconds since 1 January 1970 Greenwich Mean Time alrm idis a pointer to the location where os alarm atime stores the alarm ID signal is the signal code of the signal to send t ime specifies the time Attri
103. System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os gs eof Test for End of File Syntax include sg codes h finclude lt types h gt error code os gs eof path id path Description OS gs eof returns the EOS_EOF error if the current position of the file pointer associated with the specified path is at the end of file SCF never returns EOS EOF with this Get Stat path specifies the driver s path number Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 os gs fd Read File Descriptor Sector Syntax include lt rbf h gt finclude lt types h gt error code _os_gs_fd path id path u int32 size fd stats fdbuf Description os gs fd returns a copy of the file descriptor sector for the file associated with the specified path path specifies the driver s path number size is the number of bytes of the file descriptor to copy fdbuf is a pointer to the buffer for the file descriptor sector Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os gs fdaddt Get File Descriptor Block Address for Open File Syntax include lt rbf h gt finclude lt types h gt error code os gs fdaddr path id path u int32 addr Description o
104. Technical Manual F LOAD OS 9 Technical Manual WX MICROWARE os chdir Change Working Directory Syntax include modes h finclude lt types h gt error code os chdir char name u int32 mode Description os chdir changes a process working directory to the directory file specified by the pathlist You may change the execution or the data directory or both depending on the access mode you specify The specified file must be a directory file and the caller must have access permission for the specified mode name is a pointer to the pathlist mode specifies the access mode Only the lower 16 bits of mode are used For More Information Refer to OS 9 Technical Manual or the OS 9 for 68K Technical Manual for the available modes Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also ISChg l Dir _CH D OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE os chkmemY Check Memory Block s Accessibility Syntax finclude lt process h gt finclude lt types h gt error code os chkmem u int32 size u int32 mode void mem ptr pr desc proc desc Description os chkmem determines if a process has access to a specified memory block size specifies the size of the memory area mode specifies the permissions to check Only
105. The characters are passed to the program as read read returns the number of bytes actually read 0 indicates the end of the file If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Note End of file is returned as zero bytes being read not an error indication WX MICROWARE Note The thread enabled version of this function contains a cancel point For more information see Using OS 9 Threads Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also creat create dup open read readln ISRead OS 9 for 68K Technical Manual I_READ OS 9 Technical Manual readdir Return Pointer Syntax include lt dir h gt struct direct readdir DIR dirp Description readdir returns a pointer to a structure containing the next directory entry dirp is a pointer to the directory readdir returns NULL upon reaching the end of the directory or detecting an invalid seekdir operation Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library sys_clib 1 See Also closedir opendir rewinddir seekdir telldir WX MICROWARE readin Read Bytes from Path Syntax include lt modes h gt int readin int path char buffer unsigned count Descripti
106. This call is only available as a macro stream is a pointer to the C I O FILE structure Note If you are executing the compiler in strictly conforming ANSI mode only _fileno is available Otherwise both calls are available Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library These macros are defined in the stdio h header file See Also fopen freopen WX MIC ROWARE findnstr Search String for Pattern Syntax include lt strings h gt int findnstr int pos char string char pattern int len Description findnstr searches the string for the first occurrence of the pattern It starts at position pos where the first position is one not zero The returned value is the position of the first matched character of the pattern in the string or zero if a match is not found findnstr stops searching at 1en it may continue past null bytes pos specifies the starting position string is a pointer to the string to search pattern is a pointer to the pattern to use for the search len specifies the final position to be searched Note The current implementation does not use the most efficient pattern matching algorithm strstr is preferred for very long strings Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library sys clib l See Also f
107. Unfortunately this has the undesired side effect of implying that the fourth fifth and seventh arguments are valid integers when indeed only their lower 16 bits are valid As a result Microware has decided to optionally prototype these functions in system header files sys_clib 1 functions affected by this include os9exec osSfork osStorkc os9kexec ABCDEFGH Index Symbols aton 37 atou 38 atou alpha to unsigned conversion 142 _cleareof 46 104 168 _cmpnam 65 104 175 _cpymem 62 104 179 _dtoa 38 environ 101 errmsg 65 103 201 ERROR 140 ev creat 52 103 203 ev delete 52 103 205 ev info 52 103 206 ev link 53 103 208 ev pulse 53 103 209 ev read 53 103 211 ev set 53 104 213 ev setr 53 104 215 ev signal 53 104 217 ev unlink 53 104 219 ev wait 53 104 221 ev waitr 53 104 223 exit 35 104 232 _fileno 47 249 freemem 62 272 _freemin 274 get name 292 get module dir 68 105 313 get process desc 105 320 get process table 76 105 322 getsys 73 105 336 _gregorian 87 106 342 IJKLMNOPQRSTUVWXYZ ABCDEFGHIJKLMNOPQRSTUVWXYZ gs devn 39 106 344 gs eof 39 106 346 gs gfd 39 106 348 gs opt 39 106 350 _gs_pos 39 106 352 gs rdy 39 106 353 gs size 39 106 355 INTEGER 140 _IOFBF 945 _IOLBF 945 _IONBF 945 _isascii 36 380 isjis kana 36 387 389 393 _issjis1 37 401 _
108. _ Underscores 0 9Numbers Dollar signs Other characters terminate the name and are returned as the pathlist delimiter name is a pointer to the pathlist string length is a pointer to the location where os prsnam stores the length of the pathlist element delimiter is a pointer to the location where os prsnam stores the pathlist delimiter updated is a pointer to the location where os prsnam stores the pointer to the first character of name Note Several os prsnam calls are needed to process a pathlist with more than one name os prsnam terminates a name when it reaches a delimiter character Usually pathlists must be terminated with a null byte Attributes Operating System State Threads Re entrant Library os lib l See Also 03 crmprismi Ultra C Library Reference OS 9 and OS 9 for 68K User and System Safe Yes N n2 dv WX MICROWARE 724 Ultra C Library Reference os rdalst Copy System Alias List Syntax include lt io h gt finclude lt types h gt error_code _os_rdalst char buffer u int32 count Description _os_rdalst copies the system alias list to the caller s buffer At most count bytes are copied to the buffer Each alias entry is null terminated buffer is a pointer to the buffer into which to copy the alias list The number of total bytes to copy is passed at the location pointed to by count os rdalst also stores the
109. _os_intercept installs a signal intercept routine The intercept routine is entered asynchronously because a signal may be sent at any time similar to an interrupt The signal code is passed as a parameter to the intercept routine func is a pointer to the intercept routine s address data_ptr is a pointer to the intercept routine s global storage It usually contains the address of the program s data area os rte must be used to exit from the intercept routine func If the routine fails to use os rte at every possible exit unpredictable results occur Note The intercept routine should be short and fast such as setting a flag in the process data area Avoid complicated system calls such as I O In OS 9 for 68K data ptr must be glob data to provide compatibility between OS 9 for 68K and OS 9 signal and intercept use os intercept internally do notuse os intercept With either of these functions WX MICROWARE Each time the intercept routine is called the state of the processor such as its registers is pushed on to the user s stack Attributes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant Yes Library os lib l See Also intercept os rte os send signal ESIOpE OS 9 for 68K Technical Manual F ICPT OS 9 Technical Manual os ioconfig Configure an Element of Process System I O Syntax include lt modes h gt error
110. a minimum size determined by the global variable _memmins and satisfies the user requests from this memory space _memmins is initially set to 8192 ebrk grants memory requests from this memory space provided the requests are no larger than the amount of space If the request is larger than the available space ebrk wastes the rest of the space and tries to get enough memory from the system to satisfy the request This method works well for programs that need to get large amounts of not necessarily contiguous memory in little bits and cannot afford the overhead of malloc Changing the _memmins variable causes ebrk to use that value as the FSSRqMem for OS 9 for 68K or F_SRQMEM for OS 9 memory request size If the memory request is granted a pointer even byte aligned to the block is returned If the request is not granted 1 is returned and the appropriate error code is placed in the global variable errno Note The memory obtained from ebrk is not returned until the process terminates Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library Sys clib l See Also sbrk ibrki malloc os srqmem FSSRqMem OS 9 for 68K Technical Manual F SROMEM OS 9 Technical Manual WX MICROWARE endpwent Closes Password File Syntax include lt UNIX pwd h gt void endpwent Description endpwent Can be used to close a
111. actual number of bytes copied at the location pointed to by count Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os read Read Data from File or Device Syntax include modes h finclude lt types h gt error code os read path id path void xbuffer u_int32 xcount Description _os_read reads the number of bytes from the specified path The path must previously have been opened in read or update mode The data is returned exactly as read from the file or device without additional processing or editing such as backspace and line delete If not enough data is in the file to satisfy the read request fewer bytes are read than requested but an end of file error is not returned until the next os read service request returns an end of file error path specifies the path number buffer is a pointer to the caller s data buffer The number of bytes requested to be read is passed at the location pointed to by count os read also stores the number of bytes actually read at the location pointed to by count Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 See Also os readin ISRead OS 9 for 68K Technical Manual I READ OS 9 Technical Manual WX MICROWARE _os_readin Read Text Line with Editing Syntax include lt mod
112. any pushed back characters for the stream The external storage corresponding to the stream is unchanged c is the character to push back If c is EOF the operation fails and the input stream is unchanged stream is a pointer to the C I O FILE structure One character of pushback is guaranteed If unget c is called too many times on the same stream without an intervening read or file positioning operation on that stream the operation may fail A successful call to ungetc clears the end of file indicator for the stream The value of the file position indicator for the stream after reading or discarding all pushed back characters is the same as it was before the characters were pushed back For a text stream the value of the file position indicator after a successful call to ungetc is unspecified until all pushed back characters are read or discarded For a binary stream the file position indicator is decremented by each successful call to ungetc If the value was zero before a call it is indeterminate after the call ungetc returns the character pushed back after conversion If the conversion fails EOF is returned Attributes Operating System State Threads Re entrant Standards Library clib l See Also getc getchar fopen fseek fsetpos i rewind setbuf OS 9 and OS 9 for 68K User and System Safe No ANSI WX MICROWARE unlink Unlink Delete File Syntax inc
113. associated file to truncate beyond that point For More Information The sclib 1 and sclib il libraries contain a smaller version of the fwrite function Refer to the Using Ultra C C manual for more information about the small library functions Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also fread WX MICROWARE get name Read Value of SPR DCR PREG and TB Syntax finclude lt getset h gt include lt types h gt u_int32 _get_ lt name gt void Description The _get_ lt name gt class of functions can be used to read the value of Special Purpose Registers SPRs Device Control Registers DCRs Processor Registers PREGs and Time Based Registers TBs name is any of the names listed in the following table There is one exception to the following table the dec SPR on the 601 can be read from user state with the function get user dec Note All functions are provided It is the programmer s responsibility to avoid using system state only registers from user state and accessing registers that do not exist on the target processor All registers are accessible from system state Only those noted are available from user state Attempting to use system state registers from user state causes unpredictable results Table 2 12 get lt name gt Valid Names and Associated Processors
114. at Julian date time 52 53 122 507 at seconds 118 at specified time 54 506 735 at specified time intervals 52 54 124 509 to another process 57 758 to program 58 889 set alarm clock 57 745 cyclic alarm clock 56 738 event variable 53 55 213 589 591 593 597 process signal handler 53 364 679 relative event variable 53 55 215 595 signal intercept trap 56 sigmask 58 947 signal event occurrence 53 55 209 213 215 217 586 589 591 593 595 597 599 signal 58 950 specify signal handling 58 950 terminate use of semaphore data structure 57 unlink event 53 56 219 603 unmask signals 58 777 wait for all bits defined by mask to become clear 54 573 event to occur 53 54 56 221 575 576 577 578 601 604 606 relative event to occur 53 56 223 607 609 signal 58 869 interrupt descriptor table make entry 440 make_idesc 440 interrupt exception os rte 731 return from 731 interrupt level irg change 370 irq disable 371 irg enable 372 ABCDEFGHIJKLMNOPQRSTUVWXYZ irg maskget 373 irqg restore 374 irg save 375 mask 371 373 restore 374 return current 375 return to previous 373 set 370 unmask 372 interrupt manipulation _os firq 59 os irq 59 686 os rte 59 731 OS Sigreset 58 os9 irq 59 688 add device to fast IRQ table 59 add device to IRQ table 59 686 688 irg change 59 370 irg disable 59 371 irg enable 59 372 irq_maskget 59 373 irq restore 59 374 ir
115. be represented in fewer digits it is expanded with leading zeros The default precision is one The result of converting a zero value with a precision of zero is no characters p The parameter is a pointer to a void The pointer value is converted to a sequence of printable characters as an unsigned hexadecimal integer Table 2 9 fprintf Conversion Specifiers continued Flag Description s The parameter is a pointer to an array of character type Characters from the array are written up to but not including a terminating null character If the precision is specified no more than that many characters are written If the precision is not specified or is greater than the size of the array the array contains a null character A is written No parameter is converted The complete conversion specification is If a conversion specification is invalid the behavior is undefined If any parameter is or points to a union or an aggregate except for an array of character type using s conversion or a pointer using p conversion the behavior is undefined A non existent or small field width never truncates a field If the result of a conversion is wider than the field width the field expands to contain the conversion result fprintf returns the number of characters transmitted or a negative value if an output error occurred For More Information The sclib 1 and sclib il libraries contain a smaller
116. binding for this call performs conversions which allow compatibility with OS 9 If speed is a consideration see os9 getime Note _os_getime returns a date and time of zero with no error if no previous Call to os setime has been made A tick rate of zero indicates the clock is not running Attributes Operating System State Threads Re entrant Library os lib l See Also _os_setime _os9_getime FSTime F TIME OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE _os9_getime Get System Date Time code _os9_getime format time date day xticks Syntax include lt time h gt include lt types h gt Error u int32 u int32 u int32 u intic u int32 Description _os9_getime returns the current system date and time In the normal Gregorian format t ime is expressed as 00hhmmss and date as yyyymmdd The Julian format expresses t ime as seconds since midnight and date as the Julian day number format specifies the format of the returned date and time Table 2 19 os9 getime Format Values Format The Date and Time Are Returned In 0 Gregorian format 1 Julian format 2 Gregorian format with ticks 3 Julian format with ticks time is a pointer to the location where os9 getime stores the current system time date is a pointer to the location where os9 getime sto
117. buffer Description _gs_opt copies the options section of the path descriptor open on path into a buffer sgbuf provides a convenient means to access the individual option values sgbuf is declared in the sgstat h header file path is the path number of the open path descriptor buffer is a pointer to the buffer If the path is invalid 1 is returned and the appropriate error code is placed in the global variable errno Note Be sure the buffer is large enough to hold the options Declaring the buffer as type struct sgbuf is safe because this structure is predefined to be large enough for the options Note If you use gs opt on OS 9 you must use the OS 9 for 68K header file gs opt is provided on OS 9 solely for compatibility with OS 9 for 68K If the OS 9 for 68K header file is unavailable change the source code to use os gs popt Or os gs luopt Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also os gs popt 58 858 popti ISGetStt OS 9 for 68K Technical Manual I GETSTAT OS 9 Technical Manual SS PATHOPT OS 9 Technical Manual tmode Using OS 9 for 68K or Using OS 9 AN MICROWARE 9s pos Get Current File Position Syntax include sg codes h int gs pos int path Description gs pos returns the value of the file pointer for the file open on path path is the path num
118. by strerror with parameter errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library clib 1 See Also strerror WX MICROWARE pffinit Initialize for Float Output Obsolete Syntax int pffinit void Description pffinit was used on the 6809 C compiler to allow printf to perform float and double conversions A dummy function named pffinit exists here for 6809 68000 portability Note pffinit is historical and may be removed in a future release Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 pflinit Initialize for Longs Output Obsolete Syntax int pflinit void Description pflinit was used on the 6809 C compiler to allow printf to perform long int conversions A dummy function named pflinit exists here for 6809 68000 portability Note pflinit is historical and may be removed in a future release Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l WX MICROWARE pipe Create an Interprocess Communication Channel Syntax finclude UNIX os9def h int pipe unsigned int fd 2 Description pipe creates an I O mechanism called a pipe and returns 2 path numbers d 0 and d 1 Both paths are open for read an
119. bytes to copy If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also _os_get_moddir FSGModDr OS 9 for 68K Technical Manual WX MICROWARE getnextpwnam Get Next Password File Entry for Name Syntax include UN X pwd h struct passwd getnextpwnam char name Description getnextpwnam returns the next password file entry associated with name getnextpwnam returns NULL if no more password file entries are found for the name This function is useful for OS 9 systems where users have more than one password file entry Attributes Operating System OS 9 and OS 9 for 68K State Threads Re entrant Library unix l See Also endpwent fgetpwent getpwent getpwuid getpwnam setpwent User and System Safe No getopt Return Next Option Letter in String Syntax include UNIX os9def h extern char optarg extern int optind opterr int getopt Int argc char argv char optstring Description getopt returns the next option letter in argv that matches a letter in optstring optstring must contain the option letters the command using getopt recognizes If a letter is followed by a colon the option is expected to have an argument or a
120. cache line is not marked as invalid These specific operations may or may not be supported by a particular hardware configuration The Flush operation is considered the base operation and will be supported by most processors cct1 is a pointer to the location where os scache stores the cach cob e routine s address data is a pointer to the location where os scache stores the cache routine s static storage address addr is a pointer that specifies the address for the flush operation This parameter is used when the C ADDR bit of cont rol is set Set addr to 0 wh en C ADDRis not set size indicates the size of the target memory area to be flushed This parameter is used when the C ADDR bit of cont rol is set Set size to 0 wh en C ADDR is not set Any program that builds or changes executable code in memory should flush the instruction cache with os scache before executing new code This is necessary because the hardware instruction cache is not updated by data write accesses and may contain the unchanged WX MICROWARE instruction s For example if a subroutine builds a system call on its stack you must use the os scache system call to flush the instruction cache before executing the temporary instructions If the C GETCCTL bit of control is set os scache returns a pointer to the cache control routine in the cache extension module and a pointer to that rou
121. characters unless it exceeds a specified field width If it exceeds the field width it is the initial subsequence of that length in the sequence The first character if any after the input item remains unread If the length of the input item is zero the execution of the directive fails This condition is a matching failure unless an error prevented input from the stream If an error prevented input from the stream it is an input failure e Except in the case of a specifier the input item or in the case of a n directive the count of input characters is converted to a type appropriate to the conversion specifier If the input item is not a matching sequence the execution of the directive fails This condition is a matching failure Unless assignment suppression was indicated by an asterisk the conversion result is placed in the object pointed to by the first parameter following the format parameter that has not already received a conversion result If this object does not have an appropriate type or if the conversion result cannot be represented in the space provided the behavior is undefined If the end of file is reached during input conversion terminates If end of file occurs before any characters matching the current directive have been read other than leading white space where permitted execution of the current directive terminates with an input failure Otherwise unless execution of the current directive is terminated
122. const Get Current Constant Data Syntax include regs h void get const void Description get const returns the current constant data pointer Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library cpu l WX MICROWARE get current tss Get Current Task Segment Syntax include lt types h gt finclude lt regs h gt u int32 get current tss void Description get current tss returns the current task segment Note get current tss isonly supported on the 80x86 family of processors version of the compiler Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library Cou Mes V 1 seam Datacancs Ultra lorary Reference getenv Get Value for Environment Name Syntax include lt stdlib h gt char getenv const char name Description getenv searches the environment list for a string that matches the specified name name is a pointer to the name getenv returns a pointer to a string associated with the matched list member The string pointed to cannot be modified by the program If the specified name cannot be found a null pointer is returned For More Information The common set of environment names depends on the operating system Refer to your operating system s user manual for more information The environment list is implemented as a NULL termina
123. corresponding members in the mq attr structure referred to by attr If attr is non NULL but the calling process does not have the appropriate privilege on name mq open fails and returns an error without creating the message queue If O EXCL and O_CREAT are set mq open fails if the message queue name exists The check for the existence of the message queue and the creation of the message queue if it does not exist is atomic with respect to other processes executing mq open naming the same name with o EXCL and O_CREAT set If O EXCL is set and O_CREAT is not set the result is undefined The setting of this flag is associated with the open message queue description and determines whether a mq send Oormq receive shall wait for resources or messages that are not currently available or fail with errno set to EAGAIN See mq send and mq receive for details mq open does not add or remove messages from the queue Upon successful completion mq open returns a message queue descriptor Otherwise the function returns mqd t 1 and sets errno to indicate the error Errors EACCES EEXIST EINTR EINVAL EMFILE ENAMETOOLONG ENOENT ENOSPC ENOSYS I MICROWARE The message queue exists and the permissions specified by o 1ag are denied or the message queue does not exist and permission to create the message queue is denied O_CREAT and O0 EXCL are set and the
124. delete _os_ev_signal os ev wait _os9_ev_wait FSEvent OS 9 for 68K Technical Manual or F_EVENT OS 9 Technical Manual F_EVENT EV_CREAT OS 9 Technical Manual F_EVENT EV_SIGNL OS 9 Technical Manual os ev delete Delete Existing Event Syntax include lt events h gt finclude lt types h gt error code _os_ev_delete char name Description _os_ev_delete removes an event from the system event table freeing the entry for use by another event An event may not be deleted unless its use count is zero name is a pointer to the event s name string Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also oS ev creat FSEvent OS 9 for 68K Technical Manual F_EVENT OS 9 Technical Manual F_EVENT EV_DELET OS 9 Technical Manual F_EVENT EV_SIGNL OS 9 Technical Manual WX MICROWARE os ev info Return Event Information Syntax include events h finclude lt types h gt OS 9 for 68K error code os ev info event id ev id u int32 size ev infostr Buffer OS 9 error code os ev info event id ev id u int32 size void buffer Description os ev info returns event information in the caller s buffer The returned information is defined by the ev infostr event information structure defined in the event s h header file ev id specifies the eve
125. ev setand signals that an event has occurred The current event variable is ANDed with the value passed in mask Then the event queue is searched for the first process waiting for that event value ev id identifies the event value is a pointer to the location where os ev setand stores the event value prior to the logical operation mask is the event mask actv flag specifies which process es to activate e If actv_flag is one all processes in range are activated e If actv_flag is zero the first process in the event queue waiting for that range is activated Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MIC ROWARE See Also F EVENT OS 9 Technical Manual F EVENT EV SETAND OS 9 Technical Manual F EVENT EV SIGNL OS 9 Technical Manual os ev setor Set Event Variable and Signal Event Occurrence Syntax include lt events h gt finclude lt types h gt error_code _os_ev_setor event_id ev_id int32 value u int32 mask u int32 actv flag Description os ev setor signals that an event has occurred The current event variable is ORed with the value passed in mask Then the event queue is searched for the first process waiting for that event value ev id identifies the event value is a pointer to the location where os ev setor stores the event value prior to the logical operation mask
126. examine system global variable 77 649 execute new module 76 526 find process descriptor 77 623 fork process under control of debugger 77 565 567 569 get copy of process descriptor block 77 copy of process descriptor block table 647 file device status 77 648 process descriptor copy 77 320 651 process ID user ID 77 675 677 process table entry 76 322 getpid 76 318 getppid 319 insert process in active process queue 76 519 kill 76 413 list of functions 76 load and execute new module 155 OS 9 system call processing 78 617 OS 9000 system call processing 78 691 os9exec 78 617 os9fork 78 630 os9forkc 630 os9kexec 78 691 put calling process to sleep 78 782 784 return data for specified process memory map 77 672 send signal to process 76 413 set process priority 78 764 938 IJK LELC_MNOPQRSTUVW XYZ ABCDEFGHIJKLMNOPQRSTUVWXYZ setpr 78 938 sleep for specified interval 79 1062 sleep 78 start child process 77 start next process 78 712 suspend execution for specified time 78 process 78 831 system call processing 611 tsleep 79 1062 wait for process termination 78 79 854 1079 wait 79 1079 process table get process table 322 get entry 322 process times get 1052 process h 24 procid h 25 program exit 232 abnormal termination 114 diagnostics 132 end 232 233 exit 233 termination 136 program globals 12 class1 12 class2 13 protection hardware initialize 516 PST 84 put c
127. feof 47 241 ABCDEFGHIJKLMNOPQRSTUVWXYZ ferror 47 242 fflush 47 243 fgetc 47 245 fgets 47 248 fileno 249 fix file buffer 50 926 flush file s buffer 47 243 fopen 47 256 formatted output 47 50 51 260 880 962 fprintf 47 260 fputc 47 267 fputs 47 268 fread 47 269 freopen 47 276 fscanf 47 279 fwrite 47 290 get character 245 303 character from file 47 pointer to I O process descriptor 48 541 643 string from file 47 48 248 331 system I O device list head pointer 49 637 get character from file 47 get pointer to I O process descriptor 49 getc 47 303 getchar 303 gets 48 331 getw 48 339 initialize for float output 50 longs output 50 input string conversion 47 51 279 911 973 input strings conversion 50 list of 45 makdir 48 438 make new directory 49 704 mknod 48 459 mktemp 48 461 open ABCDEFGHIJKLMNOPQRSTUVWXYZ directory 48 501 file 47 48 256 498 path to file or device 49 713 open 48 498 opendir 48 501 output to file character 47 267 string 47 50 268 886 word 50 887 pffinit 50 872 pflinit 50 873 print to file 51 1073 1075 1077 standard output 51 string 51 printf 50 880 put next character 50 883 putc 50 883 putchar 883 puts 50 886 putw 50 887 read bytes from path 50 891 894 data from device 49 726 data from file 47 49 269 726 text line with editing 49 728 word from file 48 3
128. finclude lt process h gt int get process descq int pid int count pr desc buffer Description get process desc copies a process descriptor into the buffer for inspection pidis the process ID number of the desired process Only the lower 16 bits of pid are used count specifies the maximum number of bytes to copy buffer is a pointer to the buffer If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno The following is an example call procid pbuf _get_process_desc pid sizeof pbuf amp pbuf Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library sys_clib 1 See Also Q0OB8 Uprdsci FSGPrDsc OS 9 for 68K Technical Manual WX MICROWARE get process table Get Process Table Entry Syntax finclude lt process h gt int get process table void buffer int count Description _get_process_table copies the system s process descriptor table into the buffer for inspection A maximum of count bytes are copied The number of bytes actually copied is returned buffer is a pointer to the buffer count specifies the maximum number of bytes to copy If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys cl
129. for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 WX MICROWARE strcpy String Copy Syntax include lt string h gt char strcpy char dest const char 541 3G s Description strcpy copies a string including the terminating null character into an array If copying takes place between overlapping objects the behavior is undefined dest is a pointer to the destination array src is a pointer to the string to copy into dest strcpy returns the value of dest Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 strcspn Get String Length Syntax include lt string h gt size t strcspn const char Src const char delim Description strcspn returns the length of the segment of src up to the first occurrence of any character from delim src is a pointer to a source string delim is a pointer to a string of characters strcspn returns the length of the segment Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library Clap WX MICROWARE strerror Map Error Message String Syntax include lt string h gt char strerror int errnum Description strerror maps an error number to an error message string errnum specifies the error number st rerror ret
130. fticks is zero the process sleeps indefinitely fticks is one the process gives up a time slice but does not necessarily sleep for one tick os sleep stores the number of ticks left to sleep when awakened prematurely at the location pointed to by ticks If os sleep completes without interruption ticks contains the value 0 time may be specified in system clock ticks or if the high order bit is set the low 31 bits are considered a time in 256ths of a second signal is a pointer to the location where os sleep stores the last signal the process received Note os sleep cannot be used to time more accurately than 1 tick because it is not known when the os sleep request was made during the current tick Note The system clock must be running to perform a timed sleep The system clock is not required to perform an indefinite sleep or to give up a time slice Attributes Operating System State Threads Re entrant Library os lib l1 See Also os send oS wait Ultra C Library Reference OS 9 User and System Safe Yes 00 e WX MICROWARE os9 sleep Put Calling Process to Sleep Syntax include signal h finclude lt types h gt error code os9 sleep u int32 ticks Description _os9_sleep deactivates the calling process until the requested number of ticks have elapsed The requested number of ticks is passed at the location pointed
131. global static storage pointer for the function Note Use get static from cpu 1 to acquire your current static storage pointer Valid service request codes range from 0 to 255 The available service request codes are located in the funcs h file Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library os lib l WX MICROWARE _os9_setsvc Service Request Table Initialization Syntax include lt funcs h gt finclude lt types h gt error code _os9_setsvc void init tbl void params Description _os9_setsvc adds or replaces function requests in OS 9 for 68K s user and privileged system service request tables To install a system state only system call SYSTRAP is added to the function code number Otherwise both the system and user state dispatch tables are updated SYSTRAP is defined in the funcs h header file init tbl is a pointer to the initialization table The following is an example initialization table struct svc u_int16 func code service call function code number u intl16 offset difference between the address of the next table entry and the address of the routine svctbl F SERVICE u_int32 routine u int32 amp svctbl 1 F_SERVICE SYSTRAP u int32 sys routine u int32 amp svctbl 2 1 1 Valid service request codes range from 0 to 255 If the most significant bit of
132. group of arguments which must be separated from it by white space optarg is set to point to the start of the option argument on return from getopt getopt places in opt ind the argv index of the next argument to be processed opt ind is external and is initialized to 1 before the first call to getopt When all options have been processed up to the first non option argument getopt returns 1 The special option may be used to delimit the end of the options When it is encountered 1 is returned and is skipped getopt prints an error message on the standard error and returns a question mark when it encounters an option letter not included in optstring or no option argument after an option that expects one This error message may be disabled by setting opterr to 0 For example this code fragment shows how one might process the arguments for a command that can take the mutually exclusive options a and b and the option o which requires an option argument main argc int argc char argv rint c extern char optarg extern int opting argv while c getopt argc argv abo switch c case a if bflg errflgtt else aflagtt break case b if aflg errflgtt else bproc break case o ofile optarg break case errflgtt if errflg void fprintf stderr usage exit 2 for optind lt argc optind i
133. h fast IRQ table os irq Add or remove device from regs h IRQ table o89 irqt Add or remove device from regs h IRQ table 08 rfteli Return from interrupt signal h exception AN MICROWARE Mathematical Functions The following are the available mathematical functions Table 1 12 Mathematical Functions ANSI Header Function Standard Description File abs Integer absolute value stdlib h acos Arc cosine function math h asin Arc sine function math h atan Arc tangent function math h atan2 Arc tangent function math h ceil Ceiling function math h cos Cosine function math h cosh Hyperbolic cosine function math h div Compute quotient and stdlib h remainder exp Exponential function math h fabs Floating absolute value math h floor Floor function math h fmod Compute floating point math h remainder Table 1 12 Mathematical Functions continued Header Function Standard Description File frexp Return portions of floating math h point number hypot Euclidean distance function math h labs Compute absolute value stdlib ldexp Multiply float by exponent of 2 math h ldiv Compute quotient and stdlib remainder log Natural logarithm math h log10 Base ten logarithm math h modf Return parts of real number math h pow Power function math h rand Return random integer stdlib Sint Sine function math h sinh Hyperbolic sine functio
134. helpful for using the Ultra C library This information includes Using Functions and Macros Library Files Program Globals Header Files The C Library WX MICROWARE WX MIC ROWARE Using Functions and Macros Ultra C supports both functions and macros A function consists of compiled C statements Amacro is an identifier defined to represent a value or expression In most cases the differences between the two are transparent A WARNING Textual replacement in macro expansion can cause arguments of macros to be evaluated repeatedly Macro implementations of ANSI Standard Library functions are required to evaluate arguments exactly once and to have sufficient parentheses to avoid operator precedence trouble You can bypass the macro replacement when you compile This may be desirable when a large macro is used many times and the space saved by calling the function is outweighed by the extra time needed to call the function For example to override the replacement instantiation of the putc macro use putc c fp or fundef putc This results in a call to the putc function in the library rather than the replacement of the put c macro All American National Standards Institute ANSI macros have a library counterpart of the same name with the exception of the following assert setjmp va arg va end va start This is not true for non ANSI macros Library Files WX MICROWARE
135. include lt events h gt finclude lt types h gt error code os9 ev wait event id ev id int32 value int32 min val int32 max val Description os9 ev wait Waits for an event to occur It waits until an event call places the value in range between the minimum activation value and the maximum activation value Then the wait auto increment specified at creation is added to the event variable ev id specifies the event value is a pointer to the location where os9 ev wait stores the actual event value min val specifies the minimum activation value max val specifies the maximum activation value If a process in the event queue receives a signal it is activated even though the event has not actually occurred Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also FSEvent OS 9 for 68K Technical Manual os ev waitr Wait for Relative Event to Occur Syntax include lt events h gt finclude lt types h gt error_code _os_ev_waitr event_id ev_id int32 value signal code signal int32 min val int32 max val Description _os_ev_waitr waits for an event to occur It waits until an event call places the value in the range between the minimum and maximum activation values where the integers at locations min val and max val are relative to the current event value Then the wait auto increment specifie
136. information see Using OS 9 Threads Attributes Operating System State Threads Re entrant Library Sys clib l See Also open os create os makdir OS ss size I Create and I SetStt J CREATE and IT SETSTAT SS SIZE OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual OS 9 Technical Manual WX MICROWARE create Create File Syntax include modes h int create char name int mode int perm int initial size Description create returns a path number to the newly created file name is a pointer to the newly created file mode specifies the access modes for the file The modes h header file contains the valid mode values Only the lower 16 bits of mode are used perm specifies the file permission attributes The modes h header file contains the valid perm values Only the lower 16 bits of perm are used initial size may be used to indicate the file s initial allocation size For disk files the allocation is made even though the file size does not change For pipe files the pipe buffer is set to this value initial size may be used only if the FAM SIZE or S ISIZE bitis set in mode If the file already exists or any other error occurs 1 is returned and the appropriate error code is placed in the global variable errno Functions Note create is similar to the cre
137. input failure occurs before any conversion Otherwise sscanf returns the number of input items assigned This can be fewer than provided for or zero in the event of an early matching failure For More Information The sclib 1and sclib il libraries contain a smaller version of the sscanf function Refer to the Using Ultra C C manual for more information about the small library functions Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib l See Also scanf fscanf printrrt WX MICROWARE Ultra C Library Reference _ss_ dcoff Send Data Carrier Lost Signal to Process Syntax include lt scf h gt int _ss_dcoff int path int sigcode Description _ss_dcoff sends a signal to the calling process when the data carrier detect line associated with the device is lost path is the path number of the device sigcode is the signal code to send Only the lower 16 bits of sigcode are used on OS 9 for 68K If ss dcoff cannot register the signal 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also 0 amp 8 Ss dcorftri I SetStt OS 9 for 68K Technical Manual I SETSTAT SS DCOFF OS 9 Technical Manual WX MICROWARE
138. into which to write the generated output format is a pointer to a control string sprintf returns the number of characters written in the array not counting the terminating null character For More Information The sclib l and sclib il libraries contain a smaller version of the sprintf function Refer to the Using Ultra C C manual for more information about the small library functions Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also printf TPELNCE Ultra C Library Reference 963 AA MICROWARE sqrt Square Root Function Syntax include lt math h gt double sqrt double x Description sqrt returns the square root of x x must not be negative If the parameter is negative sqrt sets a domain error EDOM in errno and returns HUGE_VAL Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library claib l Possible Error EDOM srand Set Seed for Random Number Generator Syntax include lt stdlib h gt void srand unsigned int seed Description srand uses the parameter as a seed for a new sequence of pseudo random numbers to be returned by subsequent calls to rand lf srand is then called with the same seed value the sequence of pseudo random numbers is repeated If rand is called bef
139. is merely a placeholder until the process wide message queues are implemented The functions all return ENOSyS the POSIX error code that means not implemented The supported POSIX messaging functions are listed in Table 1 18 Table 1 18 POSIX Messaging Functions POSIX Function Standard Description Header File mq close Close a Message mqueue h Queue mag getattr E Get Message Queue mqueue h Attributes mq notify i Notify Process That a mqueue h Message is Available on a Queue mq notify wr Notify Process That a mqueue h ite Space in the Message Queue is Available mq open Open a Message mqueue h Queue Table 1 18 POSIX Messaging Functions continued Function POSIX Standard Description Header File mq receive mq send my SOCQUtUI mq unlink Receive a Message From a Message Queue Send a Message to a Message Queue Set Message Queue Attributes Remove a Message Queue mqueue h mqueue h mqueue h mqueue h Process Manipulation Functions AA MICROWARE The standard library provides functions for manipulating processes as identified in Table 1 19 ANSI prototypes for non ANSI functions are achieved by defining the macro name OP T_PROTOS during the compile Table 1 19 Process Manipulation Functions Function ANSI Standard Description Header File Chsaneih Ghairmi getpid get process desc get process table EXLLO 39589 allpay
140. is the same as expected for the subject sequence of strtoul The base parameter is 10 The corresponding parameter is a pointer to an unsigned integer Matches an optionally signed hexadecimal integer whose format is the same as expected for the subject sequence of st rtoul The base parameter is 16 The corresponding parameter is a pointer to an unsigned integer AN MICROWARE Table 2 10 fscanf Conversion Specifiers continued Flag Description Matches a non empty character sequence from a set of expected characters called the scanset The corresponding parameter is a pointer to the initial character of an array large enough to accept the sequence and a terminating null character The terminating null character is added automatically The conversion specifier includes all subsequent characters in the format string up to and including the matching right bracket 1 The characters between the brackets are the scanlist The scanlist is the scanset unless the character after the left bracket is a caret In this case the scanset contains all characters not appearing in the scanlist between the and the If the conversion specifier begins with or the is in the scanlist and the next right bracket character ends the specification Otherwise the first right bracket character ends the specification A hyphen has no special meaning itis matched like any other character oo Matches a single No conv
141. location pointed to by b1k_addr os9 translate is used when the external bus address must be passed to hardware devices such as DMA type controllers If the specified source block is nonlinear with respect to its destination mapping os9 translate returns the maximum number of bytes accessible at the translated address Note os9 translate is only available if colored memory is enabled Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os uacct User Accounting Syntax finclude lt process h gt finclude lt types h gt error code _os_uacct u int32 acct code pr desc proc desc Description os uacct provides a means for users to set up an accounting System os uacct is called by the kernel whenever it forks or exits a process This provides a mechanism for users to keep track of system operators To install a handler for this service request the os setsvc system call must be used to add the user s accounting routine to the system s service request dispatch table This is usually done in an 0S9P2 module You may perform your own system accounting by calling os uacct with a user defined acct code identifying the operation to perform For example when the kernel forks a process it identifies the operation by passing the F FORK code to the accounting routine acct code is the operation id
142. lt types h gt error code os protect void mem ptr u int32 size u int32 perm process id pig Description OS protect removes a process permission to access a block of memory Note Only super group users may use the os protect function mem ptr is a pointer to the beginning of the memory area to remove access permissions size specifies the size of memory perm specifies the permissions to remove Only the lower 16 bits of perm are used pid specifies the process identifier for the target process Note os protect only performs a useful function on MMU SSM systems On non MMU SSM systems os protect simply returns without preventing access to the memory block Attributes Operating System State Threads Re entrant Library os lib l See Also FSProtect F PROTECT OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE oS prsnam Parse Path Name Syntax include lt strings h gt finclude lt types h gt error_code _os_prsnam char name u_int32 length char delimiter char xupdated Description _os_prsnam parses a string for a valid pathlist element and returns its size This call parses one element in a pathlist not the entire pathlist A valid pathlist element may contain the following characters A ZUpper case letters Periods a zLower case letters
143. lt types h gt error code os chainm u int32 priority u int32 path cnt mh com mod head void params u int32 param size u int32 mem size Description oS chainm executes a new program without the overhead of creating a new process It is functionally similar to a Fork command followed by an Exit os chainm effectively resets the calling process program and data memory areas and begins executing a new primary module Open paths are not closed or otherwise affected os chainm is similar to os chain However it is passed a pointer to the module in memory to chain to instead of the module name priority is the priority of the process Only the lower 16 bits of priority are used path cnt is the number of I O paths to copy Only the lower 16 bits of path cnt are used mod head is a pointer to the module header params is a pointer to the parameter block param size specifies the size of the parameter block mem size specifies the additional memory size in bytes Note An error is returned only if there is not enough memory to hold the parameters If an error occurs during the chainn it is returned as an exit status to the parent of the process performing the chainm Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l1 See Also F CHAIN OS 9 Technical Manual F CHAINM OS 9 Technical Manual F EXIT OS 9 Technical Manual F FORK OS 9
144. lude types h error code os9 ioqueue process id proc id Description _os9_ioqueue links the calling process into the I O queue and performs an untimed sleep proc id specifies the process ID of the process currently in control of the device Attrib utes Operating System OS 9 for 68K State System Threads Safe Re en trant Yes Library os lib l See Also b8 findpdli os send os sleep os9 sleep F IOQu OS 9 for 68K Technical Manual WX MICROWARE os irq Add or Remove Device from IRQ Table Syntax finclude lt regs h gt finclude lt types h gt error code os irq u int32 vector u int32 priority void irq entry void statics Description os irq installs an IRQ service routine into the system polling table vector specifies the vector number Only the lower 16 bits of vector are used priority specifies the priority Only the lower 16 bits of priority are used e If priority is 0 the routine is polled first on the vector e fpriority is 1 the routine is polled first and no other device can have a priority of 1 on the vector If priority is 255 the routine is polled last on the vector irq_entry is a pointer to the IRQ service routine entry point If irq entry is 0 the call deletes the IRQ service routine statics is a pointer to the global static storage statics must be unique to the device A WARNING The called i
145. mbtowc Determine number of bytes in stdlib h multibyte characters wcstombs Convert sequence of wide stdlib h characters to multibyte characters wctomb Convert wide character to stdlib h multibyte character OS System Functions The standard library provides a large number of functions directly accessing system calls Functions available to provide access to selected system calls are identified in Table 1 17 ANSI prototypes for non ANSI functions are achieved by defining the macro name OPT_PROTOS during the compile Table 1 17 OS System Functions Function ud Description Header File _getsys Get system global variables setsys h _os_sysdbg Call system debugger process h _setsys Set examine system global setsys h variables _sysdbg Call system debugger process h WX MIC ROWARE POSIX Messaging Functions The OS 9 implementation of the POSIX specification supports a message queue that is either visible between process or between threads Currently only the threaded message queue is supported You distinguish which type you wish to create by the message queue name passed to mq open If the name starts with a then a process wide message queue is assumed Otherwise a threaded message queue is created There is a thread and non thread version of the POSIX message library At this time OS 9 does not support process wide message queues Therefore the non threaded version of the library
146. modlink modload modloadp _os_link os load o0s loadpt os unlink FSUnlink OS 9 for 68K Technical Manual F_UNLINK OS 9 Technical Manual munload Unload Module Syntax include lt module h gt int munload char name int typelang Description munload informs the system that the process no longer requires the module name which has a type language of typelang The module s link count is decremented The module is removed from memory when the link count reaches zero name is a pointer to the name of the module typelang specifies the type and language of the module If typelang is zero any module may be unloaded Only the lower 16 bits of typelang are used On error 1 is returned and the appropriate error code is placed in the global variable errno Note munload differs from munlink in that it unlinks by module name rather than module pointer Attempting to unlink a module by performing a link to a module by name to determine its address then unlinking it twice does not work because the first unlink removes the module from the process address space Attributes Operating System State Threads Re entrant Library Sys clib 1l1 See Also munlink os linki os load os unload FSUnLoad F_UNLOAD WX MICROWARE OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual offsetof
147. module dir makdir get process desc make module get process table mkdata module mktime mknod getpid mktemp getstat modcload _getsys modlink getuid modload getw modloadp Ultra C Library Reference _os_get_moddir _os_makdir 5Bn amp opr sci os mkmodule os get prtbl os datmod os getime _os9_getime os makdir 08 sg tmpnam _os_getstat _os_loadp _os_getsys os link 05 idi os load getc getw is replaced by performing two calls to getc Om loscp 105 1 106 Overview WX MICROWARE Table 1 37 sys_clib l Function Equivalents continued sys_clib Function Corresponding Function _gregorian munlink _gs_devn munload _gs_eof open 2gs gtdi opendir _gs_opt os9exec gs pos os9fork osSforkc t pe rly i _gs_size os9kexec hypot pause ibrk pause _os_gregorian 26s _ unlink _os_gs_devnm os unload os gs eof _os_open 6698 Igi _os_open peo am Popre Os exeo 08 9s posi 68 forki Oos gs ready OS gs size 08 execti none os prsnam malloc sleep Ultra C Library Reference Overview Table 1 37 sys clib Function Equivalents continued sys clib l Function Corresponding Function index SECAT PEEINIE none intercept _os_
148. module directory into your buffer for inspection buffer is a pointer to the buffer The maximum number of bytes to copy is passed at the location pointed to by count os get moddir also stores the actual number of bytes copied at the location pointed to by count Although the module directory contains pointers to each module in the system never access the modules directly Use os cpymem to copy portions of the system s address space for inspection Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also os cpymem os move WX MICROWARE os getpd Find Path Descriptor Syntax include lt io h gt finclude lt types h gt error code _os_getpd path_id path pd_com pa Description os getpd converts the path number to the absolute address of its path descriptor data structure path specifies the path number pd is a pointer to the location where os getpd stores the address of the path descriptor Attributes Operating System OS 9 and OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l See Also os9 allpd os9 retpd os get prtbl Get Copy of Process Descriptor Block Table Syntax finclude process h finclude lt types h gt error code os get prtbl void buffer u_int32 count Description os get prtbl copies the process descriptor b
149. msg prio The value of msg priois less than MQ PRIO MAX If the specified message queue is full and 0 NONBLOCK is not set in the message queue description associated with mqdes mq send blocks until space becomes available to enqueue the message or until mq send is interrupted by a signal If more than one thread is waiting to send when space becomes available in the message queue and the Process Scheduling option is supported then the thread of the highest priority that has been waiting the longest is unblocked to send its message Otherwise it is unspecified which waiting thread is unblocked If the specified message queue is full and 0 NONBLOCK is set in the message queue description associated with mqdes the message is not queued and mq send returns an error Upon successful completion mq send returns a value of 0 Otherwise no message is enqueued the function returns 1 and errno is set to indicate the error Errors EAGAIN EBADF EINTR EINVAL EMSGSIZE ENOSYS Attributes Operating System State Threads Re entrant Standards Library mq 1l See Also mq receive mg setattr The o NONBLOCK flag is set in the message queue description associated With mqdes and the specified message queue is full The mqdes argument is not a valid message queue descriptor open for writing A signal interrupted the call to mq send The value of msg prio was outside the va
150. not modify the string but it may be overwritten by a subsequent call to setlocale Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library elib l See Also atof atoi stel ftpraznttf i fscantfi isalnum isalpha Igor ispunct isspace isupper isxdigit _issjisl issjis2 isjis kana mblen mbstowcs mbtowc printtri scanf sprintf ssceantt vfprintf i vpraintf i rsprintfi wctomb wcstombs strtoog 0 Btrctoli strtoul BStrooll strftime strxfrm Ultra C Library Reference 937 AN MIC ROWARE setpr Set Process Priority Syntax finclude lt process h gt int setpr int pid int prior Description setpr sets the priority of a process The lowest priority is zero the highest is 65535 pidis the process ID prior specifies the priority Only the lower 16 bits of prior are used If an error occurs such as the process not having the same user ID as the caller 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1 setpwent Reset Password File Syntax include lt UNIX pwd h gt int setpwent void Description setpwent has the effect of rewinding the password file to allow for
151. notify will notify immediately if appropriate Message queue nonfull for mq notify write and message queue non empty for mq notify This extension provides message queue notification consistency with other OS 9 services such the send signal on data ready concept Upon successful completion mq setattr returns a value of 0 and the attributes of the message queue are changed as specified Otherwise the message queue attributes are unchanged and the function returns a value of 1 and sets errno to indicate the error Errors EBADF The mqdes argument is not a valid message queue descriptor ENOSYS mq setattr not supported Attributes Operating System OS 9 State User Threads Safe Re entrant No Standards POSIX Library mq l See Also mq open mq send WX MICROWARE mq unlink Remove a Message Queue Syntax finclude lt mqueue h gt int mq unlink const char name Description mq unlink removes the message queue named by the pathname name After a successful call to mq unlink with name a call to mq open with name fails if the flag O CREAT is not set in flags If one or more processes have the message queue open when mq unlink is called destruction of the message queue is postponed until all references to the message queue have been closed Calls to mq open to re create the message queue may fail until the message queue is actually removed However the mq u
152. of each array element compar is a pointer to a comparison function The contents of the array are sorted into ascending order according to compar compar is called with two parameters that point to the objects being compared compar returns an integer that is e Negative if the first parameter is less than the second Zero if the first parameter is equal to the second Positive if the first parameter is greater than the second If two elements compare as equal their order in the sorted array is unspecified qsort returns no value Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 raise Send Signal To Program Syntax include signal h int raise int sig Description raise sends a signal to the executing program sig specifies the signal to send raise returns zero if successful Otherwise it returns a non zero value Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 WX MIC ROWARE rand Return Random Integer Syntax include lt stdlib h gt int rand void Description rand computes a sequence of pseudo random integers in the range zero to RAND_MAX and returns a pseudo random integer rand uses the following algorithm static unsigned long int next 1 int rand void RAND MAX assumed
153. of resource lock s erik ft Create new resource lock lock h descriptor _os_ddlk Check for deadlock situation process h _os_dellk Delete existing lock descriptor lock h Overview WX MICROWARE Table 1 20 Resource Lock Functions continued ANSI Header Function Standard Description File os rellk Release ownership of resource lock h lock _os_waitlk Activate next process waiting to lock h acquire lock Searching and Sorting Functions Functions included for searching and sorting are identified in Table 1 21 Table 1 21 Search and Sort Functions ANSI Header Function Standard Description File bsearch Search array stdlib h qsort Quick sort stdlib h String Handling Functions The C language does not have a character string data type Instead it stores strings as character arrays and the standard library provides functions to manipulate them The functions are identified in Table 1 22 ANSI prototypes for non ANSI functions are achieved by defining the macro name OPT PROTOS during the compile Table 1 22 String Handling Functions ANSI Function Standard Description Header File findnstr Search string for pattern strings h findstr Search string for pattern strings h index Search for character in string strings h rindex Search for character in string strings h strcat String catenation string h strchr Locate string string h strcmp String comparison s
154. or device dup path is the path number of the path to duplicate new path is a pointer to the location where os dup stores the new path number for the same path os dup always uses the lowest available path number For example if you perform an os close on path 0 andan os dup on path 4 path 0 is returned as the new path number Therefore service requests using either the old or new path numbers operate on the same file or device Note It is usually not a good idea for more than one process to be performing I O on the same path concurrently Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes WX MICROWARE Library os lib l See Also I Dup OS 9 for 68K Technical Manual I DUP OS 9 Technical Manual os ev allceir Wait for All Bits Defined by Mask to Become Clear Syntax include lt events h gt finclude lt types h gt error code os ev allclr event id ev id int32 value signal code signal u int32 mask Description os ev allcir waits for an event to occur That is it waits until an os ev signal occurs that clears all of the bits corresponding to the set bits in the mask ev id identifies the event value is a pointer to the location where os ev allclr stores the actual event value signal is a pointer to the location where os ev allclr stores the signal code If the process receives a signa
155. os lib l1 os gs parity Calculate Parity of File Descriptor Syntax include lt rbf h gt finclude lt types h gt error_code _os_gs_parity path_id path fd_stats uXdbuft int32 parity Description OS gs parity uses a 32 bit vertical parity to validate file descriptor structures path specifies an open path to the file with which the file descriptor is associated fdbuf is a pointer to the file descriptor block parity is a pointer to the location where os gs parity stores the resulting parity Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os gs popt Read Path Descriptor Option Section Syntax include sg codes h finclude lt types h gt error code os gs popt path id path u int32 xsize void user opts Description OS gs popt copies the option section of the path descriptor into the variable sized area pointed to by user opt s You must include rbf h sbf h and or sc h for the corresponding file managers and declare size according to the size of the rbf_opts sbf_opts or scf opts path specifies the driver s path number The requested number of bytes is passed at the location pointed to by size os gs popt also stores the actual number of bytes copied at the location pointed to by size user opts is a pointer to your buffer Note On OS 9 for 68K 128 byte
156. outw writes a word to the I O address on the 80x86 or the memory address on all other processors data specifies the word to write Only the lower 16 bits are used address specifies the I O or memory address Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library cpu l See Also pute outl inci inl inw _parsepath Parse Disk File RBF Pathlist Syntax include lt strings h gt int _parsepath char string Description _parsepath parses a disk file RBF pathlist _parsepath is useful for programs that must determine the validity of a pathlist name without actually creating or opening a file string is a pointer to the pathlist to parse _parsepath returns the number of bytes in the valid pathlist If RBF does not accept the pathlist as valid parsepath returns 1 Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l1 See Also os prsnam FSPrsNam OS 9 for 68K Technical Manual F PRSNAM OS 9 Technical Manual WX MICROWARE 868 Ultra C Library Reference pause Wait for Signal Syntax include lt signal h gt int pause void Description pause Suspends a task until a signal is received pause always returns 1 unless the received signal caused the process to terminate In this case pause never returns Note The thread enabl
157. password file after processing is complete Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix l See Also fgetpwent getpw fgetpwent getpwnam getpwuid setpwent _errmsg Print Error Message Syntax include lt stdio h gt int _errmsg INE nerr char msg u int32 argl u_int32 arg2 u_int32 arg3 Description _errmsg displays an error message and the program name on the standard error path nerr specifies the error number returned by _errmsg msg is a pointer to the error message The message string is displayed in the following format prog lt message text gt prog is the module name of the program and lt message text gt is the string pointed to by msg For added flexibility in message printing msg can be a conversion string suitable for fprintf with up to three additional parameters of any integral type nerr is returned as the value of the function so _errmsg canbe used as a parameter to a function such as exit Of prerr WX MICROWARE Example Assume the program calling the function is named foobar Call errmsg 1 programmed message Wn Prints toobar programmed message Call exit errmsg errno unknown option c Xn q Prints foobar unknown option q Then exits with errno as its termination status Attributes Operating System OS 9 and OS 9 for 68K S
158. quotient 193 419 remainder 193 419 string length 1015 constant data change current pointer 158 control locale 935 process signal handling 947 convert _dtoa 194 alpha to floating 137 integer 138 long 139 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z numeric 140 unsigned 142 broken down time 129 broken down to calendar time 462 calendar to Greenwich Mean Time 341 local time 429 string format 189 character to lowercase 1056 1057 uppercase 1058 1059 date time to Gregorian value 342 Julian value 411 double to ASCII 194 input string 279 local to Greenwich Mean Time 1031 localtime 429 mbstowcs 448 mktime 462 sequence of multibyte characters 448 string to double 1017 long 1021 1024 wide to multibyte characters 1083 1085 convert characters carriage return to linefeed 188 linefeed to carriage return 422 copy os rdalst 725 contents of path descriptor 654 external memory 179 542 memory 454 old OS 9 strings 1008 string 1002 1012 system alias list 725 cos 60 177 cosh 60 178 cosine 177 arc 117 hyperbolic 178 ABCDEFGHIJKLMNOPQRSTUVWXYZ cpu 11 CRC OS crc 543 OS setcrc 759 calculate 181 check value 543 crc 181 generate 543 759 crc 68 104 181 CRCCON 543 creat 46 104 184 create data module 457 550 708 device alias 513 directory 438 459 704 event 579 file 184 186 547 hard link 808 module 441 module directory 706 path to new file 545 process 628 630 633 resource lock de
159. sg codes h int ss rest int path Description Ss rest causes an RBF device to restore the disk head to track zero It is usually used for disk formatting and error recovery path is the device s path number If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also OS ss reset I SetStt OS 9 for 68K Technical Manual I SETSTAT SS RESET OS 9 Technical Manual SS Size Set Current File Size Syntax include sg codes h int ss size int path int size Description Ss size changes the size of an open file This call is effective only on RBF devices The size change is immediate If the file size is decreased the freed sectors are returned to the system If the file size is increased sectors with undefined contents are added to the file path is the file s path number size specifies the new file size in bytes If the path is invalid or the device is not an RBF device 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also OS ss size I SetStt OS 9 for 68K Technical Manual I SETSTAT SS SIZE OS 9 Technical Manual WX MIC
160. size of unused stack area 272 system identification 833 memory 794 user ID 338 word from file 339 re validate module CRC 927 rewind 39 905 rewinddir 108 906 rindex 81 108 907 RTS line _os_ss dsrts 802 _os_ss enrts 803 Ss dsrts 977 Ss enrts 978 disable 802 977 enable 803 978 ABCDEFGHIJKLMNOPQRSTUVWXYZ S S IREAD 521 S IWRITE 521 sbf h 26 sbrk 64 108 909 scanf 50 911 scanlist 100 282 scanset 282 scfh 27 SCSI device OS gs dsize 660 get size of 660 search array 147 bit map for free area 751 for character in string 361 907 memory 452 string for pattern 250 252 SEEK END 285 SEEK SET 285 seekdir 108 913 select 914 semaphore initialize data structure for use 754 release 757 reserve 755 semaphore h 27 semaphores 57 send data carrier lost signal 975 present signal 976 signal after specified seconds 118 at Gregorian date time 120 504 at Julian date time 122 507 at specific time 124 127 506 509 512 735 on data ready 819 988 on DCD false 799 on DCD true 800 ABCDEFGHIJKLMNOPQRSTUVWXYZ to another process 758 to process 413 to program 889 system state subroutine 740 serial connection Os ss break 796 break 796 service request table initialization 766 768 set alarm clock 745 alternate working module directory 518 bits in bit map 514 buffer for I O stream 945 current file position 287 size 987 cyclic alarm clock 738 device path options 801 status 765 error
161. small library functions Attributes Operating System State Threads Re entrant Standards Library clib l See Also fwrite WX MICROWARE OS 9 and OS 9 for 68K User and System Safe No ANSI free Return Memory Syntax include lt stdlib h gt void free void ptr Description free deallocates the space pointed to by ptr If ptr is a null pointer no action occurs Otherwise if the parameter does not match a pointer previously returned by calloc malloc orrealloc or if the space has been deallocated by a call to free or realloc the behavior is undefined Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant no Standards ANSI Library clib l See Also ealloct malloc realloc WX MICROWARE freemem freemem Determine Size of Unused Stack Area Syntax include lt stdlib h gt int freemem void int freemem void Description freemem returns the number of bytes allocated for the stack that have not been used If compiler stack checking is enabled the stack is checked for possible overflow before entering a function The lowest address the stack pointer has reached is retained so freemem can report the number of bytes between the stack limit and the lowest stack value as the unused stack memory Note The program must be compiled with stack checking code in effect for fr
162. specifying any any module can be linked to regardless of the type and language attr rev is a pointer to the location where os link stores the attribute and revision level of the module Attributes Operating System State Threads Re entrant Library os lib al See Also os load _os_un _os_un FSLink F LINK link load WX MICROWARE OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual os linkm Link to Memory Module by Module Pointer Syntax include module h finclude lt types h gt error code os linkmQ mh com mod head void mod exec u_int16 type_lang u_intl6 attr rev Description os linkm causes OS 9 to link to the module specified by mod head mod headis a pointer to the module mod exec is a pointer to the location where os linkm stores the absolute address of the module s execution entry point attr rev is a pointer to the location where os linkm stores the attribute and revision level of the module Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l See Also 08 load os unlink o8 unloadt WX MICROWARE os load Load Module s from File Syntax include lt module h gt include lt modes h gt include lt memory h gt finclude lt types h gt error code _os_load char
163. srqmem 64 968 ABCDEFGHIJKLMNOPQRSTUVWXYZ srtmem 64 970 allocate colored memory 64 966 from arena 62 63 423 444 storage for array 62 151 416 task 63 516 allow access to 64 716 calloc 62 151 change size of block 898 check accessibility 532 compare 63 453 contract data area 707 copy 63 454 external memory 62 63 179 542 deallocate 271 process descriptor 63 559 determine size of unused stack area 62 272 ebrk 62 198 expand data area 707 extend data segment 64 909 fill 63 456 free 62 271 freemem 272 get externalmemory 62 198 ibrk 62 358 list of functions 62 low overhead 416 420 423 434 malloc 63 444 memchr 63 452 memcmp 63 453 memcpy 63 454 memmove 63 455 memset 63 456 move 63 455 prevent access to 64 720 realloc 64 898 request 792 request internal memory 62 358 resize block 62 64 434 898 dataarea 63 707 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z return 271 794 memory 62 420 return system 64 sbrk 64 909 search 63 452 set minimum allocation size 63 445 srqcmem 64 966 system request 64 790 968 return 64 970 translate address 64 846 memory map os9 gspump 672 return data for 672 memory h 20 memset 63 456 miscellaneous functions list of 65 mknod 48 105 459 mktemp 48 105 461 mktime 87 462 modcload 68 105 464 moddir h 20 modes h 21 modf 61 466 modlink 68 105 467 modioad 69 105 469 modloadp 69 105 471 modul
164. ss dcoff Set Signal to Be Sent when DCDL Goes False Syntax include lt scf h gt finclude lt types h gt error_code _os_ss_dcoff path_id path signal_code signal Description _os_ss_dcoff sets the signal code to be sent when the Data Carrier Detect line becomes false path specifies the path number signal is the signal code to send Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also 32558 558 ceon WX MICROWARE os ss dcon Set Signal to Be Sent when DCDL Goes True Syntax include lt scf h gt finclude lt types h gt error_code _os_ss_dcon path_id path signal_code signal Description _os_ss_dcon sets the signal code to be sent when the Data Carrier Detect line becomes true path specifies the path number signal is the signal code to send Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also 058 55 dOOFTEt os ss dopt Set Device Path Options Syntax include sg codes h finclude lt types h gt error code os ss dopt path id path u int32 size void dopts Description os ss dopt sets the initial default device path options dopt s These options initialize new paths to the device path specifies the path number size specifies the size of the options a
165. the association between the message queue descriptor mqdes and its message queue The results of using this descriptor after successful return from mq c1ose and until the return of this descriptor from a subsequent mq open are undefined If the process has successfully attached a notification request to the message queue via mqdes the attachment is removed and the message queue is available for another process to attach for notification Upon successful completion mq c10ose returns a value of 0 Otherwise the function returns 1 and sets errno to indicate the error Errors EBADF The mqdes argument is not a valid message queue descriptor ENOSYS mq close not supported Attributes Operating System OS 9 State User Threads Safe Re entrant No Standards POSIX Library mq 1 AN MICROWARE See Also mq open mq unlink 474 Ultra C Library Reference mq getattr Get Message Queue Attributes Syntax finclude mqueue h int mq getattr mqd t mqdes struct mq attr mgstat Description The mqdes argument specifies a message queue descriptor mq getattr gets status information and attributes of the message queue and the open message queue description associated with the message queue descriptor The results are returned in the mq attr structure referenced by the mgstat argument Upon return the following members shall have the values associated with the open message queue descri
166. the function code word is set only the system table is updated Otherwise both the system and user tables are updated params is intended to be a pointer to the global static storage This allows you to associate a global data pointer with each installed system call When the system call is used the data pointer is automatically passed Whatever params points to is passed to the system call params may be a pointer to anything Note The OS 9 for 68K service request codes are located in MWOS OS9 SRC DEFS Attributes Operating System OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l1 WX MICROWARE os setsys Set System Global Variables Syntax include lt sysglob h gt finclude lt types h gt error_code _os_setsys u_int32 offset u_int32 size glob_buff sysvar Description _os_setsys changes a system global variable These variables havead prefix and are located in the system library sysglob h Consult the files in the DEFS directory for a description of the system global variables Only super users may change system variables Super users must be extremely careful when changing system global variables of fset is the offset to the system global variables size specifies the size of the target variable sysvar is the new value for the system global variable For More Information Refer to your operating system technical manual for the system global vari
167. to store the code mbchar is a pointer to a multibyte character If mochar is a null pointer motowc returns a non zero value if multibyte character encodings have state dependent encodings or returns a zero value If mbchar is not a null pointer motowc either returns Oifmbchar is a pointer to the null character The number of bytes contained in the converted multibyte character if the next maxnum or fewer bytes form a valid multibyte character e 1 if they do not form a valid multibyte character maxnum Specifies the maximum number of bytes to examine The returned value is never greater than maxnum or MB CUR MAX mbtowcs is supported for both the c and JAPAN locales Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 See Also wctomb WX MICROWARE memchr Memory Search Syntax include lt string h gt void memchr const void mem area int Chr size t size Description memchr locates the first occurrence of chr converted to an unsigned char in the initial size characters each interpreted as unsigned char Of mem_area mem_area is a pointer to the memory to search chr is the character for which to search size is the size of the memory area to search memchr returns a pointer to the located character or a null pointer if the character does not occur in the object Attributes
168. units of system clock ticks refer to CLOCKS PER SEC in the time h header file The minimum time interval allowed is two system clock ticks If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno If errors do not occur alm cycle returns the alarm ID Functions For More Information Refer to your operating system technical manual for information about alarms Attributes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant Yes Library Sys clib l See Also alm delete alm set alm cycle alm delete oS alarm set D Ultra C Library Reference 1 c1 IN n ww b E ka WX MICROWARE alm delete Remove Pending Alarm Request Syntax include lt alarm h gt int alm delete int alarmid Description alm delete cancels the specified alarm request alarmid is the alarm ID of the alarm to cancel If alarmid is zero all pending alarm requests are cancelled If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno If errors do not occur alm delete returns zero For More Information Refer to your operating system technical manual for information about alarms Attributes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant Yes Library Sys clib 1l1 See Also oS alarm delete
169. version of the fprintf function Refer to the Using Ultra C C manual for more information about the small library functions Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI ye o Library clib l See Also printfi sprintti WX MICROWARE Ultra C Library Reference fputc Output Character to File Syntax include lt stdio h gt int fputc int chr FILE stream Description fputc converts a character to an unsigned char It writes the character to the output stream at the position indicated by the associated file position indicator for the stream if defined and advances the indicator appropriately If the file cannot support positioning requests or if the stream was opened with append mode the character is appended to the output stream chr is the character to convert stream is a pointer to the C I O FILE structure fputc returns the character written If a write error occurs the error indicator for the stream is set and fputc returns EOF Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also fgetc WX MICROWARE fputs Output String to File Syntax include lt stdio h gt int fputs const char Str FILE stream Description fputs writes a string to a stream The terminating nu
170. xq function must not be compiled with stackcheck because the stack is out of range at this time For More Information Refer to the OS 9 Technical l O Manual for more information Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library os lib l See Also F IRQ OS 9 Technical Manual Ultra C Library Reference 687 WX MIC ROWARE _os9_irq Add or Remove Device from IRQ Table Syntax finclude lt regs h gt finclude lt types h gt error code os9 irq u int32 vector u int32 priority void irq entry void statics void port Description _os9_irq installs an IRQ service routine into the system polling table vector specifies the vector number Only the lower 16 bits of vector are used priority specifies the priority Only the lower 16 bits of priority are used e If priority is 0 the routine is polled first on the vector fpriority is 255 the routine is polled last on the vector irq_entry is apointer to the IRQ service routine entry point If irq entry is 0 the call deletes the IRQ service routine statics is a pointer to the global static storage statics must be unique to the device port is the port address For More Information Refer to the OS 9 for 68K Technical I O Manual for more information Attributes Operating System State Threads Re entrant Library os lib l See Also FSIRQ OS 9 for
171. you can no longer use it without an intervening call to va start If there is no corresponding call to va start orif va end is not called before the return the behavior is undefined va end returns no value Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib l See Also va starci WX MICROWARE va start Initialize Variable Parameter List Syntax include stdarg h void va start va list ap parmN Description va start is a macro associated with the stdarg h header file stdarg h provides a method for stepping through a list of function parameters whose length and type are unknown ap is an object representing the next unnamed parameter parmN identifies the right most parameter in the variable parameter list in the function definition the parameter just before the If parmN is declared with one of the following types the behavior is undefined The register storage class e A function type Anarray type e Atype that is not compatible with the type that results after applying the default parameter promotions For example char short and float va start returns no value Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 vfprintf Print to File Syntax include lt stdarg h gt
172. your operating system technical manual for detailed information Error messages are generally in the form WX MIC ROWARE lt major gt lt minor gt detail ma jor is the family of error minor is the error number within the family detail is the information from the system errmsg file if available The local time zone and Daylight Savings Time 4 12 1 The local time zone and Daylight Savings Time are determined by the Tz environment variable on OS 9 for 68K and the Tz variable or the m tmzone field in the init module on OS 9 Failing to find user defined values the defaults are Central Standard Time and Central Daylight Time e The era for the clock function 4 12 2 1 The era for clock is the elapsed ticks since the program was forked Equivalents for the sys clib l Functions The functions in the sys clib 1 library exist mainly for compatibility with the Microware K amp R C compiler although the calls are accepted in all modes Whenever possible you should use the functions in the os lib landclib 1 libraries that have the same functionality The following is a list of the sys c1ib 1 functions and the corresponding calls in either os 1ib 10rclib l Table 1 37 sys clib l Function Equivalents sys clib Function Corresponding Function access _os_open create 05 Ccreateil alm atdate os alarm atime o0s9 alarm atdate detach os detach Overview Table 1
173. 20 alm_atjul 52 103 122 ABCDEFGHIJKLMNOPQRSTUVWXYZ alm cycle 52 103 124 alm delete 52 103 126 alm set 52 103 127 alpha to floating conversion 137 to integer conversion 138 to long conversion 139 to numeric translation 140 alphanumeric 376 append mode file position indicator 99 arc cosine 117 sine 131 tangent 134 135 array allocate storage 151 search 147 asctime 87 129 asin 60 131 assert 65 91 132 asserth 14 AST 84 atan 60 134 atan2 60 135 atexit 35 136 atof 37 137 atoi 138 atoi 37 atol 37 139 aton 140 aton h 15 attach device 143 521 path to file pointer 239 attach 45 103 143 base ten logarithm 431 bcmp 145 ABCDEFGHIJKLMNOPQRSTUVWXYZ bcopy 146 binary file create temporary 1053 tmpfile 1053 bit index find ffs 244 bit map _os9_allbit 514 Oos9 delbit 554 OS9 schbit 751 deallocate 554 flush cached information 807 search for free area 751 set bits 514 break serial connection 796 string into tokens 1019 broken down time convert to calendar time 462 string format 129 structure 1031 bsearch 80 147 buildpath 149 bypass macro replacement 8 bzero 150 cache control 523 747 status _os_ gs cstats 655 get information 655 cache h 15 calculate module CRC 181 parity of file descriptor 669 calendar time 341 call register function 136 ABCDEFGHIJKLMNOPQRSTUVWXYZ subroutine module 1029 system debugger 832 1036 calloc 62
174. 3 pass stdin stdout and stderr angblk 0 pointer to module name argblk the argument list environ environment list for new process 0 no extra memory amp pid pointer to the process ID type lang 0 normal child process SUCCESS printf can t fork s n argblk 0 else wait 0 Ultra C Library Re os link Link to Memory Module Syntax include module h finclude lt types h gt error code os link char mod name mh com mod head void mod exec u_int16 type_lang u_intl6 attr rev Description os link searches the current module directory and an alternate module directory in OS 9 for a module whose name type and language match the parameters The module name is passed at the location pointed to by mod name On OS 9 if mod name is an explicit module directory pathlist for example usr persi prog os link also stores the pointer to the module that was successfully linked for example prog at the location pointed to by mod name mod headis a pointer to the location where os link stores the address of the module s header mod exec is a pointer to the location where os link stores the absolute address of the module s execution entry point The type and language of the module are passed at the location pointed to by type lang os link also stores the actual type and language at the location pointed to by type_lang If type_lang is zero
175. 3 parse name 722 segment 882 read bytes from 891 894 read 891 readin 894 set options 981 translate user to system 843 valid access modes 239 write bytes to 1087 1089 ABCDEFGHIJKLMNOPQRSTUVWXYZ write 1087 writeln 1089 path descriptor os getpd 646 os gs cpypd 654 Os gs popt 670 OS ss popt 813 copy contents of 654 find 646 read option section 670 write option section 813 pattern search string for 250 252 pause 58 106 869 PDT 84 perror 67 100 871 pffinit 50 107 872 pflinit 50 107 873 pipe 874 place diagnostics in programs 132 formatted time in buffer 1005 1006 position file pointer 436 pow 61 876 power function 876 PowerPC specific functions list of 90 prerr 67 107 877 print errormessage 201 718 877 to file 1073 1075 1077 printf 50 880 priority set for process 938 setpr 938 process os aproc 519 _os clrsigs 536 os exit 621 os fork 628 os forkm 633 ABCDEFGHIJKLMNOPQRSTUVWXYZ OS ioexit 683 Os iofork 684 os nproc 712 OS setpr 764 Os sigrs 781 Os sleep 782 Os suspend 831 Os wait 854 _os9_aproc 520 _os9 gspump 672 OS9 sleep 784 clear signal queue 536 create 628 630 633 end 621 insert in active process queue 519 520 intercept 364 kill 413 os9fork 630 os9forkc 630 puttosleep 782 784 resize current signal queue block 781 return data for memory map 672 send signal to 413 set priority 764 938 set up O 684 si
176. 31 atan 60 134 atan2 60 135 base ten logarithm 61 431 ceil 60 154 ceiling function 60 154 compute absolute value 61 415 floating point remainder 60 255 quotient and remainder 60 61 193 419 cos 60 177 cosh 60 178 cosine 60 177 arc 60 117 hyperbolic 60 178 div 60 193 Euclidean distance function 61 357 exp 60 235 exponential function 60 235 fabs 60 236 floating absolute value 60 236 floor function 60 254 floor 60 254 fmod 60 255 frexp 61 278 ABCDEFGHIJKLMNOPQRSTUVWXYZ hyperbolic cosine 60 178 sine 61 959 tangent 61 1040 hypot 61 357 integer absolute value 60 115 labs 61 415 Idexp 61 418 Idiv 61 419 list of 60 log 61 430 log10 61 431 modf 61 466 multiply float by exponent of 2 61 418 natural logarithm 61 430 pow 61 876 power function 61 876 rand 61 890 return parts of real number 61 466 portions of floating point number 61 278 random integer 61 890 set seed for random number generator 61 965 sin 61 958 sine 61 958 arc 60 131 hyperbolic 61 959 sinh 61 959 sqrt 61 964 square root 61 964 srand 61 965 tan 61 1039 tangent 61 1039 arc 134 135 hyperbolic 61 1040 tanh 61 1040 mblen 72 446 mbstowcs 448 mbstowsc 72 mbtowc 72 450 MDT 84 ABCDEFGHIJKLMNOPQRSTUVWXYZ MEM ANY 442 464 966 MEM SYS 442 464 966 memchr 63 452 memcmp 63 453 memcpy 63 454 memmove 63 455 memory _mkdata_
177. 32 max val Description os9 ev waitr Waits for an event to occur It waits until an event call places the value in the range between the minimum and maximum activation values where min val and max val are relative to the current event value Then the wait auto increment specified at creation is added to the event variable ev id specifies the event value is a pointer to the location where os9 ev waitr stores the actual event value The minimum relative activation value is passed at the location pointed to by min val min val is also a pointer to the location where os9 ev waitr stores the minimum absolute value The maximum relative activation value is passed at the location pointed to by max val max val is also the pointer to the location where os9 ev waitr stores the maximum absolute value The event value is added to min val and max val respectively and the actual values are returned to the caller If an underflow or overflow occurs on the addition the values 80000000 minimum integer and S7fffffff maximum integer are used respectively Attributes Operating System State Threads Re entrant Library os lib l See Also 0S9 ev wait FSEvent WX MICROWARE OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual os exec Start Child Process Syntax finclude process h include dexec h gt used when os dfork os9 dfork or os dforkm is
178. 39 read 50 891 readin 50 894 remove device from system 49 560 file 50 903 remove 50 903 rename file 50 rename 50 re open file 47 276 scanf 50 911 set up buffer for I O stream 51 945 I O for new process 49 684 setbuf 50 926 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z setvbuf 51 945 sprintf 51 962 sscanf 51 973 terminate I O for exiting process 49 683 tmpfile 51 1053 unget character 51 1064 ungetc 51 1064 unlink file 51 1066 1067 unlink 51 1066 unlinkx 51 1067 vfprintf 51 1073 vprintf 51 1075 vsprintf 51 1077 write bytes topath 51 1087 1089 data to device 50 859 data to file 47 50 290 859 line of text with editing 50 861 write 51 1087 writeln 51 1089 I O interface edition number Os gs edt 661 get 661 I O module os iodel 682 check for use of 682 I O process descriptor os copy ioproc 541 os get ioproc 643 get pointer to 541 643 I O queue os9 ioqueue 685 enter 685 I O stream set buffer for 945 setvbuf 945 ibrk 62 106 358 inc 45 360 index 81 107 361 indicate event occurrence 209 213 215 217 593 initialize ABCDEFGHIJKLMNOPQRSTUVWXYZ directory 704 for float output 872 for longs output 873 process descriptor 516 517 resource lock descriptor 549 service request table 768 static storage 678 variable parameter list 1072 inl 45 363 input failures defined 282 read from stream 279 string conversion 279 911
179. 547 Ss attr 971 Ss size 987 affect of opening multiple times 100 attach path to file pointer 239 change access permissions 162 attributes 971 ABCDEFGHIJKLMNOPQRSTUVWXYZ name 815 904 owner 164 size 987 chmod 162 chown 164 close 237 close path 535 creat 184 create 184 186 545 547 temporary binary file 1053 unique name 461 create 186 delete 555 903 1066 1067 determine accessibility 116 path number 249 size 355 fclose 237 fdopen 239 fflush 243 fgetc 245 fgetpos 246 fgets 248 fileno 249 fix buffer 926 flush buffer 243 fopen 256 fputc 267 fputs 268 fread 269 freopen 276 fseek 285 fsetpos 287 ftell 289 fwrite 290 generate uniquename 1054 get character from file 245 current position 246 352 671 current size 355 file descriptor block address 664 ABCDEFGHIJKLMNOPQRSTUVWXYZ status 332 648 string from 248 331 gets 331 getstat 332 getw 339 load module from 700 Iseek 436 make hard link to 808 mktemp 461 open 256 498 713 open 498 output character to 267 string to 268 886 word to 887 position pointer 436 print to 1073 1075 1077 read characters from 331 datafrom 269 726 word 339 remove 903 remove 903 rename 815 904 rename 904 re open 276 report pointer position 289 reposition pointer 285 return current size 674 path number 184 186 pointer to zero 905 rewind 905 set attributes 795 971 current position 287 current size 9
180. 627 get alternate pathlist 644 copy of 645 current pathlist 644 entry 313 module manipulation get module dir 68 313 mkdata module 68 457 os altmdir 69 518 os chainm 69 528 os chmdir 69 534 os cmdperm 69 537 os crc 69 543 os datmod 69 550 os delmdir 69 558 ABCDEFGHIJKLMNOPQRSTUVWXYZ os fmod 69 627 os get mdp 70 644 os get moddir 70 645 os initdata 70 678 os link 70 697 os linkm 70 699 os load 70 700 os loadp 70 702 _os_makmdir 70 706 os modaddr 70 710 OS setcrc 70 759 _os_slink 70 786 os slinkm 71 788 _os tlink 71 840 os tlinkm 71 842 os unlink 71 849 os unload 71 850 os vmodul 71 851 _os9 vmodul 71 852 _setcrc 71 927 subcall 71 1029 calculate module CRC 68 181 call subroutine module 71 1029 change permissions of module directory 69 537 process current module directory 69 534 crc 68 181 create data memory module 68 457 data module 69 550 module 68 441 new module directory 70 706 delete existing module directory 69 558 execute new primary module 69 528 find module directory entry 69 627 module given pointer 70 710 generate CRC 69 70 543 759 get copy of module directory 70 645 current and alternate module directory pathlists 70 644 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z module directory entry 68 313 initialize static storage from module 70 678 install system state trap handling module 71 840 user subr
181. 640 _os9 setime 88 762 _sysdate 88 asctime 87 129 broken down convert to calendar 462 clock 87 171 convert broken down to calendar 87 462 string format 87 129 calendar to Greenwich Mean Time 87 341 local 87 429 string format 87 189 date time to Gregorian value 87 342 date time to Julian value 87 julian date and time 411 local to Greenwich Mean Time 88 1031 ctime 87 189 difftime 87 192 find temporal difference 87 192 get 640 1051 calendar time 88 current 88 Gregorian date 88 652 Julian date 88 690 processor time 87 171 system date time 87 638 system time 87 312 getime 87 312 gmtime 87 341 ABCDEFGHIJKLMNOPQRSTUVWXYZ list of 87 localtime 87 429 mktime 87 462 set 88 760 762 932 setime 88 932 sys mktime 88 1031 time 88 1051 time zones 84 defaults 102 time 88 1051 time h 33 34 times 1052 tmpfile 51 1053 tmpnam 67 1054 toascii 1055 tolower 38 1057 toupper 38 1059 tputs 83 1060 track OS ss wtrack 825 Ss wtrk 992 format 825 write 825 992 transform string 1027 translate character 1055 memory address 846 user to system path 843 trap handler _os_strap 827 OS tlink 840 _os_tlinkm 842 OS9 strap 829 install system state module 840 install user module 842 set for error 827 829 tsleep 79 109 1062 TZ 84 102 ABCDEFGHIJKLMNOPQRSTUVWXYZ un h 34 unget character 1064 ungetc 51 1064 unlink event 219 603 file 1066
182. 68K System Safe Yes OS 9 for 68K Technical Manual WX MICROWARE os julian Get Julian Date Syntax include lt time h gt finclude lt types h gt error code os julian u int32 time u int32 date Description os julian converts Gregorian dates to Julian dates time is a pointer to the location where the time in the form 00hhmmss is passed os julian stores the time in seconds since midnight in the location pointed to by time date is a pointer to the location where the date in the form yyyymmdd is passed os julian stores the Julian date in the location pointed to by date For More Information Refer to your operating system technical manual for more information Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l os9kexec OS 9 Create Process Syntax finclude lt types h gt int os9kexec u int32 func u intl6 priority u intl6 pathont u char modname u char argv u char envp u int32 datasize void extral void extra2 void extra3 void extra4 Description os9kexec is a high level fork chain interface that prepares the parameter and environment list before a process is created os9kexec closely resembles the UNIX execve system call func is a pointer to one of the following functions that create a new process os fork os forkm os chain
183. 78 Ss lock 44 107 979 Ss opt 44 107 981 Ss pfd 44 107 983 Ss rel 44 108 985 Ss rest 44 108 986 Ss size 44 108 987 Ss ssig 44 108 988 Ss tiks 44 108 990 Ss wtrk 44 108 992 Stacksiz 67 994 Strass 67 108 997 ABCDEFGHIJKLMNOPQRSTUVWXYZ subcall 71 1029 Sysdate 88 109 1033 1034 1035 sysdbg 73 109 1036 _toascii 38 1055 _tolower 38 1056 _toupper 38 1058 Numerics 80x86 specific functions get current task segment 89 306 global descriptor pointer 89 311 get_current_tss 89 306 get_excpt_base 89 310 get gdtr 89 311 list of 89 make global descriptor table entry 89 439 interrupt descriptor table entry 89 440 make_gdesc 89 439 make_idesc 89 440 return exception table base address 89 310 set exception table base address 89 929 global descriptor pointer 89 930 set_excpt_base 89 929 set_gdtr 89 930 abort 35 101 114 abnormal program termination 114 abs 60 115 absolute value abs 115 compute 415 fabs 236 floating 236 labs 415 ABCDEFGHIJKLMNOPQRSTUVWXYZ return 415 access permissions change for module directory 537 access 102 116 accounting 848 acos 60 117 acquire ownership of resource lock 502 conditional 525 activate next process waiting to acquire lock 857 active process queue Os aproc 519 os9 aproc 520 insert process 519 520 add device to IRQ table 686 688 add filename to root directo
184. 87 size 820 status 765 940 setbuf 926 setstat 940 ABCDEFGHIJKLMNOPQRSTUVWXYZ tmpfile 1053 tmpnam 1054 unlink 1066 1067 unlink 1066 unlinkx 1067 valid access modes 239 256 vfprintf 1073 vprintf 1075 vsprintf 1077 write data 290 859 string to 268 unwritten data 243 file descriptor gs gfd 348 Os gs fd 663 Os gs fdaddr 664 Os gs fdinf 665 OS gs parity 669 os ss fd 805 _os9_ gs cdfd 653 Ss pfd 983 calculate parity 669 get block address 664 get sector 348 665 put sector 983 read sector 663 return 653 write sector 805 file names composing valid 99 file pointer report position 289 reposition 285 436 logical 753 return to zero 905 file positioning functions OS seek 39 753 fgetpos 38 246 fseek 38 285 fsetpos 38 287 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z ftell 38 289 get current position in file 38 246 list of 38 report file pointer position 38 289 reposition file pointer 38 285 logical file pointer 39 753 return file pointer to zero 39 905 rewind 39 905 set current file position 38 287 fileno 249 fill memory 456 find fixed block of memory 624 module 710 module directory entry 627 path descriptor 646 process descriptor 623 temporal difference 192 terminal name isatty 382 find first set bit ffs 244 findnstr 81 104 250 findstr 81 104 252 fix file buffer 926 float h 17 floating absolute value 236 floor function 254 floor 60 254 flush
185. 8K Technical Manual F STRAP OS 9 Technical Manual os9 strap Set Error Trap Handler Syntax include lt settrap h gt finclude lt regs h gt finclude lt types h gt error_code _os9_strap u_int32 excpt stack os9strap init tbl Description os9 strap enables user programs to catch process local program exceptions such as illegal instructions and divide by zeroes excpt stack Is a pointer to the stack to use if an exception occurs If excpt stack is zero os9 strap uses the current stack init tbl is a pointer to the service request initialization table The first field of the init tb1 should be the vector OF FSET of the exception vector on which to install the handler The second field is the OFFSET from the next entry in init_tb1 to the exception handling function for this vector init t1 may look like the following void ovferror void chkerror extern void os9 init tbl os9strap init tbl os9strap os9 init tbl asm os9strap init tbl dc w 0 ovferror 4 T TRAPV 2 asm dc w 0 chkerror 4 T CHK lt lt 2 asm dc w 1 1 WX MICROWARE Note To access the contents of the initialization table os9strap init tbl in this example you must define os9 init tblasifitwerea function For example os9strap os9 init tbl would not generate PC relative references while extern void os9 init tb1 forces the compiler to generate references into the code area
186. 9 module If the header values are valid the module is entered into the module directory and a pointer to the directory entry is returned The current module directory is searched for another module with the same name If a module with the same name and type exists the module with the highest revision level is retained in the module directory Ties are broken in favor of the established module mod group Specifies the beginning of the module group ID size is the size of the module mod_head is a pointer to the module dir entry is a pointer to the location where os9 vmodul stores the pointer to the directory entry Attributes Operating System OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l1 See Also DE nre os load Ultra C Library Reference 853 WX MICROWARE os wait Wait for Child Process to Terminate Syntax finclude lt process h gt finclude lt types h gt error code os wait process id child_id status code status Description os wait deactivates the calling process until a child process terminates by executing an os exit system call or is otherwise terminated The child s ID number and exit status are returned to the parent If the child process died due to a signal status contains the signal code child idis a pointer to the location where os wait stores the process ID of the terminating child status is a pointer to the location where o
187. Cosine Function Syntax include lt math h gt double cosh double x Description cosh returns the hyperbolic cosine of x The value of x is in radians If the magnitude of x is too large a range error ERANGE placed in errno occurs and the properly signed HUGE_VAL is returned Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clin Possible Error ERANGE _cpymem Copy External Memory Syntax finclude lt process h gt int _cpymem int pid int count void from void into Description cpymem copies memory owned by another process or the system into a buffer pid is the process ID number of the external process If pid is zero the system s address space is assumed Only the lower 16 bits of pid are used count is the number of bytes to copy from is a pointer to the address in the process address space from which to copy into is a pointer to the buffer into which to copy the memory If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l WX MICROWARE See Also os cpymem F CpyMem OS 9 for 68K Technical Manual F CPYMEM OS 9 Technical Manual crc Calculate Module CRC Syntax finclude mo
188. E initial file size bit is set you can also pass an initial file size estimate as a variable argument If either the FAM NOCREATE bit or the S TEXCL exclusive bit is set an error is returned if name already exists If neither FAM NOCREATE nor S EXCL are set any existing file called name is deleted By default if the pathlist specifies a file name that already exists _os_create recreates the file WX MICROWARE For More Information Refer to your operating system technical manual for the available mode and attribute bits p Note On OS 9 for 68K the binding for this call exists for compatibility If speed is an issue use os9 create Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also oS attach os open OS close os makdir ISCreate OS 9 Technical Manual I CREATE OS 9 Technical Manual I w D raro Datararnan lorary meterence _os9 create Create Path to New File Syntax include lt modes h gt finclude lt types h gt error code os9 create char name u int32 mode path id path u int32 perm uuo Description _os9 create creates a new file e Onmultifile devices the new file name is entered in the directory structure e Onnon multifile devices create is synonymous with open name is a pointer to the path name mode specifies
189. F EVENT EV DELET OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual WX MICROWARE os ev wait Wait for Event to Occur Syntax include lt events h gt finclude lt types h gt error_code _os_ev_wait event_id ev_id int32 value signal code signal int32 min val int32 max val Description os ev wait Waits for an event to occur It waits until an event call places the value in the range between the minimum and maximum activation values Then the wait auto increment specified at creation is added to the event variable ev ididentifies the event value is a pointer to the location where os ev wait stores the actual event value signal is a pointer to the location where os ev wait stores the signal code If a process in the event queue receives a signal it is activated even though the event has not actually occurred min val is the minimum activation value max val is the maximum activation value Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l1 See Also OoS ev signal oS ev waitr os9 ev waitr F EVENT OS 9 Technical Manual F EVENT EV WAIT OS 9 Technical Manual F EVENT EV SIGNL OS 9 Technical Manual WX MICROWARE _os9 ev wait Wait for Event to Occur Syntax
190. Fri Sat mmm is one of the following months of the year Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec dd specifies the day of the month hh mm ss specifies the time in hours minutes and seconds yyyy specifies the year ctime t is the equivalent of asctime localtime t Note ctime returns a pointer to a static area which may be overwritten To ensure data integrity use the string or save it immediately Attributes Operating System State Threads Re entrant Standards Library clib l See Also asctime gmt ime localtime WX MICROWARE OS 9 and OS 9 for 68K User and System Safe No ANSI detach Detach Device Syntax finclude lt io h gt finclude lt modes h gt int detach dev list ptr Description detach removes a device from the system device table if no other process is using it ptr is a pointer returned by either attach or os attach If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also os attach oS detach ISDetach OS 9 for 68K Technical Manual I DETACH OS 9 Technical Manual AA MICROWARE difftime Find Temporal Difference Syntax include lt time h gt double difftime time_t timel time t time0
191. If additional devices are required to be on the same vector as an os firq device use os9 irq to install them WX MICROWARE The interrupt stack provided is a small default IRQ stack The service routine must ensure that this stack is not overflowed The init module s IRQ stack value does not affect this stack the init module value is used to control the os9 irq polling system stack Attributes Operating System OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l See Also _os_irg FSFIRQ OS 9 for 68K Technical Manual os fmod Find Module Directory Entry Syntax include module h finclude lt types h gt error code os fmod u int32 type lang mod dir moddir entry char mod name Description os fmod searches the module directory for a module whose name type and language match the parameters If found a pointer to the module directory entry is returned in moddir entry type lang specifies the type and language of the module Only the lower 16 bits of type 1ang are used moddir entry is a pointer to the location where os fmod stores the pointer to the module directory entry mod name is a pointer to the module name Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os fork Create New Process Syntax finclude lt process h gt finclude lt types h gt erro
192. LE structure pos s a pointer to the value of the file position indicator pos is returned from getpos A successful call to setpos clears the end of file indicator for the stream and undoes any effects of unget c on the same stream After an setpos call the next operation on an update stream may be either input or output If successful setpos returns zero Otherwise it returns a non zero value and places the appropriate error code in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also fgetpos WX MICROWARE fstat Get File Status Syntax include UNIX stat h int fstat unsigned int fd struct stat buf Description fstat obtains the same information about an open file referenced by the argument descriptor as would be obtained by a stat call buf is a pointer to a scat structure into which information about the file is placed fstat returns zero on success It returns 1 on failure and sets errno to indicate the error Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix l See Also stat ftell Report File Pointer Position Syntax include lt stdio h gt long ftell FILE stream Description ftell returns the current value of the file position in
193. Manual os write Write Data to File or Device Syntax include lt modes h gt finclude lt types h gt error code os write path id path void buffer u int32 count Description os write outputs bytes to a file or device associated with the specified path number The path must have been opened or created in the write or update access modes path is the specified path number for the file or device buffer is a pointer to the data buffer The number of bytes to write is passed at the location pointed to by count os write also stores the number of bytes written at the location pointed to by count Data is written to the file or device without processing or editing If data is written past the present end of file the file is automatically expanded Note On RBF devices any record that was locked is released Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 See Also os open os create os9 create os writeln WX MICROWARE Ultra C Library Reference os writeln Write Line of Text with Editing Syntax include lt modes h gt finclude lt types h gt error code os writeln path id path void buffer u int32 count Description _os_writeln outputs bytes to a file or device associated with the specified path number The path must have been opened or created in wri
194. OS 9 State User and System Threads Safe Re entrant Yes Library os lib l1 os getsys Examine System Global Variable Syntax include lt sysglob h gt finclude lt types h gt error code _os_getsys u_int32 offset u_int32 size glob_buff sysvar Description _os_getsys enables a process to examine a system global variable These variables have ad prefix in the system header file sysglob h Consult the files in the DEFS directory for a description of the system global variables offset is the variable s offset in the system globals size specifies the size of the variable 1 2 or 4 bytes sysvar is a pointer to the location where os getsys stores the value of the requested system global Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE Example This example gets the current value of the tick counter include stddef h if err os getsys offsetof sysglobs d ticks 4 amp buf 0 exit err See Also os setsys os gprdsc Get Process Descriptor Copy Syntax finclude process h finclude lt types h gt error code os gprdsc process id procid void buffer u int32 count Description os gprdsc copies a process descriptor into your buffer for inspection procidis the requested process ID buffer is a pointer to the buffer to use The maximu
195. OS 9 Technical Manual execl Calls a File With Variable Arguments Syntax include lt UNIX os9def h gt int execl char path char argO Dr Description exec1 is the UNIX like exec interface to the os chain system call path is the pathlist to the program to chain to arg0 and any additional variable arguments are the arguments to pass to the chained process arg0 is conventionally the name of the chained program The list of variable arguments is terminated by a NULL entry The global variable environis used for the environment for the call to os chain execl returns 1 and sets the global variable errno to indicate an error exec1 only returns an error if setting up for the os chain call fails Once an attempt to chain occurs the process exits if any error occurs Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix l WX MICROWARE See Also execle execv execvp 226 Ultra C Library Reference execle Calls a File With Variable Arguments Syntax include lt UNIX os9def h gt int execle char path char argO char envp Description execle is the UNIX like exec interface to the os chain system call path is the pathlist to the program to chain to arg0 and any additional variable arguments are the arguments to pass to the chained process arg0 is conventionally the name of
196. OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also oS sema init OS Sema term OS Sema v WX MICROWARE os sema term Terminate Use of Semaphore Data Structure Syntax include lt semaphore h gt error code _os_sema_term semaphore sema Description OS 9 for 68K os sema term is valid in version 3 0 and greater os sema term terminates the use of the semaphore The application should call os sema term before terminating the application sema is a pointer to the semaphore data structure to terminate Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also OoS sema init os sema p os sema v os sema v Release Semaphore Release Exclusive Access Syntax include lt semaphore h gt error code _os_sema_v semaphore sema Description OS 9 for 68K os sema v is valid in version 3 0 and greater os sema v releases the reservation of a semaphore If a process is waiting on the semaphore it is activated allowing it to attempt to acquire the semaphore sema is a pointer to the semaphore to release The os sema v call releases the semaphore but does not give it to the next process waiting for it Instead if the process that issued the os sema v callissues a os sema p call before its slice is up then it re obtains the
197. OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual os getdl Get System I O Device List Head Pointer Syntax finclude lt io h gt include lt types h gt error code os getdl dev list dev list ptr Description os getdl returns a pointer to the first entry in the system s I O device list dev list ptris a pointer to the location where os getdl stores the pointer to the first entry in the device list Note This pointer should never be accessed directly in user state You should use os cpymem to get a copy of the device list entry Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os getime Get System Date Time Syntax include lt time h gt finclude lt types h gt error_code _os_getime time_t time u int32 xticks Description _os_getime returns the current system time in the number of seconds since a date specified in Greenwich Mean Time To determine the specified date refer to the applicable manual OS 9 for 68K Technical Manual or OS 9 Technical Manual time is a pointer to the location where os getime stores the current time ticks is a pointer to the location where os getime stores the clock tick rate in ticks per second in the most significant word and the current tick in the least significant word Note On OS 9 for 68K the
198. OS ev tstset 56 601 ABCDEFGHIJKLMNOPQRSTUVWXYZ os ev unlink 56 603 OS ev wait 56 604 OS ev waitr 56 607 os exec 77 611 os exit 35 621 os findpd 77 623 os firq 59 625 os fmod 69 627 os fork 77 628 os forkm 77 633 Os get blkmap 635 OS get ioproc 49 643 os get mdp 70 644 os get moddir 70 645 os get module 645 Os get prtbl 77 647 os getdl 49 637 OS getime 87 638 os getpd 66 646 Os getstat 40 77 648 Os getsys 40 77 649 os gprdsc 77 651 OS gregorian 88 652 Os gs cpypd 40 654 OS gs cstats 40 655 os gs devnm 40 656 os gs devtyp 40 657 OS gs dopt 40 659 OS gs dsize 40 660 OS gs edt 40 661 os gs eof 40 662 os gs fd 40 663 os gs fdaddr 40 664 os gs fdinf 40 665 os gs luopt 41 668 OS gs parity 41 669 OS gs popt 41 670 OS gs pos 41 671 Os gs ready 41 673 OS gs size 41 674 os id 77 675 ABCDEFGHIJKLMNOPQRSTUVWXYZ os initdata 70 678 OS intercept 56 679 OS ioconfig 681 configure 681 os iodel 49 682 Os ioexit 49 683 Os iofork 49 684 os irq 59 686 Os julian 88 690 os link 70 697 os linkm 70 699 os load 70 700 os loadp 70 702 os makdir 49 704 _os_makmdir 70 706 os mem 63 707 os mkmodule 708 os modaddr 70 710 os move 711 os nproc 78 712 os open 49 713 os permit 64 716 _os perr 66 718 OS protect 64 720 _os_prs
199. Only the owner of the file or the super user can change a file s attributes path is the path number of a disk file attr specifies the file attributes to set Only the lower 16 bits of attr are used The attributes selected in attr are set in the file open on path The modes h header file defines the valid mode values If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Note _ss_attr is effective even if the owner or super user does not have write permission to the path You cannot set the directory bit of a non directory file or clear the directory bit of a directory that is not empty Attributes Operating System State Threads Re entrant Library Sys clib 1l1 See Also D8 gs fd JOB ce atEr oe ss rcf ISSetStt I SETSTAT SS ATTR WX MIC ROWARE OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual sscanf Input Strings Conversion Syntax include lt stdio h gt int sscanf const char input const char format Description sscanf reads input from the string specified by input Reaching the end of the string is equivalent to encountering end of file for fscanf If copying takes place between overlapping objects the behavior is undefined input is a pointer to the input string format is a pointer to the control string sscanf returns EOF if an
200. Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib l memcmp Compare Memory Syntax include lt string h gt int memcmp const void stringl const void string2 size t size Description memcmp compares the first size characters of st ringl to the first size characters of st ring2 stringl is a pointer to a string to compare string is a pointer to a string to compare size is the number of characters to compare memcmp returns an integer that is e Positive if string1 is greater than st ring2 e Zero if stringl equals string2 e Negative if stringl is less than st ring2 Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 WX MICROWARE memcpy Copy Memory Syntax include lt string h gt void memcpy void dest const void source size t num Description memcpy copies characters from one location to another If copying takes place between overlapping objects the behavior is undefined memcpy returns the value of dest dest is a pointer to the destination in memory source Is a pointer to the memory to copy into dest num is the number of characters to copy Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib
201. Output word to file stdio h read Read bytes from path modes h readdir Return pointer dir h readln Read bytes from path modes h remove Remove file stdio h rename Rename file stdio h seekdir Set position of next readdir dir h scanf Input strings conversion stdio h setbuf Fix file buffer stdio h Table 1 9 Ultra C I O Functions continued ANSI Header Function Standard Description File setvbuf Set up buffer for I O stream stdio h sprintt i Formatted strings output stdio h sscanf Input strings conversion stdio h telldir Return current location dir h tmpfile Create temporary binary file stdio h ungetc Unget character stdio h unlink Unlink delete file modes h unlinkx Unlink delete file modes h vfprint Print to file stdio h vprintf Print to standard output stdio h vsprintf Print to string stdio h write Write bytes to path modes h writeln Write bytes to path modes h WX MICROWARE Interprocess Communication Functions Functions available for interprocess communication are shown in Table 1 10 ANSI prototypes for non ANSI functions are achieved by defining the macro name OPT_PROTOS during the compile Table 1 10 Interprocess Communication Functions Function Standard Description Header File alm_atdate Send signal at alarm h Gregorian date time alm atjul Send signal at Julian alarm h date time alm cycle Send signal
202. READ OS 9 Technical Manual F_EVENT EV_SIGNL OS 9 Technical Manual os ev set Set Event Variable and Signal Event Occurrence Syntax include lt events h gt finclude lt types h gt error_code _os_ev_set event_id ev_id int32 value u int32 actv flag Description os ev set signals that an event has occurred The current event variable is set to the value passed at value Then the event queue is searched for the first process waiting for that event ev id identifies the event value is a pointer to the location where os ev set stores the event value prior to the set operation actv flag specifies which process es to activate e If actv_flag is one all processes in range are activated e If actv_flag is zero the first process in the event queue waiting for that range is activated Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also os ev signal FSEvent F EVENT F EVENT EV SET F EVENT EV SIGNL WX MICROWARE OS 9 for 68K Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual os ev setand Set Event Variable and Signal Event Occurrence Syntax include lt events h gt finclude lt types h gt error code os ev setand event id ev id int32 value u int32 mask u int32 actv flag Description os
203. ROWARE SS ssig Send Signal on Data Ready Syntax include sg codes h int ss ssig int path int sigcode Description Ss ssig Sets up a signal to be sent to the calling process when an interactive device has data ready This feature exists only on SCF devices and pipes When data is received on the device indicated by path a signal is sent to the calling process path is the device s path number sigcode specifies the signal code to send Only the lower 16 bits of sigcode are used on OS 9 for 68K _ss_ssig must be called each time the signal is sent if it is to be used again The device is considered busy and returns an error if any read requests arrive before the signal is sent Write requests to the device are allowed while in this state If an error occurs 1 is returned and the appropriate error value is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l1 See Also oS ss relea OoS ss sendsig ISSetStt I SETSTAT SS SENI DS OS 9 for 68K Technical Manual IG OS 9 Technical Manual WX MIC ROWARE _ss_tiks Wait for Record Release Syntax include lt rbf h gt int _ss_tiks int path int tickcnt Description If a read or write request is issued for a part of a file that is locked out by another user RBF normally sleeps indefinitely un
204. SPR SPR SPR SPR SPR PREG SPR SPR SPR SPR SPR SPR WX MICROWARE Table 2 12 get lt name gt Valid Names and Associated Processors continued Register Processor s name Type 403 505 601 603 User Writable pvr SPR rpa SPR e rtcl SPR E rtcu SPR sdrl SPR sprgO SPR sprgl SPR Sprg2 SPR sprg3 SPR sro PREG Bd PREG Sr2 PREG srs PREG sr4 PREG sr5 PREG sr6 PREG I I tra C I ihrary Rafaranra Ultra C Library Reference Table 2 12 get lt name gt Valid Names and Associated Processors continued Register Processor s name Type 403 505 601 603 User Writable st PREG sr8 PREG sr9 PREG sr10 PREG sr11 PREG arl2 PREG sr13 PREG srl4 PREG sr15 PREG srrO SPR s e srrl SPR E E E srr2 SPR srr3 SPR tbhi SPR tbl SPR tbl TB WX MICROWARE Table 2 12 get lt name gt Valid Names and Associated Processors continued Register lt name gt Type tblo SPR tbu SPR tbu TB ter SPR tsr SPR xer SPR Legend Processor s 403 505 601 603 User Writable e e e e e e e e e User state read versionis get user name Write version is system state only Attributes Operating System State Threads Re entrant Library c
205. Stt OS 9 for 68K Technical Manual I SETSTAT OS 9 Technical Manual WX MICROWARE oS ss relea Release Device Syntax include sg codes h finclude lt types h gt error code os ss relea path id path Description OS ss relea releases the device from any os ss sendsig OS Ss dcon 0r os ss dcoff request made by the calling process path is the path number of the device to release Attributes Operating System State Threads Re entrant Library os lib l See Also os ss sendsig 0s ss dcocotri De ss doon OS 9 and OS 9 for 68K User and System Safe Yes OS SS rename Rename File Syntax include sg codes h finclude lt types h gt error code os ss rename path id path char newname Description os ss rename changes the file name in the file s associated directory entry to newname path is the file s path number newname is a pointer to the file s new name Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE OS SS reset Restore Head to Track Zero Syntax include sg codes h finclude lt types h gt error code os ss reset path id path Description For RBF os ss reset directs the disk head to track zero It is used for formatting and error recovery For SBF os ss reset rewinds the tape path is the path num
206. Syntax include lt math h gt double fmod double X double y Description fmod computes the floating point remainder of x divided by y If y is non zero mod returns the value with the same sign as x and a magnitude less than the magnitude of y If y is zero zero is returned Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 Possible Error EDOM WX MICROWARE fopen Open File Syntax include lt stdio h gt FILE fopen const char name const char mode Description fopen opens a file and associates a stream with it If an error occurs fopen returns NULL name is a pointer to the name of the file mode is a pointer to the access mode mode may be one of the following Table 2 5 fopen Mode types Mode Description r Open text file for reading w Truncate to zero length or create text file for writing a Append open or create text file for writing at end of file rD Open binary file for reading wb Truncate to zero length or create binary file for writing ab Append open or create binary file for writing at end of file r Open text file for update reading and writing Table 2 5 fopen Mode types continued Mode Description wt Truncate to zero length or create text file for update at Append open or create text file for update writing at en
207. Syntax include lt stdio h gt void rewind FILE stream Description rewind sets the file position indicator for the stream pointed to by stream to the beginning of the file It is equivalent to the following except that the error indicator for the stream is also cleared void fseek stream OL SEEK SET stream is a pointer to the C I O file structure rewind returns no value Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also fseek WX MICROWARE rewinddir Reset Position of Directory Stream Syntax include dir h void rewinddir DI R dirp Description rewinddir resets the position of the named directory stream to the beginning of the directory dirp is a pointer to the directory stream Attributes Operating System State Threads Re entrant Library Sys clib l1 See Also closedir opendir readdir seekdir tellgiri OS 9 and OS 9 for 68K User and System Safe Yes rindex Search for Character in String Syntax include strings h char rindex char ptr int oh 5 Description rindex returns a pointer to the last occurrence of a character in a string If the character is not found rindex returns NULL ptr is a pointer to the string to search ch is the character for which to search Only the lower 8 bits of cn a
208. TMPDIR whose value is the name of the desired temporary file directory Many applications prefer their temporary files to have certain favorite initial letter sequences in their names Use the pfx argument for this This argument may be NULL or point to a string to be used as the first few characters of the temporary file name tempnam uses malloc to get space for the constructed file name and returns a pointer to this area Thus any pointer value returned from tempnam may serve as an argument to free If tempnam cannot return the expected result for any reason that is malloc failed or none of the above mentioned attempts to find an appropriate directory was successful a NULL pointer is returned Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix l tgetent Get Termcap Entries Syntax include lt termcap h gt extern char BC extern char UP int tgetent char bufptr char name Description tgetent extracts the entry for the specified terminal type The entry is placed in a buffer The buffer size must be at least 1 024 characters and must remain intact for all subsequent calls to tgetnum tgetflag and tgetstr bufptr is a pointer to the buffer in which to place the entry name is a pointer to the name of the terminal type If the termcap file cannot be opened 1 is returned If the terminal name cann
209. Threads Safe Re entrant Yes Library ctype h See Also isalnunm isalpha 1senpeklq 1isedigit isgraphi islower lgpreinti t l8punect isspace isupper 158xXCOlg1 0 382 WX MIC ROWARE isatty Find Terminal Name Syntax include UNIX os9def h include lt setsys h gt int isatty int fd Description isatty returns 1 if a is associated with a SCF device Otherwise it returns zero Note This routine available as a function or a macro in ctype h does not operate well with values outside the range of an unsigned char The function checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b isatty c Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l Ultra C Library Reference iscntrl See If Parameter Is Control Code Syntax include lt ctype h gt int iscntrl int c Description iscntrl is aC macro that returns a non zero value for ASCII character
210. Threads Safe Re entrant Yes Library os lib l See Also F Load OS 9 for 68K Technical Manual F LOAD OS 9 Technical Manual WX MICROWARE os loadp Load and Link to Memory Module Using PATH Syntax include lt module h gt include lt modes h gt finclude lt types h gt error code _os_loadp char name u int32 mode char nameptr mh com mod head Description _os_loadp opens a file specified by the pathlist It reads one or more memory modules from the file into memory until an error or end of file is reached then it closes the file The PATH environment variable determines the alternate directories to search for the named file name is a pointer to the file name mode specifies the access mode Only the lower 16 bits of mode are used nameptr is a pointer to a buffer for the pathlist of the successfully loaded file Use NULL to indicate that no complete pathlist is required mod head is a pointer to the location where os loadp stores the pointer to the module For More Information Refer to your operating system technical manual for information regarding the PATH environment variable Attributes Operating System State Threads Re entrant Library os lib l See Also os load oS exec OS 9 and OS 9 for 68K User and System Safe Yes WX MICROWARE os makdir Make New Directory Syntax include lt modes h gt finclude lt types
211. Ultra C Library Reference Version 2 1 AA MICROWARE Intelligent Products For A Smarter World WX MIC ROWARE Copyright and Publication Information Copyright 2000 Microware Systems Corporation All Rights Reserved Reproduction of this document in part or whole by any means electrical mechanical magnetic optical chemical manual or otherwise is prohibited without written permission from Microware Systems Corporation This manual reflects version 2 1 of Ultra C Revision K Publication date September 2000 Disclaimer The information contained herein is believed to be accurate as of the date of publication However Microware will not be liable for any damages including indirect or consequential from use of the OS 9 operating system Microware provided software or reliance on the accuracy of this documentation The information contained herein is subject to change without notice Reproduction Notice The software described in this document is intended to be used on a single computer system Microware expressly prohibits any reproduction of the software on tape disk or any other medium except for backup purposes Distribution of this software in part or whole to any other party or on any other system may constitute copyright infringements and misappropriation of trade secrets and confidential processes which are the property of Microware and or other parties Unauthorized distribution of software may cause da
212. WX MICROWARE Currently the C locale is fully supported If locale is C the minimal environment for C translation is specified 1 If Locale is the value of the corresponding environment variable LC TIME for category LC TIME and so forth is checked for validity If the environment variable contains a valid locale string locale is set accordingly If it does not contain a valid string set locale behaves as if passed an invalid locale string If the environment variable is not set or is set to the empty string the existence and validity of the environment variable LANG is checked and locale is set from these If LANG does not exist locale is set to C At program startup the equivalent of the following is executed setlocale LC ALL C If Locale is a pointer to a string and the selection can be honored setlocale returns a pointer to the string associated with the specified category for the new locale If the selection cannot be honored set locale returns a null pointer and the program s locale is not changed A null pointer for Locale causes set 1ocale to return a pointer to the string associated with the category for the program s current locale the program s locale is not changed The pointer to the string returned by set locale is such that a subsequent call with that string value and its associated category restores that part of the program s locale The program does
213. _os9_srqmem _os_srtmem _os9_translate _srqmem _srtmem srqcmem Module directory information moddir h contains prototypes for the following functions os altmdir os chmdir os cmdperm os delmdir os fmod os get mdp os makmdir Indicates a standard ANSI header Table 1 2 Ultra C Header Files continued File Description modes h Defines the access modes and permissions for files and directories modes h contains prototypes for the following functions accessibsttechi chdir r ehownt chmod chxdir close creat create detach dup Leeek makdir mknod open os chdir 05 closei os create lt ps9 ireate cr os deletel os dup os ioconfig os makdir os open os read os readlin oS seek os9 ss close os9 ss open os write _os_writeln read readin unlink unlinkx write writeln Indicates a standard ANSI header WX MICROWARE Table 1 2 Ultra C Header Files continued File Description module h mqueue h Module related data structures and functions module h contains prototypes for the following functions crc get module dir make module modcload mkdata module modlink modload modloadp munlink munload os crc os datmod oSs get moddir os initdata s iodel os link os linkm os load os
214. ables that may be changed Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 _os_setuid Set User ID Number Synta incl X lude lt process h gt inc Lude lt types h gt error_code _os_setuid owner_id user_id Description _os_setuid changes the current user ID to user_id user_id is the desired group user ID number The following restrictions apply to os setuid e Us ers with group ID zero may change their IDs to anything without restriction A primary module owned by a group zero user may change its ID to anything without restriction Any primary module may change its user ID to match the module s owner Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os sgetstat GetStat Call Using System Path Number Syntax include sg codes h finclude lt types h gt error code os sgetstat path id Spath u int32 code void pb Description _os_sgetstat makes a specific Get Stat or Set Stat call spath is the system path number code is the Get Stat code pb is a pointer to the parameter block corresponding to the function being performed If the function does not have a parameter block for example os ss reset pb should be NULL Attributes Operating System OS 9 State Use
215. ache control information cache h contains prototypes for the following functions oS cache _os_scache Contains CD I specific functions cdi h contains prototypes for the following function 089 ss crai Declares Ultra C global variables Declares functions that are useful for testing and mapping characters ctype h contains prototypes for the following functions isalnum isalpha d889OGilil PSASCII Ca Sener 1 isdigit _iseuc_kana iseucl _iseuc2 isgraph _isjis_kana islower isprint ispunctk t A88 2811 388741521 isspace isupper isxdigiti toasciiti toasecriit tolower tolower toupper toupper Indicates a standard ANSI header WX MICROWARE Table 1 2 Ultra C Header Files continued File Description dexec h dir h direct h OS 9 for 68K only errno h t Defines information related to debugger controlled processes dexec h contains prototypes for the following functions os dexec os dexit 65 dforki os dforkmi Gs9 Grorkc Defines structures and functions for BSD 4 2 directory calls dir h contains prototypes for the following functions closedir opendir readdir rewinddir seekdir telldir Defines the RBF data structures This is obsolete it has been replaced with rbf h Defines macros relating to error reporting errno h contains a prototype for the following function _os_perr Indi
216. address character 45 864 integer 45 865 word 45 866 I O functions cleareof 46 168 _fileno 47 249 os alias 48 513 os attach 48 521 os chdir 48 530 os close 48 535 os copy ioproc 48 541 os create 48 545 os delete 48 555 os detach 49 560 os dup 49 571 os get ioproc 49 643 os getdl 49 637 os iodel 49 682 Os ioexit 49 683 os iofork 49 684 os makdir 49 704 os open 49 713 os rdalst 49 725 os read 49 726 os readln 49 728 _os_write 50 859 _os_writeln 50 861 _os9_create 48 547 _os9 ioqueue 49 685 attach ABCDEFGHIJKLMNOPQRSTUVWXYZ new device to system 48 path to file pointer 46 239 to device 45 143 521 attach 45 143 change current execution directory 46 166 working directory 48 530 check buffered file for end of file 47 241 error condition 47 242 for use of I O module 49 682 chxdir 46 166 clear end of file condition 46 168 error condition 46 170 cleareof 168 clearer 46 170 close file 46 237 path 46 48 172 535 close 46 172 copy system alias list 49 725 creat 46 184 create device alias 48 513 directory 48 438 459 file 46 184 186 path to new file 48 545 547 temporary binary file 51 1053 unique filename 48 461 create 46 186 delete file 48 555 detach device 46 191 detach 46 191 determine path number from file 47 249 duplicate path 49 571 enter I O queue 49 685 fclose 46 237 fdopen 46 239
217. ads Safe Re entrant No Standards ANSI Library clib 1 toascii toascii Character Translation Syntax finclude lt ctype h gt int toascii int c int toascii int c Description _toascii returns a character with all bits that are not part of a standard ASCII character turned off It is used for compatibility with other systems Only toascii is available in strictly conforming ANSI mode c is the returned character Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library CES T See Also getc getchar WX MICROWARE tolower Convert Character to Lowercase Syntax include lt ctype h gt int _tolower int c Description _tolower is amacro that changes the uppercase parameter to lowercase The parameter must be uppercase or the results are unpredictable and useless Use tolower if the parameter is not guaranteed to be uppercase c is the character to convert Only the lower 8 bits of c are used _tolower is hard coded to the ASCII character set Changing the locale does not cause tolower to recognize a non ASCII character You must use tolower if you are not using ASCII characters Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library ctype h See Also tolower toupper iB8850 110 1888980331 tol
218. al Parameters Function Parameter Definition _os_fork extral The child process ID returns to where extral points extra2 Type language of the new process extra3 Orphan 0 Normal child process 1 Process not associated with parent _os_forkm extral The child process ID returns to where extral points extra2 Orphan 0 Normal child process 1 Process not associated with parent Table 2 20 os9kexec Additional Parameters continued Function Parameter Definition _os_chain extral Type language of the new process _os_chainm Does not use the extra parameters _os_dfork extral The child process ID returns to where extral points extra2 Type language of the new process extra3 Pointer to register stack for child process extra4 Pointer to floating point register stack for child process _os_dforkm extral The child process ID returns to where extral points extra2 Pointer to register stack for child process extra3 Pointer to floating point register stack for child process If func indicates a fork function and the initial attempt to create the child process fails due to EOS_PNNF path name not found os9kexec calls modloadp with modname to load the module from disk and attempts the fork again This action is the same as the shell handling of executable files AN MICROWARE Note 694 If you use os9kexec when func is os chain or _os_chainc you must either Ensure
219. al to Serial Line Syntax include sg codes h finclude lt types h gt error code os ss break path id path Description JOS ss break sends a break conditional to the serial line path specifies the path number Attributes Operating System State Threads Re entrant Library os lib l See Also I SETSTAT SS BREAK OS 9 User and System Safe Yes OS 9 Technical Manual OS ss cache Enable Disable RBF Caching Syntax include lt rbf h gt finclude lt types h gt error_code _os_ss_cache path_id path u_int32 enblflag u_int32 drvcsize Description _os_ss_cache enables and disables RBF caching on an RBF device path specifies the path number enblflag is the cache enable disable flag e If enblflag is zero caching is disabled If enblflag is non zero caching is enabled drvcsize is the memory size for the cache Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library os_lib l WX MICROWARE _os9 ss close Notify Driver that Path Has Been Closed Syntax include sg codes h finclude lt types h gt error code os9 ss close path id path Description OS9 ss close notifies a driver that a path has been closed path specifies the path number that was closed Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 os
220. alent The conversion terminates when The requested number of digits are converted The specified number of digits after the decimal point is reached fnumis the floating point number to convert buff is a pointer to a buffer for the converted ASCII string _dtoa returns the signed decimal exponent The returned string only contains mantissa digits A null byte is appended to the end of buf f buff should be one byte larger than the requested number of digits tot digs is the number of digits requested frac digs is the specified number of digits following the decimal point signis a pointer to the sign Set the sign in sign as follows e 1 for a negative sign e 0 for a positive sign If num represents or an IEEE 754 Not a Number and tot digs is greater than or equal to three buf contains respectively Inf or NaN If cot digs is less than three buff contains respectively I or N In these cases _dtoa returns DBL MAX 10 EXE dtoa returns no errors Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Clqp WX MICROWARE dup Duplicate Path Syntax include lt modes h gt int dup int path Description dup returns a synonymous path number for an existing file or device The lowest available path number is used path specifies the path number dup increments the link count of a path descriptor an
221. alling process to sleep 782 784 file descriptor sector 983 next character to file standard out 883 putc 50 883 putchar 883 putenv 885 puts 50 886 putw 50 107 887 ABCDEFGHIJKLMNOPQRSTUVWXYZ Q qsort 80 888 quick sort 888 quotient Idiv 419 return 193 419 R raise 58 889 rand 61 890 random number rand 890 return 890 set seed for generator 965 srand 965 RBF caching Os ss cache 797 disable 797 enable 797 rbf h 25 read 668 bytes from path 891 894 data from device 726 file 269 726 device path options 659 event value 588 event without waiting 211 file descriptor sector 663 fread 269 logical unit options 668 path descriptor option section 670 text line 728 word from file 339 read input scatter data readv 896 read 50 107 891 readdir 107 893 ABCDEFGHIJKLMNOPQRSTUVWXYZ readin 50 107 894 readv 896 realloc 64 101 898 record os ss lock 810 OS ss ticks 823 Ss lock 979 Ss tiks 990 lock out 810 979 wait for release 823 990 regcmp 900 regerror 901 regex 902 regexec 902 regexp h 25 registers get value of get name 292 set value of 916 regs h 26 regular expression handler comparison 902 compiler 900 error handler 901 release device 814 985 ownership of resource lock 729 remainder Idiv 419 return 193 419 remove device 191 560 from IRQ table 686 688 file 903 pending alarm request 126 510 742 743 r
222. alue is restored after activating processes if any ev idis the event ID returned from a call to ev creat ev link os ev creat Of os ev link ev value sets the value of the event variable allflag indicates which process es to activate Only the lower 16 bits of allflag are used e Ifa 1fj activated 1fj e Ifal ag is zero the first process waiting for the event is ag is 0x8000 all processes waiting for the event that have a value in range are activated If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Refer to your operating system technical manual for more information about events Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also ev creat ewv linkt os ev creat os ev link os ev pulse FSEvent F EVENT V CREAT EV LINK EV PULSE WX MICROWARE OS 9 for 68K Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual ev read Read Event Without Waiting Syntax include lt events h gt int ev read int ev id Description ev read reads the value of an event without waiting for or affecting the event variable and returns the current value of the event ev id identifies the event If an error occurs 1 is returned and the app
223. am is a pointer to the C I O FILE structure fclose returns zero if the stream was successfully closed Otherwise EOF is returned For More Information The sclib 1 and sclib il libraries contain a smaller version of the fclose function Refer to the Using Ultra C C manual for more information about the small library functions Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 238 See Also fflush fopen getc getchar pute purchari tmpfile WX MICROWARE Ultra C Library Reference fdopen Attach Path to File Pointer Syntax include lt stdio h gt FILE fdopen int path char action Description fdopen returns a file pointer to the file specified by a currently open path path is the path to attach action is a pointer to the file action string The action must be compatible with the access mode of the given path The valid actions are listed in Table 2 4 Table 2 4 Valid Actions Action Description r Open for reading w Open for writing a Append write at the end of the file or create file for writing if path does not exist r Open for update w Create for update a Create or open for update at end of file d Directory read WX MICROWARE Use fdopen when you require some special processing not provided by open for opening files Attribute
224. andler process h errno h strings h process h regs h memory h svctbl h funcs h process h settrap h Table 1 14 Miscellaneous Functions continued ANSI Function Standard Description Header File 089 strap Set error trap handler settrap h oS sysid Return system identification regs h os uacct User accounting process h pause Parse disk file RBF pathlist strings h perror Map error number stdio h prerr Print error message stdio h _prgname Get module name module h _prsnam Parse path name segment strings h setjmp Non local goto setjmp h setlocale Locale control locale h setuid Set user ID process h stacksizi Get size of stack used stdlib h Btacksiz _strass Structure assignment strings h tmpnam Generate unique valid stdio h filename va arg Get parameter in variable stdarg h parameter list WX MICROWARE Table 1 14 Miscellaneous Functions continued ANSI Function Standard Description Header File va_end End references to current stdarg h variable parameter list va starti Initialize variable parameter stdarg h list Module Manipulation Functions Table 1 15 shows the module manipulation functions ANSI prototypes for non ANSI functions are achieved by defining the macro name OPT PROTOS during the compile Table 1 15 Module Manipulation Functions ANSI Function Standard Description Header File euet Calculate module
225. ape marks 43 818 to end of tape 43 822 wait for record release 44 990 specified number of ticks for record release 43 823 write file descriptor sector 42 805 logical unit options 43 811 option section of path descriptor 43 813 tape marks 43 824 track 43 44 825 992 setstat 44 108 940 setsys h 27 settrap h 27 ABCDEFGHIJKLMNOPQRSTUVWXYZ setuid 67 109 944 setvbuf 51 945 sg codes h 28 sgstat h 28 shell execute command 1037 system 1037 SIG1010 95 954 SIG1111 95 954 SIGABRT 93 114 132 952 SIGADDR 95 954 SIGALIGN 97 956 SIGALRM 94 953 SIGBNDCHK 96 955 SIGBRKPT 96 955 SIGCHECK 96 97 956 SIGCHK 95 954 SIGCOPRCV 954 SIGDBG 96 955 SIGDBLFLT 96 955 SIGFMTERR 954 SIGFPE 93 952 SIGGPROT 96 955 SIGHUP 94 953 SIGILL 93 98 952 SIGINST 96 956 SIGINT 93 952 SIGINVTSS 96 955 SIGKILL 94 953 sigmask 58 109 947 949 signal ev pulse 209 os intercept 679 os send 758 _os_sigmask 777 Ss ssig 988 cancel signal to send on data ready 985 define mask 947 event occurrence 209 213 215 217 586 589 591 593 595 597 599 kill 413 ABCDEFGHIJKLMNOPQRSTUVWXYZ mask 777 pause 869 raise 889 reset intercept context stack 779 send 758 on data ready 988 to program 413 889 set up intercept trap 679 unmask 777 wait for 869 signal handler control for process 947 defined 950 intercept 364 setup 364 sigmask 947 signal 950 specify 950 signal
226. aphore acquire exclusive access Terminate use of semaphore data structure Release semaphore release exclusive access Send signal to another process semaphore semaphore semaphore signal h WX MICROWARE Table 1 10 Interprocess Communication Functions continued ANSI Function Standard Description Header File _os_siglngj Set signal mast signal h value and return on types h specified stack image _os_sigmask Mask unmask signal h signals during critical code o08 sigreset Reset signal signal h intercept context stack s eigre Resize current signal h process signal queue block pause Wait for signal signal h raise Send signal to signal h program sigmask Control process signal h signal handling signal Specify signal signal h handling Interrupt Manipulation Functions The following functions are provided for interrupt manipulation ANSI prototypes for non ANSI functions are achieved by defining the macro name OPT_PROTOS during the compile Table 1 11 Interrupt Manipulation Functions ANSI Function Standard Description Header File irq change Set IRQ level regs h irq disable Mask interrupts regs h irq enable Unmask interrupts regs h irq maskget Mask interrupts return regs h previous level irq restore Restore interrupt level regs h irq save Return current interrupt regs h level os firqi Add or remove device from regs
227. aracter are not copied If copying takes place between overlapping objects the behavior is undefined dest is a pointer to the destination string src is a pointer to the source string to copy count specifies the maximum number of characters to copy If src is shorter than count characters null characters are appended to the copy in dest until count characters in all have been written strncpy returns the value of dest Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 strpbrk Locate First Occurrence of String Syntax include lt string h gt char strpbrk const char Src const char delim Description strpbrk locates the first occurrence in src of any character from delim src is a pointer to a string in which to search for any character from delim delim is a pointer to a string containing characters to locate in src strpbrk returns a pointer to the character or a null pointer if no character from delim occurs in src Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library elabsL WX MICROWARE strrchr Locate Last Occurrence of String Syntax include lt string h gt char strrchr const char Src int chr Description strrchr locates the last occurrence of chr converted to char in src
228. aracter that is neither the first nor the last character in the scanlist for conversion in the fscanf function 4 9 6 2 A hyphen character is interpreted simply as the addition of to the scanlist The value to which the macro errno is set by the getpos or ftell function on failure 4 9 9 1 4 9 9 4 errno is set to the operating system specific error that is returned by either os gs size in append mode or os gs pos The messages generated by the perror function 4 9 10 4 The messages generated by the perror function are located in the system errmsgfile dd SYS errmsg h0 SYS errmsg or d0 SYS errmsg Refer to your operating system technical manual for detailed information Error messages are generally in the form message lt major gt lt minor gt detail message is the user passed message string ma jor is the family of error minor is the error number within the family detail is the information from the system errmsg file if available The behavior of the cal1oc malloc O0r realloc function if the size requested is zero 4 10 3 The calloc malloc and realloc functions return NULL if the requested size is zero The behavior of the abort function with regard to open and temporary files 4 10 4 1 If the SIGABRT signal handler returns the program is terminated abnormally flushing open streams closing open streams and removing temporary f
229. args See Also fprinttt va arg va end va starb vprintf Print to Standard Output Syntax include lt stdarg h gt include lt stdio h gt int vprintf const char format va_list arg Description vprintf performs formatted output to stdout It converts formats and prints any parameters as indicated by the control string vprintf is similar to printf However arg replaces the variable parameter list format is a pointer to a control string arg is initialized by va_start and possibly subsequent va_arg Calls vprintf does not call va_end vprintf returns the number of characters transmitted If an output error occurs a negative value is returned For More Information The sclib 1 and sclib il libraries contain a smaller version of the vprintf function Refer to the Using Ultra C C manual for more information about the small library functions Attributes Operating System State Threads Re entrant Standards Library clib l See Also fprintf printfi va arg va end va Start WX MICROWARE OS 9 and OS 9 for 68K User and System Safe No ANSI vsprintf Print to String Syntax include lt stdarg h gt include lt stdio h gt int vsprintf char ASE const char format va list arg Description vsprintf performs formatted output to a string It converts formats and prints any parameters as i
230. ary Sys clib 1l1 See Also close creat os create os open TSOpen OS 9 for 6K Technical Manual OS open OS 9 Technical Manual WX MICROWARE 500 Ultra C Library Reference opendir Open Directory Syntax include lt dir h gt DIR opendir char filename Description opendir opens the specified directory and associates a directory stream with it opendir returns a pointer identifying the directory stream in subsequent operations The pointer NULL is returned if filename cannot be accessed or if it cannot allocate enough memory to hold the entire DIR structure filename is a pointer to the name of the directory Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library Sys clib l See Also eclosedir t readdir rewinddir seekdir telldir WX MIC ROWARE _os_acqlk Acquire Ownership of Resource Lock Syntax finclude lt lock h gt finclude lt types h gt error code _os_acglk lk desc lock signal code signal Description _os_acqlk acquires ownership of a resource lock that is it attempts to gain exclusive access to a resource lock is a pointer to the 1k desc structure of the lock that you are trying to acquire signal is a pointer to the location where _os_acqlk stores the signal that prematurely terminated the acquisition of the lock if applicable If
231. ary Reference 3 WX MICROWARE 83 Terminal Manipulation Functions Termcap 84 Time Functions 89 Processor Specific Functions 90 Implementation Defined Behavior 92 ANSI Core Signals 92 OS 9 Core Signals 92 OS 9 68K Family Signals 92 OS 9 80x86 Family Signals 93 OS 9 PowerPC Family Signals 95 Processor Specific Family Signals 95 68K Family Processors 96 80x86 Family Processors 96 PowerPC Family Processors 97 ARM Family Processors 97 SH Family Processors 98 SPARC Family Processors 102 Equivalents for the sys_clib Functions 110 The Function Description 110 Syntax 111 OS 9 Attributes 111 Library 111 Errors 111 References to Other Calls Chapter 2 Functions 113 951 Default Handling 952 Ignore Handling 952 Available Signals 952 ANSI Core Signals 953 OS 9 for 68K OS 9 Core Signals 954 680x0 OS 9 for 68K OS 9 954 680x0 OS 9 955 80x86 OS 9 Ultra C Library Reference 956 PowerPC OS 9 956 Function Handling 956 Asynchronous Signals Appendix A Prototyping sys clib Functions 1093 1094 Function Declarations and K amp R Compiler vs Prototypes and ANSI C 1096 ANSI fying Code and Function Prototypes Index 1097 Product Discrepancy Report 1195 Ultra C Library Reference 5 WX MICROWARE Ultra C Library Reference Chapter 1 Overview Ultra C library calls perform a variety of functions from classifying characters to managing memory This section contains information
232. ass 111 in the year member of the tm structure timebuf is a pointer to the time buffer If successful set ime returns a pointer to a buffer Otherwise 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also getime _os_setime _os9_setime FSSTime OS 9 for 68K Technical Manual F_STIME OS 9Technical Manual setjmp Non Local Goto Syntax include lt setjmp h gt int set jmp jmp_buf env Description set jmp is a macro which saves its calling environment in its env parameter for later use by a call to long jmp env is a program environment structure If the return is from a direct call set jmp returns zero If the return is from a call to longjmp set jmp returns a non zero value set jmp may only be used as follows The entire expression of an expression statement This may be cast to void For example void setjmp env The entire controlling expression of a selection or iteration statement For example while setjmp env One expression of a relational or equality operator with the operand an integral constant expression with the resulting expression being the entire controlling expression of a selection or iteration statement For example while 1 lt set jmp env The ope
233. at call However create allows the caller to specify the exact file attributes desired and does not truncate the file if it is already present You cannot create directories with this call instead use os makdir Note The thread enabled version of this function contains a cancel point For more information see Using OS 9 Threads Attributes Operating System State Threads Re entrant Library Sys clib l See Also os create o ms Takdir Os ss size I Create and I SetStat SS SIZE CREATE and I SETSTAT OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual OS 9Technical Manual WX MIC ROWARE crtolf Convert Carriage Return Characters to Linefeed Characters Syntax include UNIX os9def h void crtolf char buf unsigned int n Description crtolf converts all carriage return characters to linefeed characters in buf fora span of n characters Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix 1 ctime Convert Calendar Time to String Format Syntax include lt time h gt char ctime time_t t Description ctime converts the calendar time t into the following 26 byte string format including the terminating V0 xxx mmm dd hh mm ss yyyy n 0 xxx is one of the following days of the week Sun Mon Tue Wed Thu
234. at alarm h specified time intervals alm delete Remove pending alarm h alarm request alm set Send signal after alarm h specified time interval ev creat Create event events h ev delete Delete event events h 0s9 ev infol Returns event events h information in the caller s buffer ev info Get event events h information Table 1 10 Interprocess Communication Functions continued ANSI Function Standard Description Header File ev link Link to existing events h event _ev_pulse Signal event events h occurrence _ev_read Read event without events h waiting ev set Set event variable events h and signal event occurrence ev setr Set relative event events h variable and signal event occurrence _ev_signal Signal event events h occurrence ev unlink Unlink event events h ey w iti Wait for event events h ev waitr Wait for relative events h event intercept Set up process signal h signal handler os9 alarm atdate Send signal at alarm h Gregorian date time SendsignalatJulian alarm h os9 alarm atjul date time WX MICROWARE Table 1 10 Interprocess Communication Functions continued ANSI Function Standard Description Header File os alarm atime Send signal at alarm h specified time o0s alarm cycle t Send signal at alarm h specified time intervals 0 alarm delete Remove pending alarm h alarm request OS alarm reset
235. ath to new file modes h os delete Delete file modes h Table 1 9 Ultra C I O Functions continued ANSI Header Function Standard Description File _os_detach Remove device from system io h _os_dup Duplicate path modes h _os_get_ioproc Get pointer to I O process io h descriptor _os_getdl Get system I O device list io h head pointer s ioconfigi Configure an element of modes h process system I O _os_iodel Check for use of I O module module h oS ioexit s 3ofortkt _os9_ioqueue _os_makdir _os_open os _rdalst _os_read _os_readin s tranpn Terminate I O for exiting process Set up I O for new process Enter I O queue Make new directory Open path to file or device Copy system alias list Read data from file or device Read text line with editing Translate user path to system path process h process h process h modes h modes h io h modes h modes h io h WX MICROWARE Table 1 9 Ultra C I O Functions continued ANSI Header Function Standard Description File _os_write Write data to file or device modes h _os_writeln Write line of text with editing modes h pffinit Initialize for float output none obsolete pflinit Initialize for longs output none obsolete printf Formatted output stdio h putet Put next character to stdio h putchar file standard out puts Output string to file stdio h putw
236. ax include lt module h gt mh_com modloadp char modname int accessmode char namebuffer Description modloadp loads all modules in the file specified by the path modname The PATH environment variable determines alternate directories to search for the named module PATH can contain a list of directories to search if the program is not found in the module directory or the execution directory PATH is set to any number of directory pathlists separated by colons h0 cmds d0 cmds n0 droid h0 special stuff cmds modname is a pointer to the name of the module accessmode is the access mode for the module Only the lower 16 bits Of accessmode are used namebuffer is a pointer to an array containing the pathlist of the successfully loaded module Any errors other than EOS_PNNF leave the path list used for the load attempt intact namebuffer can be NULL if access to the path string is not required modloadp returns a pointer to the module if the load is successful If the load is unsuccessful 1 is returned and the appropriate error code is placed in errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also os loadp modload os load WX MICROWARE Ultra C Library Reference mq close Close a Message Queue Syntax finclude mqueue h int mq close mqd t mqdes Description mq close removes
237. ay message 201 ferror 242 format of messages 1004 map number 871 perror 871 prerr 877 print message 201 718 877 set trap handler 827 829 error message strings contents of 101 error messages format of 100 EST 84 Euclidean distance function 357 events ev creat 203 ev delete 205 ev info 206 ev link 208 ev pulse 209 ev read 211 ev set 213 ev setr 215 ev signal 217 ev unlink 219 ev wait 221 ev waitr 223 os ev allclr 573 OS ev allset 575 Os ev_anyclr 576 Os ev anyset 577 os ev change 578 OS ev creat 579 OS ev delete 581 os ev info 582 Os ev link 585 _os ev pulse 586 ABCDEFGHIJKLMNOPQRSTUVWXYZ Os ev read 588 OS ev set 589 Os ev setand 591 OS ev setor 593 Os ev setr 595 OS ev setxor 597 os ev signal 599 OS ev tstset 601 os ev unlink 603 os ev wait 604 os ev waitr 607 os9 ev wait 606 os9 ev waitr 609 create 203 579 decrement link count 219 delete 205 581 get information 206 link to existing event 208 585 read event value 588 read without waiting 211 return event information 582 set event variable 213 589 591 593 597 relative 215 595 signal event occurrence 209 213 215 217 586 589 591 593 585 597 599 unlink 219 603 wait for bits to clear 573 event to occur 221 573 575 576 577 578 601 604 606 relative event 223 607 609 events h 17 examine system global variable 336 649 942 example error file 718 for gen
238. bal variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1 See Also os makdir I MakDir OS 9 for 68K Technical Manual I MAKDIR OS 9 Technical Manual make gdesc Make Global Descriptor Table Entry Syntax finclude lt regs h gt finclude lt types h gt void make_gdesc void tbl entry addr u int32 offset u intl6 segment attr Description make gdesc makes an entry in the global descriptor table It returns a pointer to the next entry tbl entry addr is a pointer to the address of the local descriptor table or the global descriptor table offset is the offset into the global descriptor table segment attr is the segment attributes Note make gdesc is only supported by the 80x86 family of processors version of the compiler Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library cpu l WX MICROWARE make idesc Make Interrupt Descriptor Table Entry Syntax finclude lt regs h gt finclude lt types h gt void make idescq void tbl entry addr u int32 offset u intl16 segment attr u intl16 selector Description make idesc makes an entry in the interrupt descriptor table It returns a pointer to the next entry tb1 entry addr is a pointer to the interrupt descriptor table of fset is an offset into the table
239. ber of the device Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 0S ss reten Retension Pass on Tape Drive Syntax include lt sbf h gt finclude lt types h gt error_code _os_ss_reten path_id path Description _os_ss_reten performs a retention pass on the tape drive path is the path number of the tape drive Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os_lib l WX MICROWARE _os_ss rfm Skip Tape Marks Syntax include lt sbf h gt finclude lt types h gt error code _os_ss_rfm path id path int32 marks Description os ss rfm skips the number of tape marks specified in marks path is the tape drive s path number marks specifies the number of tape marks to skip If marks is negative the tape is rewound the specified number of marks Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 Os ss sendsig Send Signal on Data Ready Syntax include sg codes h finclude types h error code os ss sendsig path id path signal code signal Description os ss sendsig sets up a signal to send to a process when an interactive device or pipe has data ready os ss sendsig must be reset each time the signal is sent path specifies the path numb
240. ber of the open file If the path is invalid or the device is not an RBF device 1 is returned and the appropriate error code is placed in the global variable errno Note This call is effective only on RBF devices Do not use this call if buffered I O is being performed on the path instead use te11 Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also feel o5 ges posl ISGetStt OS 9 for 68K Technical Manual I_GETSTAT SS_POS OS 9 Technical Manual 9s rdy Test for Data Available Syntax include sg codes h int gs rdy int path Description _gs_rdy checks the device open on path to see if data is waiting to be read Read requests to the operating system wait until enough bytes have been read to satisfy the specified byte count thereby suspending the program until the read is satisfied _gs_rdy can determine the number of bytes if any waiting to be read and then issue a read request for only the number of bytes actually available If the path is invalid or no data is available to be read 1 is returned and the appropriate error code is placed in the global variable errno Otherwise the number of bytes available to be read is returned Note This call is effective only on RBF SCF or pipe devices gs rdy is not intended for use with the buffered I O calls such as getc unpredictable resu
241. butes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant Yes Library os lib l1 See Also os alarm set os9 alarm atdate os9 alarm atjul FSAlarm OS 9 for 68K Technical Manual F_ALARM OS 9 Technical Manual os9 alarm atjul Send Signal at Julian Date Time Syntax include lt alarm h gt finclude lt types h gt error_code _os9_alarm_at jul alarm_id alrm id signal code signal u int32 time u int32 date OS 9 Attributes Compatibility State Threads Compatibility Re entrant OS 9 for 68K User Safe Yes Description 0s9 alarm atjul sends a signal to the caller at a specific Julian date and time The alarm signal is sent anytime the system date time becomes greater than or equal to the alarm time alrm idis a pointer to the location where os9 alarm atjul stores the alarm ID signal specifies the signal code time is the seconds after midnight date is the Julian day number WX MICROWARE Note os9 alarm at jul only allows you to specify the time to the nearest second However it does adjust if the system s date and time have changed using _os9_setime Attributes Operating System OS 9 for 68K State User Threads Safe Re entrant Yes Library os lib l See Also FSAlarm OS 9 for 68K Technical Manual tes b dran Dataranrs Ultra O Library heterence os alarm cycle Send Signal at Specified Tim
242. c quantities according to the rules of the current locale The members of the structure with type char are pointers to strings any of which except decimal point can point to a NULL value to indicate that the value is not available in the current locale or is of zero length The members with type char are non negative numbers any of which can be CHAR MAX to indicate that the value is not available in the current locale The members include the following char decimal point The decimal point character used to format non monetary quantities char thousands sep The character used to separate groups of digits before the decimal point character in formatted non monetary quantities char grouping A string whose elements indicate the size of each group of digits in formatted non monetary quantities The string may contain the following CHAR MAX No further grouping is to be performed 0 The previous element is to be repeatedly used for the remaining digits other WX MIC ROWARE The integer value is the number of digits that comprise the current group The next element is examined to determine the size of the next group of digits before the current group char int_curr_symbol The international currency symbol that applies to the current locale The first three characters contain the alphabetic international currency symbol The fourth character immediately preceding the null character is the character used to sepa
243. cached bit map information 807 file buffer 243 fmod 60 92 255 fopen 47 256 fork process under control of debugger 565 567 569 format of error messages 100 Gregorian value 342 time and date values 342 formatted output 260 880 962 ABCDEFGHIJKLMNOPQRSTUVWXYZ fprintf 47 100 260 fputc 47 267 fputs 47 268 fread 47 269 free 62 271 freemem 272 freopen 47 276 frexp 61 278 from to process create communication pipe 874 fscanf 47 100 279 fseek 38 285 fsetpos 38 287 fstat 288 ftell 38 100 289 funcs h 17 function defined 8 fwrite 47 290 generate CRC 181 543 unique valid file name 1054 valid CRC 759 get alternate module directory pathlist 644 cache status information 655 calendar time 1051 character from file 245 I O address 360 copy of module directory 645 process descriptor block table 647 current constant data pointer 305 file position 352 671 file size 355 module directory pathlist 644 ABCDEFGHIJKLMNOPQRSTUVWXYZ position in file 246 static storage pointer 335 task segment 306 cursor movement capability 1049 device name 344 status 648 event information 206 exception table base address 310 external memory 198 file descriptor block address 664 sector 348 665 file status 332 648 free memory block map 635 global descriptor pointer 311 Gregorian date 652 I O interface edition number 661 integer from I O address 363 Julian date 690 module director
244. cant 2 bytes are the error s group number and the least significant 2 bytes are the specific error within that group preer prints a message in the form Error ggg sss where ggg is the group number of the error and sss is the specific error number within the group If path is non zero the opened error message file is searched for further text related to the error If more text is available it is printed Example prerr 0 216 function call Error 000 216 output prerr errmsg_path 216 function call Error 000 216 ESPNNF File not found output line 1 The pathlist does not lead to any known file output line 2 Attributes Operating System State Threads Re entrant Library Sys clib 1l1 See Also os perr FSPErr WX MIC ROWARE OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual _prgname Get Module Name Syntax include lt module h gt char _prgname void Description _prgname returns a pointer to the name of the calling module Normally the argv 0 string indicates the name of the program as called by the parent process with os9exec You can use _prgname todetermine the actual name of the module as it appears in the module directory Note If the code that calls prgname is executing in a trap handler the name of the trap handler module is returned Attributes Operating System OS 9 and OS 9 fo
245. cates a standard ANSI header Table 1 2 Ultra C Header Files continued File Description events h Used for functions using the OS 9 event functions events h contains prototypes for the following functions ev creat ev delete ev info ev link ev pulse ev read v set ev setr ev signal ev unlink ev wait ev waitr oS ev allc os ev allset ba os ev anyclr os ev anyset os ev change os ev creat os ev delete os ev info OoS ev link os ev pulse 6s Bv read os ew seti 05 ev setsnd os ev setor Ds eyv soctr os ev setxor OoS ev signal os ev tstset os ev unlink os ev wait oSs9 ev wait os ev waitr os9 ev waitr os9 ev info fleat h T Defines the limits for floating point numbers funcs h Symbolic names for the system calls funcs h contains a prototype for the following function _os9_setsvc Indicates a standard ANSI header WX MICROWARE Table 1 2 Ultra C Header Files continued File Description getset h io h ioctl h ioedt h limits h locale h f Used to read and set values of special purpose registers device control registers processor registers and time based registers get set h contains prototypes for the following functions get name set name Used for functions performing input output io h contains prototypes for the following
246. ck size the process requires priority is the priority at which the new process runs If priority is zero the new process receives the priority of the calling process pathcnt is the number of open paths to pass to the new process If func is os9forkc Of os9fork and the initial attempt to create the child process fails due to EOS_PNNF path name not found os9exec calls modloadp with modname to load the module from disk and attempts the fork again This action is the same as the shell handling of executable files Note If you use os9exec when unc is chain Or chainc you must either Ensure that the module is in memory or in your current execution directory See modlink modload and modloadp Provide a full pathlist to the module os9exec returns the value of func This is the ID of the child process for os9fork 1 is returned on error Note Any program that executes a C program must do so using the os9exec interface The cstart module can handle parameter strings passed by os9 fork and chain but no environment is available and the argv pointer list is separated by white space Note os9exec is not automatically available if you are using ANSI or extended ANSI modes To use os9exec in one of these modes link with sys clib l Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library
247. ck to write ilvf is the interleave factor trkbuf is a pointer to the track buffer image ilvptr is a pointer to the interleave table If an error occurs 1 is returned and the appropriate error value is placed in the global variable errno Note This feature exists only on RBF devices You can obtain additional information on actual use of this call by examining the format utility and or a device driver Attributes Operating System State Threads Re entrant Library Sys clib l See Also 08 ss wtracki I SetsStt I_SETSTAT SS_WTRACK format OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual Using OS 9 for 68K or Using OS 9 WX MICROWARE stacksiz stacksiz Get Size of Stack Used Syntax include lt stdlib h gt int stacksiz void int _stacksiz void Description stacksiz returns the maximum number of bytes of stack used at the time of the call if stack checking code is in effect You can use stacksiz to determine the stack size a program requires stacksiz is not available when compiling in strictly conforming ANSI mode Note stacksiz is historical and may be removed in a future release Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library CS EE E stat Get File Status Syntax include lt UNIX stat h gt int stat char
248. clude lt assert h gt void assert int expression Description assert is a macro that places diagnostics in programs If expression is false assert writes a message about the failed call to standard error The following message is printed Assertion failed expression file filename line line n expression is the text of the parameter filename is the name of the file containing the assert macro line is the line number of the file containing the assert macro After printing the message assert calls abort This raises the SIGABRT signal that may be handled by the application Note assert never returns a value Note If NDEBUG is defined as a macro name when the assert h header file is included assert is defined as follows define assert ignore void 0 Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library assert is a macro defined in assert h See Also abort raise signal WX MICROWARE atan Arc Tangent Function Syntax include lt math h gt double atan double x Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Description atan returns the arc tangent of x in the range 1 2 x 2 radians Library elrpul atan2 Arc Tangent Function Syntax include lt math h g
249. code os ioconfig u int32 code void param Description _os_ioconfig is a wildcard call used to configure elements of the I O subsystem which may or may not be associated with an existing path It is intended to be used to dynamically reconfigure system I O resources at runtime The target I O resources may be system wide resources or they may be process or path specific depending on the nature of the configuration call being made code is the IO configuration command code Refer to the OS 9 Technical Manual for a list of valid command codes for your version of the operating system param is a pointer to any additional parameters required by the specified configuration function Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes See Also b amp confidit WX MICROWARE os iodel Check for Use of I O Module Syntax include lt module h gt finclude lt types h gt error code os iodel mh com mod head Description _os_iodel is executed when the kernel unlinks a file manager device driver or device descriptor module It is used to determine if the I O system is still using the module mod headis a pointer to the module header Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library os lib l1 os ioexit Terminate I O for Exiting Process Syntax finclude lt process h gt finclude lt types h gt error co
250. corresponding parameter is a pointer to a short int rather than pointing to int or by 1 if itis a pointer to a long int WX MIC ROWARE The conversion specifiers o u and x are preceded by n if the corresponding parameter is a pointer to an unsigned short int rather than pointing to an unsigned int or by 1 if itis a pointer to an unsigned long int The conversion specifiers e and g are preceded by 1 if the corresponding parameter is a pointer to a double rather than pointing to a 1oat or by L if itis a pointer to a 1ong double If anh 1 or L appears with any other conversion specifier the behavior is undefined A character that specifies the type of conversion to apply The following conversion specifiers are valid Table 2 10 fscanf Conversion Specifiers Flag Description Matches a character sequence of the number specified by the field width By default the field width is one The corresponding parameter is a pointer to the initial character of an array large enough to accept the sequence No null character is added Matches an optionally signed decimal integer whose format is the same as expected for the subject sequence of st rtol The base parameter is 10 The corresponding parameter is a pointer to an integer f Matches an optionally signed floating point number whose format is the same as expected for the subject string of strtod The corresponding parameter is a pointer to a float Matche
251. creat ev link os ev creat Of os ev link ev value specifies the amount to increment the event variable allflag specifies the process es to activate Only the lower 16 bits of allflag are used e fallflag is zero the first process waiting for the event is activated e Ifallflag is 0x8000 all processes waiting for the event that have a value in range are activated OS 9 for 68K ev setr returns the value of the event before changing by ev value If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Clear the global variable errno prior to calling ev setr to distinguish between return of a prior event value of 1 and an error OS 9 ev setr returns 0 If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno WX MICROWARE For More Information Refer to your operating system technical manual for more information about events Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also ev creat ev link t os ev creat os ev link Oos ev setr FSEvent OS 9 for 68K Technical Manual F_EVENT OS 9 Technical Manual EV_CREAT OS 9 Technical Manual EV_LINK OS 9 Technical Manual EV_SETR OS 9 Technical Manual ev signal Signal Event Occurrence Syntax include
252. cters have been read into the array the contents of the array remain unchanged and a null pointer is returned If a read error occurs during the operation the array contents are indeterminate and a null pointer is returned Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library elib 1 See Also fgets WX MICROWARE getstat Get File Status Synta incl x lude lt sgstat h gt incl int getstat lude lt sg_codes h gt int int code path struct sgbuf buffer int Int int int int int long int int int long Description getstat code path getstat code path size getstat code path pos code code code code lor 6 getstat is historical from the 6809 C Compiler It accesses a few I GetStt system functions code is defined as follows Table 2 13 getstat Code Values Code Description 0 buffer is the address of the 128 byte buffer into which the path option bytes are copied The sgstat h header file contains a struct defined for use by the program 1 This applies only to SCF devices and is used to test for data ready The return value is the number of bytes available or 1 if an error occurred 2 size is the address of the long integer into which the current file size is placed The function returns 1 on error and zero on succes
253. ction has a second argument of zero 4 5 6 4 fmod returns zero if it has a second argument of zero The set of signals for the signal function 4 7 1 1 The set of signals for the signal function varies with the operating system and the processor A set of signals is also available regardless of operating system ANSI Core Signals S S IG IGABRT SEGV S S IGFP IGTE OS 9 Core Signals S S GKILL IGALRM S S E RM IGWAKE GP PE OS 9 68K Family Signals S S OS 9 80x86 Family Signals S SI SI G G IGADDR IGTRACE IGGPROT DBLFLT DBG S S S SI IGCH IG10 IGST GBNI K 10 ACK DCHK GQUIT IGUSR1 IGTRAPV IG1111 IGSEGNP IGBRKPT IGHUP IGUSR2 GPRIV GINVTSS GNM OS 9 PowerPC Family Signals SIGCHK SIGINST SIGPRIV SIGALIGN e The semantics for each signal recognized by the signal function 4 7 1 1 For More Information For information related to the exceptions see the reference manual for your specific processor supplied by the manufacturer Table 1 29 Signals Signal Condition SIGABRT Abnormal termination such as initiated by the abort function SIGFPE An erroneous arithmetic operation such as zero divide or an
254. ction in relation to OS 9 including whether the function is compatible with OS 9 and or OS 9 for 68K whether the function is in user state and or system state whether the function is safe for use in a threaded application and whether the function is re entrant Library The library field indicates the libraries that contain the function Errors When an error occurs C functions typically return an error code in the global variable errno You must include the file lt errno h gt in C programs to declare errno References to Other Calls Many functions also have a See Also section Functions listed in the See Also section are related functions or are called by the function being described 1 Overview AN MICROWARE Tue Ultra C Library Reference Chapter 2 Functions This chapter includes library function definitions in alphabetical order according to some special rules Special characters not letters numbers or underscores are listed first Function calls are listed in alphabetic order next without regard for numbers and underscores If two function calls are identical using these rules then they are alphabetized according to the following order 1 Symbols 2 Underscores 3 Alphabetic characters 4 Numbers WX MICROWARE AA MICROWARE abort Abnormal Program Termination Syntax include lt stdlib h gt void abort void Description abort abnormally terminates a program by rais
255. ction varies with the operating system and the processor A set of signals is also available regardless of the operating system ANSI Core Signals Table 2 28 ANSI Core Signals Signal Description SIGABRT Abnormal termination such as initiated by abort SIGFPE An erroneous arithmetic operation such as zero divide or an operation resulting in overflow This signal is generated on processor specific conditions SIGILL Detection of an invalid function image such as illegal instruction This signal is generated on processor specific conditions SIGINT Receipt of an interactive attention signal generated by a lt control gt c on OS 9 for 68K and OS 9 SIGSEGV An invalid access to storage This signal is generated on processor specific conditions SIGTERM A termination request sent to the program OS 9 for 68K OS 9 Core Signals Table 2 29 OS 9 for 68K and OS 9 Core Signals Signal Description SIGKILL A death request sent to the program This signal cannot be ignored or handled SIGWAKE A wakeup request sent to the program If a process is active when this signal arrives it is ignored Otherwise the process is activated but the signal handling function is not called SIGQUIT Receipt of an interactive abort signal generated by a control E on OS 9 for 68K and OS 9 SIGHUP Modem hangup signal This signal is sent to a proce
256. ctor of the file open on path into a buffer The structure fd declared in the rbf h header file provides a convenient means to access the file descriptor information path specifies the path number of the open file buffer is a pointer to the buffer in which to place the file descriptor information count specifies the maximum number of bytes to copy If an error occurs 1 is returned and the appropriate error value is placed in the global variable errno Note Be sure the buffer is large enough to hold count bytes A file descriptor is one sector in length and a sector may be between 256 bytes and 32K in size If an entire descriptor is desired you must first find the sector size on the device and allocate a buffer The sector size can be found in the path descriptor s option section See os gs popt and your operating system technical manual for more information Generally the struct fdin rbf h is only large enough to hold a 256 byte file descriptor Note This call is effective only on RBF devices Attributes Operating System State Threads Re entrant Library Sys clib l See Also 058 us rdi os gs popt XE cm TQ ISGetStt I GETSTAT SS FD OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9000 Technical Manual WX MICROWARE _gs_opt Get Path Options Syntax include lt sg_codes h gt int _gs_opt int path struct sgbuf
257. d getchar file standard input ANSI Header Function Standard Description File feof Check buffered file for end stdio of file Ferror Check buffered file for error stdio condition Fflush Flush file s buffer stdio Ftgete Get character from file stdio h fgets Get string from file stdio h fileno Determine path number stdio h Fileno from file fopen Open file stdio h Fprintf Formatted output stdio h Fputc Output character to file stdio h Fputs Output string to file stdio h fread Read data from file stdio h f reopen Re open file stdio h Fscanf Input string conversion stdio h fwrite Write data to file stdio h getet Get next character from stdio h WX MICROWARE Table 1 9 Ultra C I O Functions continued ANSI Header Function Standard Description File gets Get string from file stdio h getw Read word from file stdio h lseek Position file pointer modes h makdir Create directory modes h mknod Create directory modes h mktemp Create unique file name stdio h open Open file modes h opendir Open directory dir h os alias Create device alias io h DB attechij Attach new device to system io h 68 chdiri Change working directory modes h os close Close path to file device modes h 08s cpy ioproc Get pointer to I O process process h descriptor _os_create Create path to new file modes h _os9_create Create p
258. d If successful unlinkx returns 0 Otherwise 1 is returned and the appropriate error code is placed in the global variable errno Note OS 9 for 68K does not support multiple links to a file un 1inkx always causes the file to be removed from the disk Attempting to delete an open file by the calling or another process results in an EOS SHARE error Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1 See Also OS delete IS Delete I DELETE WX MICROWARE OS 9 for 68K Technical Manual OS 9 Technical Manual user addr Address Translation Function Syntax include lt regs h gt void user_addr void addr Description user addr returns the user state version of the specified address If the passed address is already in the user state address space or address translation is not applicable on the host processor it is returned untouched addr is the address to be converted to its user state address user_addr returns the user state version of the specified address Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library Cpu See Also System addr WX MICROWARE va arg Get Parameter in Variable Parameter List Syntax include stdarg h type va arg va list ap type Description va arg is a macro associated with the stdarg
259. d butnotmq receive A message queue may be open multiple times in the same or different processes for sending messages Open the queue for both receiving and sending messages The process can use any of the functions allowed for O_RDONLY and O_WRONLY A message queue may be open multiple times in the same or different processes for sending messages Any combination of the remaining flags may be specified in the value of oflag O CREAT This option is used to create a message queue and it requires two additional arguments mode which is of type mode t and attr which is a pointer to amq attr Structure If the pathname name has already been used to create a message queue that still exists then this flag has no effect except as noted under O_EXCL Otherwise a message queue is created without any messages in it The user ID of the message queue is set to the effective user ID of the process and the group ID of the message queue is set to the effective group ID of the process The file permission bits is set to the value of mode When bits in mode other than file permission bits are set the effect is implementation defined If attr is NULL the message queue is O EXCL O NONBLOCK created with implementation defined default message queue attributes If attr is non NULL and the calling process has the appropriate privilege on name the message queue mq maxmsg and mq msgsize attributes are set to the values of the
260. d OS 9 for 68K State User and System Threads Safe Re entrant no Standards ANSI Library clib 1 See Also cal Loc free ma rea loci llecet Ultra C Library Reference 275 WX MICROWARE freopen Re Open File Syntax include lt stdio h gt FILE freopen char name char action FILE stream Description freopen substitutes a file name for the file currently open if any The original file is closed even if the opening of the new file does not succeed freopen is usually used to associate the st din stdout or stderr file pointers with a file instead of a terminal device name is a pointer to the file name to use for a substitute action specifies the action to take Refer to fopen for details on the action values stream is a pointer to the C I O FILE structure freopen returns the stream passed or a null pointer if the open fails Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library Gl abs 1 See Also fopen Ultra C Library Reference 277 A MIC ROWARE frexp Return Portions of Floating Point Number Syntax include lt math h gt double frexp double value int exp Description frexp breaks a floating point value into a normalized fraction and an integral exponent of two rexp returns the fraction x such that 1 2 l
261. d at creation is added to the event variable ev id identifies the event value is a pointer to the location where os ev waitr stores the actual event value signal is a pointer to the location where os ev waitr stores the signal code if a signal activates the process The minimum relative activation value is passed at the location pointed to by min val min val is also a pointer to location where os ev waitr Stores the minimum absolute activation value The maximum relative activation value is passed at the location pointed to by max val max val is also a pointer to the location where os ev waitr Stores the maximum absolute activation value The event value is added to min val and max val and the actual values are returned to the caller If an underflow or overflow occurs on the addition the values 0x80000000 minimum integer and Ox7fffffff maximum integer are used respectively Attributes Operating System State Threads Re entrant Library os lib l See Also _os_ev_signal os ev wait os9 ev waitr F EVENT F EVENT EV SETOR F EVENT EV SIGNL AA MICROWARE OS 9 User and System Safe Yes OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual _os9 ev waitr Wait for Relative Event to Occur Syntax include lt events h gt finclude lt types h gt error code _os9_ev_waitr event_id ev_id int32 value int32 min val int
262. d error occurs the error indicator for the stream is set and getc returns EOF Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also getc getchar WX MICROWARE fgetpos Get Current Position in File Syntax include lt stdio h gt int fgetpos FILE stream fpos t pos Description fgetpos stores the current value of the file position indicator The stored value contains information usable by setpos for repositioning the stream to its position at the time of the get pos call stream is a pointer to the C I O FILE structure pos is a pointer to the file position indicator If successful getpos returns zero Otherwise it returns a non zero value and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib l See Also fsetpos fgetpwent Get Password File Entry Syntax include lt UNIX pwd h gt struct passwd fgetpwent FILE f Description fgetpwent returns a pointer to the next password structure in the stream which matches the format of the password file dd SYS password Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library
263. d of file r b rb Open binary file for update reading and writing wtb wb Truncate to zero length or create binary file for update a b ab Append open or create binary file for update writing at end of file d Directory read OS 9 extension this is only available in K amp R source mode Note Appending an x to any action s indicates that names are relative to the current execution directory The x also implies that the file should have the execute permission bit set This option is only available for OS 9 in non ANSI mode Note In modes other than compatibility mode appending a d to any action s indicates that the file is a directory WX MIC ROWARE mode must point to a string and not a character fopen fun r is correct fopen fun xr is not correct If the file does not exist or cannot be read opening a file with read mode fails When you open a file with append mode the file position indicator is initially positioned at the beginning of the file However all subsequent writes to the file are forced to the then current end of file regardless of intervening calls to fseek If an error occurs when opening a file with append mode refer to open Append Bit subsection in the appropriate processor specific chapter of the Ultra C C Processor Guide When a file is opened with update mode both input and output may be performed on the associated stream However output may not be
264. d of the argv list is marked by a null pointer envp is a pointer to the environment pointer list containing environment variables that the new process is to receive The end of the envp list is also marked by a null pointer datasize is the additional memory in bytes to allocate to the new process stack memory A datasize of zero indicates the default stack size required by the process The first seven parameters are identical for os fork os forkm os chain os chainm os dfork Of _os_dforkm Four additional parameters may be required add1 add2 add3 and add4 and have different meaning depending on the function specified by unc Table 2 18 os exec Additional Parameters Call Parameter Definition os fork addi Child process ID returns to the location of the add1 pointer add2 Type language of the new process add3 Orphan 0 Normal child process 1 Process not associated with parent Table 2 18 os exec Additional Parameters continued Call Parameter Definition _os_forkm addi The child process ID returns to the location of the add1 pointer add2 Orphan 0 Normal child process 1 Process not associated with parent _os_chain addi Type language of the new process _os_chainm Does not use the extra parameters _os_dfork addi Child process ID returns to the location of the add1 pointer add2 Type language of the new process add3 Pointer to register stack for child process add4
265. d returns a different synonymous path number The path descriptor is not cloned Note It is usually not a good idea for more than one process to perform I O on the same path concurrently Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library sys_clib 1 See Also 05 dupi I Dup OS 9 for 68K Technical Manual I DUP OS 9 Technical Manual dup2 Specifies the Value of Duplicated Path Syntax include UNIX os9def h int dup2 int fdl int fd2 Description dup2 returns a synonymous path number for an existing file or device and specifies the value of the new duplicated path d1 specifies the original path number d2 specifies the value of the duplicated path If path a2 is already in use it is first closed Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix 1 WX MICROWARE ebrk Get External Memory Syntax include lt stdlib h gt extern int _memmins void ebrk unsigned int size Description ebrk returns the amount of memory specified by size The memory is obtained from the system using the F SRqMem for OS 9 for 68K or _os_srqmem for OS 9 system request It is intended for general purpose memory allocation To reduce the overhead involved in requesting small quantities of memory ebrk requests memory from the system in
266. d write access When the pipe is written up to 4 KB of data are buffered before the writing process is blocked Data read from one of the paths accesses data written to either of the paths on a FIFO first in first out basis The standard programming model is that after the pipe has been set up two or more cooperating processes created by subsequent os exec Calls passes data through the pipe using read and write I O calls If an error occurs the pipe returns 1 and sets the global variable errno to indicate the error Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix 1 See Also pclose popen popen Open a Pipe From To a Process Syntax include UNIX os9def h include lt stdio h gt FILE popen char command char type Description popen opens a pipe from or to a process The arguments to popen are pointers to null terminated strings containing respectively a shell command line and an I O mode either r for reading or w for writing popen creates a pipe between the calling process and the command to be executed The value returned is a stream pointer such that you can write to the standard input of the command if the I O mode is w by writing to the file stream If the I O mode was r you can read from the standard output of the command by reading from the file stream A stream opened by popen
267. data 806 flush cached bit map information for RBF device 807 get cache status information 655 current file position 352 671 size 355 device name 344 file descriptor block address 664 descriptor sector 348 status 332 file device status 648 I O interface edition number 661 path options 350 size of SCSI device 660 specified file descriptor sector 665 GetStat call using system path number 772 getstat 332 lock outrecord 810 979 make hard link to existing file 808 notify driver that path has been closed 798 opened 812 put file descriptor sector 983 read device path options 659 file descriptor sector 663 logical unit options 668 path descriptor option section 670 release device 814 985 ABCDEFGHIJKLMNOPQRSTUVWXYZ rename file 815 restore device 986 head to track zreo 816 retension pass on tape drive 817 return amount of free space on device 667 current file size 674 device name 656 773 device type 657 file descriptor 653 send data carrier lost signal to process 975 present signal to process 976 signal on data ready 819 988 when DCD line goes false 799 true 800 set current file size 987 device path options 801 file attributes 795 971 size 820 status 940 file device status 765 path options 981 system global variables 770 setstat 940 skip blocks 821 tape marks 818 to end of tape 822 test for data available 353 data ready 673 end of file 662 wait ABCDEFGHIJKLMNOPQRSTUVWXYZ for record release 990 sp
268. date become greater than or equal to the alarm time If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno If errors do not occur a1m atdate returns the alarm ID Functions For More Information Refer to your operating system technical manual for information about alarms Attributes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant No Library Sys clib l See Also os9 alarm atdate os alarm set Ultra C Library Reference 121 IN n N ka ww WX MICROWARE alm atjul Set Alarm at Julian Date Time Syntax include lt alarm h gt int alm atjul int sigcode int time int date Description alm atjul requests that a signal be sent to the requesting process at a specific Julian date and time sigcode specifies the signal to be sent to the caller time should contain the time at which to send the signal expressed as the number of seconds after midnight date must contain the Julian date on which to send the signal The Julian date is the number of days since 1 January 4713 B C the beginning of the Julian period Note A Julian day begins at midnight on OS 9 systems Standard Julian days begin twelve hours earlier at noon For example 1 00 a m January 2 4713 B C is one hour after the beginning of Julian Day 1 for OS 9 but thirteen hours after the beginning in standard Julia
269. de os ioexit process id proc id u int32 path cnt Description os ioexit is executed when the kernel terminates or chains to a process proc id specifies the process ID path cnt specifies the number of I O paths If the most significant bit of path cnt is cleared the process default data and execution directory paths and all other open paths in the path translation table are closed The I O process descriptor is also deallocated If the most significant bit of path cnt is set the remaining bits specify the number of paths to leave open The default directory paths are not closed and the I O process descriptor is not de allocated Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os iofork Set Up I O for New Process Syntax finclude lt process h gt finclude lt types h gt error code os iofork process id par proc id process id new proc id u int32 path cnt Description _os_iofork is executed when the kernel creates a new process _os_iofork creates an I O process descriptor for the new process par proc idis the parent s process ID new proc idis the process ID of the new process path cnt is the number of I O paths Attributes Operating System OS 9 State User Threads Safe Re entrant Yes Library os lib l1 os9 ioqueue Enter I O Queue Synta fincl fincl X lude lt process h gt
270. dicator as the number of bytes from the beginning of the file for a stream This is not necessarily a meaningful measure of the number of characters written or read stream is a pointer to the C I O FILE structure If successful te11 returns the current value of the file position indicator for the stream On failure te11 returns 1L and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib l1 See Also fseek getc getchar pute putochari WX MICROWARE fwrite Write Data to File Syntax include lt stdio h gt size_t fwrite const void ptr size t size size t nmemb FILE stream Description fwrite Writes up to nmemb elements from an array to the stream The file position indicator for the stream if defined is advanced by the number of characters successfully written If an error occurs the resulting value of the file position indicator for the stream is indeterminate ptr is a pointer to the array size specifies the size of each array element nmemb specifies the number of array elements to write stream is a pointer to the C I O FILE structure fwrite returns the number of elements successfully written This is less than nmemb only if a write error is encountered A write to a text stream does not cause the
271. ding the terminating null character If the value returned is count or more the contents of dest are indeterminate Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI 1028 Library clib l See Also stromp sltroollt AA MICROWARE Ultra C Library Reference subcall Call Subroutine Module Syntax include lt module h gt void _subcall void Description subcall calls a subroutine module previously linked by Sliblink subcall expects the first two longwords in the code area following it to contain respectively The subroutine library number The function number to call Subcall retrieves these identifiers adjusts the program stack and dispatches to the subroutine library entry point with the correct global static storage configuration For More Information For more information consult the OS 9 Technical Manual Note A process can link to a maximum of sixteen subroutine libraries numbered from 0 to 15 Attributes Operating System State Threads Re entrant Library clib l See Also _sliblink OS 9 User and System Safe Yes WX MICROWARE sys mktime Convert Local Time to Greenwich Mean Time Syntax include lt time h gt time_t sys_mktime struct tm tp Description sys_mktime converts the local time values in a broken down time structure int
272. dir rewinddir telldrir WX MICROWARE select Synchronous I O Multiplexing Syntax include lt UNIX os9types h gt finclude lt types h gt int select unsigned int width fd_set readfdas fd set writefds fd set exceptfds struct timeval timeout Description select examines the path sets whose addresses are passed in readfds writefds and except fds to see if some of their paths are ready for reading ready for writing or have an exceptional condition pending width is the number of bits to be checked in each bit mask that represent a path The paths from 0 through width 1 in the descriptor sets are examined width is in the range 1 FD SETSIZE The total number of ready paths in all the sets is returned The macros FD SET FD CLR FD ISSET and FD ZERO have been defined in os9types h to manipulate these d set structures If timeout is not a NULL pointer it specifies a maximum interval to wait for the selection to complete If timeout is a NULL pointer the select blocks indefinitely To effect a poll the timeout argument should be a non NULL pointer pointing to a zero valued t imeval structure Any readfds writefds and except fds may be given as NULL pointers if no paths are of interest select returns a non negative value on success A positive value indicates the number of ready paths in the path sets Zero indicates that the time limit referred to by timeou
273. directly followed by input without an intervening call to 1ush orto a file positioning function fseek fsetpos or rewind Likewise input may not be directly followed by output without an intervening call to a file positioning function unless the input operation encounters end of file When opened a stream is fully buffered only if it does not refer to an interactive device The error and end of file indicators for the stream are cleared Three file pointers are available and are considered open the moment the program runs stdin standard input I O is to path 0 stdout standard output I O is to path 1 stderr standard error I O is to path 2 These macros are defined in the stdio h header file Note You cannot open a directory for writing with open Example Examples using fopen are found in Table 2 6 Table 2 6 fopen Examples fp fopen fred wx Creates a file for writing in the execution directory fp fopen moe r Opens an existing file for reading fp fopen stooge curly w Creates a file for reading and writing Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library elabal See Also creat fflush fseek getc getchar open os create _os9_create _os_open putec putchar WX MIC ROWARE fprintf Formatted Output Syntax include lt stdio h gt int fprint
274. dmada2 DCR dmada3 DCR 7 E dmasa0 DCR x dmasal DCR g dmasa2 DCR E dmasa3 DCR G dmasr DCR dmiss SPR dpdr SPR dsisr SPR Reference Ilt f Ultra Lib Table 2 12 get lt name gt Valid Names and Associated Processors continued name ear ecr eid eie esr evpr exier exisr fpecr fpscr hashl hash2 hido hid2 Bu Dalaran rary Reference Register Processor s Type 403 505 601 603 User Writable SPR SPR SPR SPR SPR SPR DCR DCR SPR PREG SPR SPR SPR e SPR SPR SPR WX MICROWARE Table 2 12 get lt name gt Valid Names and Associated Processors continued Register Processor s name Type 403 505 601 603 User Writable hid5 SPR d iabr SPR iacl SPR iac2 SPR ibatOl SPR d ibat0u SPR a g ibatll SPR ibatlu SPR M d ibat21 SPR ibat2u SPR ibat3l SPR 7 x ibat3u SPR g g icadr SPR s icer SPR s iccst SPR icdat SPR i QQ Mhea f I theany E N FE P JO Ult G ary ReTerence ES Ultra C Lib Table 2 12 get lt name gt Valid Names and Associated Processors continued lt name gt icmp Teter imiss iocr letri lctrl2 mq nri msr pbu1 pbu2 pir pit rary Reference Register Processor s Type 403 505 601 603 User Writable SPR e SPR SPR DCR
275. ds Safe Re entrant Yes Library os _lib l See Also os link _os9_getime FSSTime OS 9 for 68K Technical Manual WX MICROWARE OS setpr Set Process Priority Syntax finclude lt process h gt finclude lt types h gt error code os setpr process id proc id u int32 priority Description _os_setpr changes the process priority to the value specified by priority A super user group ID zero may change any process priority A non super user can only change the priorities of processes with the same user ID proc idis the process ID priority specifies the new priority 65535 is the highest priority 0 is the lowest Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 See Also FSSPrior OS 9 for 68K Technical Manual F SPRIOR OS 9 Technical Manual _os_setstat Set File Device Status Syntax include lt sg_codes h gt finclude lt types h gt error_code _os_setstat path_id path u_int32 code void pb Description _os_setstat is a wildcard call used to handle individual device parameters that are not uniform on all devices or are highly hardware dependent path is the path number code is the Set Stat code Only the lower 16 bits of code are used pb is a pointer to the parameter block The exact operation of this call depends on the device driver and file manager associated with the
276. dule h int ere void Dif unsigned int count int accum Description crc generates or checks the CRC cyclic redundancy check values of sections of memory Compilers assemblers and other module generators use crc to generate a valid module CRC ptr is a pointer to the data count specifies the byte count for the data The CRC accumulator is passed at the location pointed to by accum crc also stores the updated CRC accumulator at the location pointed to by accum To generate the CRC for a module 1 Initialize the accumulator to 1 Oxffffffff Perform the CRC over the module Call crc with a NULL value for ptr Complement the CRC accumulator S oe deer qu Write the contents of the accumulator to the module For More Information Refer to your operating system technical manual for more information on how your operating system uses CRCs for modules Attributes Operating System State Threads Re entrant Library Sys clib 1l1 See Also E Pret FSCRC F CRC Example WX MICROWARE OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual The following code fragment illustrates a technique for generating a CRC for a module include lt stdio h gt include lt module h gt main char ptr int count accum 1 one or more calls to crc erc ptr count amp accum The final call to crc At
277. dule name params is a pointer to the parameter block param size specifies the size of the parameter block WX MICROWARE mem size specifies any additional stack space to allocate mem size is specified in bytes proc idis a pointer to the location where os dfork stores the child process ID type lang specifies the desired type and language Only the lower 16 bits of type lang are used reg stack is a pointer to the register buffer freg stack is a pointer to the floating point register buffer Attributes Operating System OS 9 State User Threads Safe Re entrant Yes Library os lib l See Also o8 dexat bos forki oso dforkit OS dexec FSDExit OS 9 Technical Manual F DFORK OS 9 Technical Manual os9 dfork Fork Process Under Control of Debugger Syntax include lt dexec h gt finclude lt types h gt error_code _os9_dfork u_int32 priority u_int32 path cnt char mod name void params u int32 param size u int32 mem size process id proc id u int32 type lang void reg buf Description _os9_dfork creates a new process which becomes a child of the caller It sets up the new process memory MPU registers and standard I O paths In addition os9 dfork allows a debugger utility to create a process whose execution can be closely controlled The process is not placed in the active queue but is left in a suspended state This allows the debugger to control its executio
278. e stream is a pointer to the C I O FILE structure If stream is a null pointer flush performs this flushing action on all streams opened in either write or update mode and containing unwritten data fflush returns EOF if a write error occurs or if the stream is read only Otherwise it returns zero Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also fopen getc getchar puteo putchar WX MICROWARE ffs Find First Set Bit Syntax finclude UNIX os9def h int ffs unsigned int i Description ffs finds the first bit set in the argument passed to it and returns the index of that bit Bits are numbered starting at one 1 from the least significant A return value of zero indicates that the value passed to the function was zero Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l fgetc Get Character from File Syntax include lt stdio h gt int fgetc FILE stream Description fgetc returns a character as an unsigned converted to an int from the file and advances the associated file position indicator for the stream if defined stream is a pointer to the C I O FILE structure If the stream is at end of file the end of file indicator for the stream is setand fgetc returns EOF If a rea
279. e double num Description modf breaks value into integral and fractional parts each of which has the same sign as the parameter It stores the integral part as a double in num value is a real number num is a pointer to the integer portion of value modf returns the signed fractional part of value Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 modlink Link to Memory Module Syntax include lt module h gt mh com modlink char modname int typelang Description modlink searches the module directory for a module with the same name as that pointed to by modname and links to it provided that typelang matches the respective value of Type Language in the module If the module is found the module s link count is incremented by one modname is a pointer to the name of the module typelang is the type and language value of the module If any module type or language is acceptable specify zero for typelang Only the lower 16 bits of typelang are used The module h header file contains a structure appropriate for accessing the elements of system defined memory modules If the link is successful modlink returns a pointer to the module If the link fails 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User a
280. e new size is larger the value of the newly allocated portion of the object is indeterminate ptr is a pointer to the old block of memory If ptr is a null pointer realloc behaves like malloc for the specified size Otherwise if ptr does not match a pointer earlier returned by calloc malloc O0rrealloc orifthe space has been deallocated by a call to free lfree realloc Or lrealloc the behavior is undefined size is the size of the new block of memory If the space cannot be allocated pt x is unchanged If size is zero and ptr is not a null pointer the object pt x points to is freed realloc returns either a null pointer or a pointer to the possibly moved allocated space Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also callocti free lealloge lfree lrealloc malloc realloc Ultra C Library Reference 899 WX MICROWARE regcomp Regular Expression Handler Syntax include lt UNIX regexp h gt regexp regcomp char str Description regcomp compiles a string st x into an internal form suitable for pattern matching with regex regex matches a compiled regular expression against a string regcomp returns a pointer to the compiled regular expression Otherwise a string containing an error message is returned If an error occurs the func
281. e 645 697 os altmdir 518 os chain 526 os chainm 528 os chmdir 534 os fmod 627 os iodel 682 os link 697 os linkm 699 os load 700 os loadp 702 os makmdir 706 os modaddr 710 ABCDEFGHIJKLMNOPQRSTUVWXYZ _os_slink 786 _os_slinkm 788 Os tlink 840 _os_tlinkm 842 os unlink 849 os unload 850 os vmodul 851 _os9_vmodul 852 prgname 879 Setcrc 927 _subcall 1029 calculate CRC 181 call subroutine module 1029 chain 155 chainc 155 change module directory 534 check CRC 851 852 for use of I O module 682 parity 851 852 crc 181 create 441 module directory 706 establish alternate working directory 518 execute 155 526 528 find 710 directory entry 627 get copy of module directory 645 name 879 initialize static storage 678 install system state trap handler 840 user Subroutine library module 788 user Subroutine module 786 user trap handler 842 link to 699 702 load 155 702 from file 700 locate 710 make_module 441 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z munlink 494 munload 495 re validate CRC 927 set alternate working directory 518 unlink by address 849 by name 850 from 494 unload 495 update CRC 927 header parity 927 verify 851 852 module directory get module dir 313 os cmdperm 537 os delmdir 558 os fmod 627 os get mdp 644 os get moddir 645 os makmdir 706 change permissions 537 change process current 534 create 706 delete 558 find entry
282. e Intervals Syntax include lt alarm h gt finclude lt types h gt error_code _os_alarm_cycle alarm_id alrm id signal code signal u int32 time Description os alarm cycle sends a signal after the specified time interval has elapsed and then resets the alarm This provides a recurring periodic signal The time interval may be specified in system clock ticks or if the high order bit is set the low 31 bits are considered a time in 256ths of a second The minimum time interval allowed is 2 system clock ticks a1rm id is a pointer to the location where os alarm cycle stores the alarm ID signal is the signal code of the signal to send t ime specifies the time interval between signals Attributes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant Yes Library os lib l See Also os alarm set FSAlarm OS 9 for 68K Technical Manual F_ALARM A_CYCLE OS 9 Technical Manual WX MICROWARE os alarm delete Remove Pending Alarm Request Synta fincl fincl X Lude lt alarm h gt lude lt types h gt error code os alarm delete alarm id alrm id Description os alarm delete removes a cyclic alarm or any alarm that has not expired alrm id specifies the alarm to remove If a1rm idis zero all pending alarm requests for the owner are removed Attributes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant Yes Libra
283. e OPT_PROTOS during the compile Table 1 14 Miscellaneous Functions ANSI Function Standard Description Header File assert Place diagnostics in assert h programs change static Change current static regs h storage pointer _cmpnam Compare two strings strings h _errmsg Print error message stdio h get_static Return current static storage regs h pointer getuid Determine user ID number process h localeconv Numeric formatting locale h convention inquiry long jmp Non local goto set jmp h os9 allbit Set bits in bit map memory h os cache Cache control cache h _os_config Configure an element sysglob h os cmpnam Compare two names strings h WX MICROWARE Table 1 14 Miscellaneous Functions continued Function iam Description Header File _os9_delbit Deallocate in bit map memory h os dexec Execute debugged program dexec h Jos dexit Exit debugged program dexec h _os9_findpd Find fixed block of memory process h _os_getpd Find path descriptor io h OS 9 penis _os_perr _os_prsnam _os9_retpd os scache _os9_schbit os setsvc _os9_setsvc os setuid Dos Strap System catastrophic occurrence Print error message Parse path name Return fixed block of memory Cache control Search bit map for free area Service request table initialization Service request table initialization Set user ID number Set error trap h
284. e OS 9 68K family signals sent when their associated exception occurs are identified in Table 1 31 Table 1 31 OS 9 68K Family Exception Signals Signal Exception SIGADDR Address Error SIGCHK CHK Instruction SIGTRAPV TRAPV Instruction SIGPRIV Privilege Violation SIGTRACE Trace SIG1010 Line 1010 Emulation SIG1111 Line 1111 Emulation Ultra C Library Refer co WX MICROWARE 80x86 Family Processors The OS 9 80x86 family signals shown in Table 1 32 are sent when their associated exception occurs Table 1 32 OS 9 80x86 Family Exception Signals Signal Exception SIGGPROT General Protection SIGSTACK Stack Exception SIGSEGNP Segment Not Present SIGINVTSS Invalid TSS SIGDBLFLT Double Fault SIGBNDCHK Bounds Check SIGBRKPT Breakpoint SIGNMI Non Maskable Interrupt SIGDBG Debug Exceptions PowerPC Family Processors The OS 9 PowerPC family signals shown in Table 1 33 are sent when their associated exception occurs Table 1 33 OS 9 PowerPC Family Exception Signals Signal Exception SIGCHECK Machine Check SIGINST Instruction Access Table 1 33 OS 9 PowerPC Family Exception Signals Signal Exception SIGPRIV Privilege Violation SIGALIGN Alignment ARM Family Processors The OS 9 ARM family signal shown in Table 1 34 is sent when its associated exception occurs Table 1 34 OS 9 ARM Family Exception Signals Signal Exception SIGALIGN Alignment SH Family Proce
285. e Ultra C libraries contain the functions listed in Table 1 3 for communicating with the environment Table 1 3 Environment Communications Functions ANSI Function Standard Description Header File abort Abnormal program stdlib h termination atexit Register function to call at stdlib h normal program termination exit Task termination stdlib h exit Task termination stdlib h getenv Get value for environment stdlib h name os exit Terminate calling process process h system Shell command execution stdlib h WX MICROWARE Character Classification Functions The character classification functions are really macros defined in lt ctype h gt Be careful when using these macros to avoid macro expansion side effects The macros provide a platform independent method of character classification Table 1 4 identifies character classification functions Table 1 4 Character Classification Functions ANSI Header Function Standard Description File isalnum Test if parameter is ctype h alphanumeric isalpha Test if parameter is alphabetic ctype h isasciilt Test if parameter is ASCII ctype h isascii iscntrl Test if parameter is control code ctype h isdigit Test if parameter is digit ctype h isgraph Test if parameter is printing ctype h character iajis kanail Test if parameter is ctype h Hankaku Kana islower Test if parameter is lowercase ctype h isprint Test if para
286. e further checking needs to be done WX MICROWARE Header Files Most of the Ultra C library calls are declared in header files A header file declares a set of related functions and includes any necessary types and additional macros needed to use the functions The contents of these header files are available through the include preprocessing directive Header files may be included in any order Ultra C provides the following header files Table 1 2 Ultra C Header Files File Description alarm h Used by functions that use the OS 9 alarm functions alarm h contains prototypes for the following functions alm atdate alm atjul alm cycle alm delete alm set 059 alarm atdate os alarm atime os9 alarm atjul os alarm cycle os alarm delete 05 alarm reseti os alarm set os9 salarm atdate os salarm atime os9 salarm atjul os salarm cycle os9 salarm cycle os salarm delete 05 salarm reset os salarm set 0o59 salarm set i assert h f Defines the assert macro assert h contains prototypes for the following function assert Indicates a standard ANSI header Table 1 2 Ultra C Header Files continued File Description aton h cache h edr h OS 9 for 68K only cglob h ctype h t Used for converting alphabetic characters to numeric values aton h contains prototypes for the following function aton Defines the CPU internal c
287. e of digits optionally containing a decimal point character WX MICROWARE An optional exponent part but no floating suffix If the subject sequence has the expected form the character sequence starting with the first digit or the decimal point character whichever occurs first is interpreted as a floating constant Currently only the C locale is supported Therefore the decimal point character is a period If neither an exponent part nor a decimal point character appears a decimal point is assumed to follow the last digit in the string If the subject sequence begins with a minus sign the value resulting from the conversion is negated A pointer to the final string is stored in end unless end is a null pointer If the subject sequence is empty or does not have the expected form no conversion is performed begin is stored in end unless end is a null pointer strtod returns the converted value if any If no conversion could be performed zero is returned If the correct value is outside the range of representable values plus or minus HUGE VAL is returned according to the sign of the value and ERANGE is stored in errno If the correct value would cause underflow zero is returned and ERANGE is stored in errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib l See Also isspace SEE OL strtoul Possible Error ERANGE
288. echnical Manual WX MICROWARE change const Change Current Static Storage Pointer Syntax finclude lt regs h gt void change const void constptr Description change const changes the current constant data pointer and returns the previous constant data pointer constptr is the value of the new constant data pointer Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library cpu l change static Change Current Static Storage Pointer Syntax finclude lt regs h gt void change static void dest stat Description change static changes the current static storage pointer and returns the address of the previous static storage dest stat is a pointer to the new static storage Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library cpu l A MICROWARE chdir Change Current Data Directory Syntax include modes h int chdir char dirname Description chdir changes the current data directory for the calling process dirname is a pointer to a string containing a path name for the directory chdir returns zero after a successful call If dirname is not a directory path name or some other error occurs 1 is returned and the appropriate error code is placed in the global variable errno Note chdir changes the data directory only for the program containing the f
289. ecified number of ticks for record release 823 write file descriptor sector 805 logical unit options 811 option section of path descriptor 813 tape marks 824 track 825 992 stdarg h 29 stdde h 29 stdio h 30 stdlib h 31 store current value of file position indicator 246 strcat 81 998 strchr 81 999 stremp 81 1000 strcoll 81 1001 strcpy 81 1002 strcspn 81 1003 strerror 81 strftime 81 88 1005 1007 strhcpy 81 108 1008 string break into tokens 1019 catenate 998 1010 compare 175 1000 1001 1011 compute length 1015 convert to double 1017 long 1021 1024 copy 1002 1012 old OS 9 strings 1008 determine length 1009 findnstr 250 findstr 252 get from file 331 length 1003 index 361 input conversion 279 locate 999 ABCDEFGHIJKLMNOPQRSTUVWXYZ first occurrence of 1013 1016 last occurrence of 1014 output to file 268 886 return next option letter getopt 315 search for character in 361 search for first instance of pattern 252 search for first occurrence of pattern 250 strcat 998 strchr 999 strcmp 1000 strcoll 1001 strcpy 1002 strcspn 1003 strhcpy 1008 strlen 1009 strncat 1010 strncmp 1011 strncpy 1012 strpbrk 1013 strrchr 1014 strspn 1015 strstr 1016 strtod 1017 strtok 1019 strtol 1021 strtoul 1024 strxfrm 1027 transform 1027 string handling functions break string into tokens 82 1019 compute string length 82 1015 copy old OS 9 str
290. ectory Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l See Also F ALTMDIR OS 9 Technical Manual os aproc Insert Process in Active Process Queue Syntax finclude process h finclude lt types h gt error code os aproc process id proc i93 Description os aproc inserts the process specified by proc id into the active process queue so that it may be scheduled for execution Attributes Operating System OS 9 and OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l See Also 08 nproc i FSAProc OS 9 for 68K Technical Manual F ALLPRC OS 9 Technical Manual WX MICROWARE _os9_aproc Insert Process in Active Process Queue Syntax finclude lt process h gt finclude lt types h gt error code os9 aproc pr desc proc desc Description os9 aproc inserts a process into the active process queue so that it may be scheduled for execution proc desc is a pointer to the process descriptor Attributes Operating System OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l See Also 08 nproci FSAProc OS 9 for 68K Technical Manual os attach Attach New Device to System Syntax include lt io h gt include lt modes h gt finclude lt types h gt error code _os_attach char name u int32 mode dev list gev tbl Descript
291. ed mod_head is a pointer to the module The module image must start on a longword address or an exception may occur WARNING Although os setcrc and_setcrc functions update the header and crc of a module in memory the copy of the module header in the module directory is not affected Therefore you have an invalid module directory entry for the memory module with the new CRC and an error 236 results if links to the module are attempted Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also QS Pre 1 WX MICROWARE _os_setime Set System Time Syntax include lt time h gt finclude lt types h gt error code os setime u int32 time Description _os_setime sets the current system time and starts the system real time clock to produce time slice interrupts Only super users may set the time time is stored as the number of seconds since a specific date in Greenwich Mean Time t ime is the desired current time in Greenwich Mean Time For More Information To determine the specified date reference the applicable manual OS 9 for 68K Technical Manual or OS 9 Technical Manual On OS 9 for 68K the binding for this call performs conversions which allow compatibility with OS 9 If speed is a consideration refer to _os9_setime The time is not validated in any way If time is zero on systems with a batt
292. ed version of this function contains a cancel point For more information see Using OS 9 Threads Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also ki110 os sleep os9 sleep sleep FSSleep OS 9 for 68K Technical Manual F_SLEEP OS 9 Technical Manual WX MICROWARE pclose Close a Pipe from to a Process Synta finc fincl int pclose FI X lude UN X os9def h lude stdio h Description LE stream pclose closes a pipe from or to a process that was opened by popen pclo and returns the exit status of the command se waits for the associated process to terminate Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l See Also popen perror Map Error Number Syntax include lt stdio h gt void perror const char chptr Description perror maps the error number in errno to an error message chptr is a pointer to a character If chptr is not a null pointer and the character pointed to by chptr is not a null character perror writes a sequence of characters to the standard error stream The sequence written contains chpt r a colon a space and an appropriate error message string followed by a newline character The contents of the error message strings are the same as those returned
293. eemem to return a correct result freemem is historical avoid using it in new code as it is likely to be removed in a future release These calls are not available when compiled in strictly conforming ANSI mode Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library CStoartsr See Also Stacksi2 stacksizi Ultra C Library Reference 273 WX MICROWARE freemin Set Memory Reclamation Bound Syntax include lt stdlib h gt void _freemin int size Description _freemin allows you to set the minimum size for a free block of memory or concatenation of free blocks for free to return to the operating system If a program is known to use a lot of memory you can instruct free never to return memory to the operating system size is the minimum size for a free block of memory or the concatenation of free blocks If size is positive it is used as the minimum number of bytes for a free block of memory to be a candidate for return to the operating system e If size is negative free never tries to return memory allocated by the ANSI memory allocation functions calloc malloc or realloc to the system You do not need to use reemin to return memory to the system The default minimum size to return is 4K _freemin ignores any specified non negative size smaller than 4K Attributes Operating System OS 9 an
294. eg CPU Family h header file for the target processor If a particular application needs to access the contents of the process context it may use the size of these structures for indexing Alternatively the application can determine the size of the FPU context at runtime by accessing the kernel globals field d pusize which contains the size of the FPU context Attributes Operating System State Threads Re entrant Library os lib l See Also _os_sigmask _os_send WX MICROWARE OS 9 User Safe Yes os sigmask Mask Unmask Signals During Critical Code Syntax include signal h include lt types h gt error code os sigmask int32 mode Note The only function that os sigmask provides in system state processes is to wake up that process It does not interrupt code that is currently executing Description _os_sigmask enables signals to reach the calling process or disables signals from reaching the calling process If a signal is sent to a process whose mask is disabled the signal is queued until the process mask becomes enabled mode is the process signal level Table 2 22 os sigmask Parameter Mode Values If Mode Is The Mask Level Is 0 Cleared 1 Set or incremented 1 Decremented WX MICROWARE Note Signals are analogous to hardware interrupts and should be masked sparingly Attributes Operating System OS 9 and OS 9 for 68K State U
295. egins in the initial shift state wcstombs stores these multibyte characters stopping if a multibyte character would exceed the limit of maxnum total bytes or if a null character is stored Each code is converted as if by a call to wct omb except that the shift state of wctomb is not affected str is a pointer to the string in which to store the multibyte characters pwcs is a pointer to the array from which to read maxnum specifies the maximum number of bytes to convert No more than maxnum bytes are modified in str If copying takes place between overlapping objects the behavior is undefined If a code is encountered that does not correspond to a valid multibyte character wcstombs returns size t 1 Otherwise wcstombs returns the number of bytes modified not including a terminating null character if any wcstombs is supported for both the C and JAPAN locales Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI WX MICROWARE Library clib l See Also wctomb 1084 Ultra C Library Reference wctomb Convert Wide Character to Multibyte Character Syntax include lt stdlib h gt int wctomb char STL wchar t wchar Description wctomb determines the number of bytes needed to represent the multibyte character corresponding to the code whose value is wchar This includes any change in shift state wctomb stores
296. em Threads Safe Re entrant Yes Library os lib l os9 gs free Return Amount of Free Space on Device Syntax include sg codes h finclude lt types h gt error code os9 gs free path id path u int32 free Description 0S9 gs free returns the amount of free space on a device path specifies the path number of the device free is a pointer to the location where os9 gs free stores the amount of free space The amount of free space is specified in bytes Note _os9_gs_free is only supported by the NRF file manager Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os gs luopt Read Logical Unit Options Syntax include sg codes h finclude lt types h gt error code os gs luopt path id path u int32 size void luopts Description _os_gs_luopt copies the contents of the logical unit options for a path into the buffer pointed to by 1uopts path specifies the driver s path number The size of the buffer is passed at the location pointed to by size _os_gs_luopt also stores the actual number of bytes copied at the location pointed to by size size may not be less than the size of the file manager s logical unit option section luopts is a pointer to your buffer Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library
297. emove 50 100 903 rename file 815 904 rename 50 100 904 re open file 276 report file pointer position 289 reposition file pointer 285 753 ABCDEFGHIJKLMNOPQRSTUVWXYZ request internal memory 358 system memory 792 reset alarm clock 744 existing alarm request 511 position of directory stream 906 signal intercept context stack 779 resize current process signal queue block 781 data memory area 707 memory block 434 898 resource lock os acglk 79 502 os caglk 79 525 os crik 79 549 os ddlk 79 552 Os dellk 79 557 _os_rellk 80 729 Os waitlk 80 857 acquire 79 502 activate 80 857 conditionally acquire ownership of 79 525 create 79 549 deadlock situation 79 552 delete descriptor 79 557 get ownership 502 list of functions 79 release ownership 80 729 restore device 986 head 816 interrupt level 374 retension tape drive 817 return amount of free space on device 667 character 245 current file size 674 interrupt level 375 location 1041 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z static storage pointer 335 data for memory map 672 device name 656 773 type 657 event information 582 exception table base address 310 file desriptor 653 pointer to zero 905 fixed block of memory 730 free 271 from interrupt exception 731 memory 271 420 parent process ID 319 parts of real number 466 pointer 893 portions of floating point number 278 process ID 318 quotient and remainder 193 random integer 890
298. entifier This is usually a system call function code Only the lower 16 bits of acct code are used proc desc is a pointer to the current process descriptor Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 os unlink Unlink Module by Address Syntax include module h finclude lt types h gt error code os unlink mh com mod head Description os unlink informs the system that the calling process no longer needs the module and decrements the module s link count mod headis a pointer to the module header Note Some modules such as device drivers in use and all modules included in the bootfile cannot be unlinked Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 See Also os unloadt FSUnLink OS 9 for 68K Technical Manual F_UNLINK OS 9 Technical Manual WX MICROWARE _os_unload Unlink Module by Name Syntax include lt module h gt finclude lt types h gt error_code _os_unload char mod name u int32 type lang Description os unload locates the module specified by mod name in the module directory and decrements its link count mod name is a pointer to the module name type lang specifies the module s type and language Only the lower 16 bits of type 1ang are used Library os lib l1 Att
299. er of the process receiving the signal signal specifies the signal to send Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also oS ss relea WX MICROWARE OS SS Size Set File Size Syntax include sg codes h finclude lt types h gt error code os ss size path id path u int32 size Description OS SS size sets the size of the file associated with path to the specified size path is the file s path number size is the size of the file in bytes Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 os ss skip Skip Blocks Syntax include lt sbf h gt finclude lt types h gt error code _os_ss_skip path_id path int32 blocks Description os ss skip skips the specified number of blocks path is the path number of the tape drive blocks specifies the number of blocks to skip If blocks is negative the tape is rewound the specified number of blocks Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os ss skipend Skip to End of Tape Syntax include lt sbf h gt finclude lt types h error code _os_ss_skipend path_id path Description _os_ss_skipend skips the tape to the end of data This enabl
300. erating CRC 182 initialization table 766 768 827 of errmsg 202 of get process desc 320 of julian 412 of os exec 615 ABCDEFGHIJKLMNOPQRSTUVWXYZ of os getsys 650 of sysdate 1035 of fopen 259 of index 361 of intercept 366 of os9exec 620 of os9kexec 696 of rindex 907 of strtok 1020 of vfprintf 1074 exception table set base address 929 set_excpt_base 929 exec interfaces execl 225 execle 227 execv 229 230 execvp 231 execl 225 execle 227 execute 561 module 526 528 new module 155 shellcommand 1037 system state subroutine 746 at Gregorian date time 733 at Julian date time 736 execv 229 230 execvp 231 exit debugged program 564 exit 35 233 status returned by 101 exp 60 235 expand value to integral constand expression 497 exponential function 235 extend data memory segment 909 external memory 542 ABCDEFGHIJKLMNOPQRSTUVWXYZ fabs 60 236 fclose 46 237 fdopen 104 fdopen 46 104 239 feof 47 241 ferror 47 242 fflush 47 243 ffs 244 fgetc 47 245 fgetpos 38 100 246 fgetpwent 247 fgets 47 248 file 883 _fileno 249 _gs_pos 352 _gs_size 355 os close 535 Os create 545 os delete 555 Os getstat 648 os gs fdaddr 664 Os gs pos 671 os gs size 674 os open 713 os read 726 OS setstat 765 OS ss attr 795 os ss hdlink 808 _os_ ss rename 815 OS Ss size 820 OS write 859 _os9 create
301. erforms the same action as write but gathers the output data from the 1ovcnt buffers specified by the members of the iov array iov 0 iov 1 iov iovcnt 1 lfiovent is zero any iov len member of a passed iovec structure is less than zero or all the iov 1en members of the passed iovec structures are Zero writev returns 1 and sets the global variable errno For writev the iovec structure is defined as follows struct iovec caddr t iov base int iov len by Each iovec entry specifies the base address and length of an area in memory from which data should be written writev always writes a complete area before proceeding to the next Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix l WX MICROWARE 1092 Ultra C Library Reference Appendix A Prototyping sys clib 1 Functions Before this topic is discussed in depth it is important to note that the primary purpose of sys clib 1is to provide a library for compatibility with the Microware K amp R C compiler This allows people who wrote code for that compiler to use the Ultra C C ANSI C compiler without altering their original code Note It is strongly recommended that when writing new code a programmer not use the sys c1ib library functions Table 1 37 provides a table to look up equivalent functions for the sys clib functions WX MICROWARE WX MIC ROWARE
302. erify that a file exists Only the lower 16 bits of perm are used If the file cannot be accessed 1 is returned and the appropriate error code is placed in the global variable errno Note The perm value may not be compatible with other systems Attributes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant Yes Standards ANSI Library Sys clib l1 acos Arc Cosine Function Syntax include lt math h gt double acos double x Description acos returns the arc cosine of x inthe range of O x radians A domain error EDOM stored in errno occurs for parameters not in the range 1 1 On error acos returns HUGE VAL Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 Possible Error EDOM WX MICROWARE alarm Sends signal SIGALRM Syntax include UNIX os9def h unsigned int alarm unsigned int seconds Description alarm requests that a signal be sent to the requesting process after a specified number seconds of seconds Unless caught or ignored the signal terminates the process alarm sends signal SIGALRM when the alarm expires al clock If the argument is 0 any alarm request is canceled Larm requests are not stacked successive calls reset the alarm alarm returns 1 and sets the global value errno if an error occurs Att
303. erminal capability 83 1047 terminal capability ID 83 1046 list of 83 output capability string 83 1060 tgetent 83 1043 tgetflag 83 1045 tgetnum 83 1046 tgetstr 83 1047 tgoto 83 1049 tputs 83 1060 terminal name find isatty 382 terminate exit 232 calling process 621 I O for exiting process 683 program 233 task 232 233 termio h 33 termlib 11 test _isascii 380 _isjis_kana 387 389 393 issjist 401 _issjis2 403 ABCDEFGHIJKLMNOPQRSTUVWXYZ error indicator 242 for alphabetic character 378 alphanumeric 376 ASCII 380 control code 383 data available 353 data ready 673 digit 385 end of file 241 662 Hankaku kana 387 389 393 hexadecimal 409 Kanji 401 403 lowercase 395 printable character 397 printing character 391 punctuation 399 uppercase 407 white space 405 isalnum 376 isalpha 378 isascii 380 iscntrl 383 isdigit 385 isgraph 391 islower 395 isprint 397 ispunct 399 isspace 405 isupper 407 isxdigit 409 tgetent 83 1043 tgetflag 83 1045 tgetnum 83 1046 tgetstr 83 1047 tgoto 83 1049 time _os9 alarm atdate 504 os9 alarm atjul 507 broken down structure 1031 get current 337 ABCDEFGHIJKLMNOPQRSTUVWXYZ place formatted time in buffer 1005 1006 send signal at Julian date time 507 time functions _gregorian 87 342 _julian 87 411 os getime 87 638 _os_gregorian 88 652 os julian 88 690 os setime 88 760 _os9 getime 88
304. ersion or assignment occurs The complete conversion specification is The conversion specifiers E G and x are also valid and behave the same as respectively e g and x If a conversion specification is invalid the behavior is undefined fscanf executes each directive of the format in turn If a directive fails scanf returns Failures are described as input failures or matching failures Aninput failure is caused by the unavailability of input characters e A matching failure is caused by inappropriate input A directive composed of white space character s is executed by reading input up to the first non white space character or until no more characters can be read The first non white space character remains unread A directive containing an ordinary multibyte character is executed by reading the next characters of the stream If one character differs from one in the directive the directive fails and the differing and subsequent characters remain unread A directive containing a conversion specification defines a set of matching input sequences for each specifier A conversion specification is executed in the following steps e Input white space characters as specified by 1sspace are skipped unless the specification includes a c or n specifier Aninput item is read from the stream unless the specification includes an n specifier An input item is defined as the longest matching sequence of input
305. ery backed clock the actual time is read and set from the real time clock In order to get the system time date from the real time clock or the battery backed clock the month field in the date parameter must be 0 Attributes Operating System State Threads Re entrant Library os lib l See Also gmtime os link _os_getime os9 setime FSSTime F_STIME OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE _os9_setime Set System Date Time Syntax include lt time h gt finclude lt types h gt error_code _os9_setime u_int32 time u_int32 date Description _os9_setime sets the current system date time and starts the system real time clock to produce time slice interrupts Only super users may set the time time is in the format 00hhmmss date is in the format yyyymmdd Each value is one byte in length except for the year which is 2 bytes long Values must be in hexadecimal format The date and time are not checked for validity On systems with a battery backed clock it is usually only necessary to supply the year to the _os9_setime call The actual date and time are read from the real time clock In order to get the system time date from the real time clock or the battery backed clock the month field in the date parameter must be 0 Attributes Operating System OS 9 for 68K State User and System Threa
306. es Library clib 1 attach Attach to Device Syntax include lt modes h gt include lt io h gt dev_list attach char name int mode Description attach causes a new device to become known to the system or verifies that the device is already attached If the device descriptor is found and the device is not already attached attach links to its file manager and device driver and places their addresses in a new device table entry name is a pointer to the name of the device descriptor mode is the access mode FAM READFAM WRITES IREADS IWRITE mode may be used to verify that subsequent read and or write operations are permitted Only the lower 16 bits of mode are used If the attach fails 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l WX MICROWARE See Also os attach ISAttach OS 9 for 68K Technical Manual I ATTACH OS 9 Technical Manual bemp Compares Bytes from Two Memory Areas Syntax include lt UNIX os9def h gt int bemp void addrl void addr2 unsigned int len Description bcmp compares the memory at the first address addr1 against the memory at the second address addr2 The function returns zero if the memory areas are identical non zero otherwise
307. es you to append data to tapes on cartridge type tape drives path is the path number of the tape drive Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l1 os ss ticks Wait Specified Number of Ticks for Record Release Syntax include lt rbf h gt finclude lt types h gt error_code _os_ss_ticks path_id path u_int32 delay Description _os_ss_ticks may be used to cause an error EOS LOCK to return to the user program if a file lock conflict still exists after the specified number of ticks have elapsed path is the path number delay specifies the delay interval Adelay of zero RBF s default causes sleep until the record is released Adelay of one indicates that if the record is not released immediately an error is returned If the high order bit is set the lower 31 bits are converted from 256ths of a second to ticks before sleeping Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os ss wfm Write Tape Marks Syntax include lt sbf h gt finclude lt types h gt error code os ss wfm path id path u int32 marks Description os ss wfm writes the specified number of tape marks path specifies the tape drive s path number marks specifies the number of tape marks to write Attributes Operating System OS 9 a
308. es are defined in setsys h for C programs Each of these variables begin with a D_ prefix g g lob is the system global variable to examine Only the lower 16 bits of lob are used size is the size of the variable _getsys returns the value of the variable if the examine request succeeds If the request fails 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also os getsys _os_setsys FSSetSys OS 9 for 68K Technical Manual gettimeofday Get Current Time Syntax include lt UNIX os9time h gt int gettimeofday struct timeval tp struct timezone tzp Description The system s notion of the current time is obtained with the gettimeofday call The current time is expressed in elapsed seconds and microseconds since January 1 1970 zero hour The resolution of the system clock is hardware dependent The time may be updated continuously or in ticks gettimeofday returns zero 0 on success and 1 on failure and sets errno to indicate the error tp points to a timeval structure which includes the following members long tv sec seconds since Jan 1 1970 long tv usec and microseconds If tp is a NULL pointer the current time information is not returned t zp is not supported by unix 1 Attributes Operatin
309. es h gt finclude lt types h gt error code os readln path id path void buffer u int32 Gount Description _os_readin reads the specified number of bytes from the input file or device until an end of line character is encountered On SCF type devices os readiln also causes line editing such as backspacing line delete echo and automatic line feed to occur path specifies the path number buffer is a pointer to the location where the bytes to be read are placed The number of bytes requested is passed at the location pointed to by count os readin also stores the number of bytes actually read at the location pointed to by count Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also os read ISReadLn OS 9 for 68K Technical Manual I READLN OS 9 Technical Manual os rellk Release Ownership of Resource Lock Syntax finclude lt lock h gt finclude lt types h gt error code os rellkq lk desc lock Description os rellk releases ownership of a resource lock and activates the next process waiting to acquire the lock The next process in the lock s queue is activated and granted exclusive ownership of the resource lock If no other process is waiting on the lock the lock is simply marked free for acquisition lock is a pointer to the 1k desc structure of the lock to release Attributes O
310. es the specific memory type in which to load the module The memory h header file contains definitions of the memory types that you can specify Table 2 15 make module Color Memory Types Memory Type Description SYSRAM or MEM SYS System RAM memory VIDEO1 Video memory for plane A VIDEO2 Video memory for plane B MEM_ANY No specific memory type If color is MEM_ANY the module is made in whatever memory the system allocates make_module returns a pointer to the beginning of the module header If the module cannot be created 1 is returned and the appropriate error code is placed in the global variable errno Note The name of the module created by make module always begins at offset 34 within the module This implies that program modules trap handlers file managers device drivers and device descriptors cannot be made conveniently by this call Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also os datmod FSDatMod service request OS 9 for 68K Technical Manual WX MICROWARE malloc Allocate Memory from Arena Syntax include lt stdlib h gt void malloc size_t size Description malloc allocates space for an object The value of the object is indeterminate size is the size of the memory block to allocate If size is zero NULL is returned malloc returns either a null pointer if s
311. escription _sliblink links or loads the named module Then it places the subroutine module s execution entry pointer and static storage data pointer in the global arrays _sublibs and submems respectively You can use subcall to make subsequent calls the subroutine library s1ib num specifies the subroutine number s1ib name isa pointer to the subroutine name string For More Information For more information on creating installing and calling subroutine library modules refer to the OS 9 Technical Manual You can remove a subroutine module by passing a null pointer for the name of the module and specifying the subroutine number A process can link to a maximum 16 subroutine libraries numbered from 0 to 15 Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes See Also ubesglltj F SLINK OS 9 Technical Manual WX MICROWARE sprintf Formatted Output Syntax include lt stdio h gt int sprintf char Str const char format Description sprintf isa standard C library function that performs formatted output to the array specified by str sprintf converts formats and prints any parameters as indicated by the control string A null character is written at the end of the characters written it is not counted as part of the returned sum If copying takes place between overlapping objects the behavior is undefined str is a pointer to an array
312. et 34 within the module This implies that this call cannot conveniently make program modules trap handlers file managers device drivers and device descriptors Attributes Operating System State Threads Re entrant Library os lib l See Also os datmod Ds seterce os move OS 9 for 68K User and System Safe Yes WX MICROWARE os modaddr Find Module Given Pointer Syntax include lt module h gt finclude lt types h gt error_code _os_modaddr void mem ptr mh com mod head Description _os_modaddr locates a module given a pointer to any position within the module and returns a pointer to the module s header mem_ptr is a pointer to any position within the module mod head is a pointer to the location where _os_modaddr stores the pointer to the module header Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os_lib l os move Move Data Low Bound First Syntax include lt memory h gt finclude lt types h gt error_code _os_move void from void CO u_int32 count Description _os_move is a fast block move subroutine which copies data bytes from one address space to another usually from system to user or vice versa This call allows the source and destination buffers to overlap from is a pointer to the source data to is a pointer to the destination data count is the b
313. except that signals are not implicitly unmasked Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l See Also os sleep WX MICROWARE outc Write Character to I O Address Syntax finclude lt regs h gt finclude lt types h gt void outc void address u int32 data Description outc writes a character to an I O address on the 80x86 processors or memory address on all other processors data specifies the character to write Only the lower 8 bits are used address specifies the I O or memory address Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library cpu l See Also outl outw inc ee inw outl Write Integer to I O Address Syntax finclude lt regs h gt finclude lt types h gt void outl void address u int32 data Description outil writes a long value to the I O address on the 80x86 or the memory address on all other processors data specifies the long value to write address specifies the I O or memory address Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library cpu l See Also outc outw inet irl inw WX MICROWARE outw Write Word to I O Address Syntax finclude lt regs h gt finclude lt types h gt void outw void address u_int32 data Description
314. f FILE stream const char format Description printf fprintf and sprintf are standard C library functions that perform formatted output Each of these functions converts formats and prints any parameters as indicated by the control string fprintf writes output to a stream stream is a pointer to the C I O FILE structure format is a pointer to a control string format determines the format type and number of parameters that the function expects If the control string does not correctly match the parameters the results are not predictable fprintf returns when the end of the format string is encountered A format specification consists of a percent character followed by in this order 1 Zero or more flags that modify the meaning of the conversion specification You may use the following flags in any order Table 2 7 fprintf Flags Flag Description The result of the conversion is left justified within the field If this flag is not specified the result is right justified The result of a signed conversion always begins with a plus or minus sign If this flag is not specified the result begins with a sign only when a negative value is converted space If the first character of a signed conversion is not a sign or if a signed conversion results in no characters a space is prefixed to the result If the space and flags both appear the space flag is ignored The resul
315. f access argv optind 4 HY Ultr WX MICROWARE a C Library Reference Note Changing the value of the variable opt ind or calling getopt with different values of argv may lead to unexpected results Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Unsafe Re entrant No Library unix l Yes yay f ee 17 Ultra C Library Reference 317 WX MICROWARE getpid Return Process ID Number Syntax finclude lt process h gt int getpid void Description getpid returns the system process ID number for the calling process You can use this number for tasks such as creating unique file names Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also os id o089 idi FSID OS 9 for 68K Technical Manual F ID OS 9 Technical Manual getppid Return Parent Process ID Number Syntax include UNI unsigned int Description X os9def h getppid void getppid returns the system process ID number for the parent of the calling process You can use this number for tasks such as creating unique file names Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l See Also getpidi WX MICROWARE get process desc Get Process Descriptor Copy Syntax
316. f the child after its termination normal termination by the child process does not release any resources proc idis the process ID of the child to terminate Attrib utes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re en trant Yes Library os lib l See Also os exit oS dfork o89 dfork OS dexec FSDExit OS 9 Technical Manual F DEXIT OS 9 Technical Manual os dfork Fork Process Under Control of Debugger Syntax include lt dexec h gt finclude lt types h gt error_code _os_dfork u_int32 priority u int32 path cnt char mod name void params u int32 param size u int32 mem size process id proc id u int32 type lang regs reg stack fregs fregstack Description os dfork creates a new process which becomes a child of the caller It sets up the process memory MPU registers and standard I O paths In addition os dfork allows a debugger utility to create a process whose execution can be closely controlled The created process is not placed in the active queue but is left in a suspended state This allows the debugger to control its execution through the _os_dexec and os dexit calls priority is the priority of the new process Only the lower 16 bits of priority are used path cnt is the number of I O paths for the child to inherit Only the lower 16 bits of path cnt are used mod name is a pointer to the mo
317. faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b isgraph c Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Ultra C Library Reference 391 WX MICROWARE Library ctype h See Also isalnum isalpha lscntrti isdigit islower isprinti E l8pQ rnet isspace isupper lexdlgi 0 392 Ultra C Library Reference _isjis_kana See If Parameter Is Hankaku kana Syntax include lt ctype h gt int _isjis_kana int c Description isjis kana isa C macro that returns a non zero value if c is a Hankaku Kana Otherwise it returns zero The valid range is between Oxal and Oxdf c is the character to test Note This routine available as a function or a macro in ct ype h does not operate well with values outside the range of an unsigned char The function checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive o
318. fied to the signal function 4 7 1 1 The default handling is reset on all signals Whether the last line of a text stream requires a terminating newline character 4 9 2 A terminating newline is not required as the last character of a text stream Whether space characters that are written out to a text stream immediately before a newline character appear when read in 4 9 2 Space characters written to a text stream immediately before a newline character appears when read The number of null characters that may be appended to data written to a binary stream 4 9 2 Null characters are not appended to data written to a binary stream Whether the file position indicator of an append mode stream is initially positioned at the beginning or end of the file 4 9 3 The file position indicator of an append mode stream is initially positioned at the beginning of the file Regardless all writes to a stream in append mode are started at the current end of file Whether a write on a text stream causes the associated file to be truncated beyond that point 4 9 3 No truncation of this sort occurs The characteristics of file buffering 4 9 3 The file buffering decision is made when the first request is made to the stream If the buffering type and size have not been set explicitly by set vbuf the determination is made based on the device with which the stream is associated If the device is interactive line buffering is used Ot
319. flag is zero the first process in the event queue waiting for that range is activated Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also os ev set OoS ev signal FSEvent F EVENT EV SETR F EVENT EV SIGNL WX MICROWARE OS 9 for 68K Technical Manual OS 9 Technical Manual OS 9 Technical Manual oS ev setxor Set Event Variable and Signal Event Occurrence Syntax include lt events h gt finclude lt types h gt error_code _os_ev_setxor event_id ev_id int32 value u int32 mask u int32 actv flag Description os ev setxor signals that an event has occurred The current event value is EXCLUSIVE ORed with mask Then the event queue is searched for the first process waiting for that event value ev id identifies the event value is a pointer to the location where os ev setxor stores the event value prior to the logical operation mask specifies the event mask actv flag specifies which process es to activate e If actv_flag is one all processes in range are activated e If actv_flag is zero the first process in the event queue waiting for that range is activated Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MIC ROWARE See Also F EVENT OS 9 Technical Manual F EVENT EV SETXOR OS 9 Technica
320. fork returns an int and accepts the parameters specified Of particular interest is the three short parameters In ANSI mode the compiler assumes that the prototype was visible to the calling program and as a result the values were NOT widedned to int If the prototype was not visible to the calling function the values would have been widened This could have potentially caused a problem especially if the parameters were passed on the stack and NOT in registers As a result the Ultra C compiler has an option cw which warns the user if a function is being called without a prototype for that function being visible WX MIC ROWARE ANSI fying Code and Function Prototypes It has been a common practice as of late to take code and switch it over to ANSI compliant code This often entails prototyping many of the functions which used to be compiled with K amp R C compilers If this were done strictly as in the prototype from the os9fork function mentioned above and the os9fork function was not recompiled with an ANSI compiler things would not work since the function itself would be expecting the short arguments to be widened to ints and the calling program after having seen the prototype would send shorts There is really only one way to handle this in a manner that causes everything to still work and that is to prototype the functions to their widened types as follows int os9fork char int char int int int int
321. from a successful call to open creat create Or dup buffer is a pointer to space with at least count bytes of memory from which writeln obtains the data to write to the path It is guaranteed that at most count bytes are written writeln causes output filtering to take place such as outputting a linefeed after a carriage return or handling the page pause facility writeln writes at most one line of data A carriage return indicates the end of a line writeln is the preferred call for writing to the terminal writeln returns the number of bytes actually written If an error occurred 1 is returned and the appropriate error code is placed in the global variable errno Note writeln stops when the carriage return is written even if the byte count has not been exhausted WX MICROWARE Note The thread enabled version of this function contains a cancel point For more information see Using OS 9 Threads Attributes Operating System State Threads Re entrant Library Sys clib 1l1 See Also creat create dup open os writeln write ISWritLn _WRITELN OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual writev Write Output from iovcnt Buffers Syntax include UNIX os9def h int writev unsigned int fd struct iovec iov unsigned int iovcnt Description writev p
322. functions OS al ssi os attach _os_detach _os_get_ioproc os getdl os getpd 6S rdalst os tranpa Contains definitions for 1oct1 library function Defines the current I O interface editions ioedt h contains a prototype for the following function os gs edt Defines macros that expand to various limits and parameters Used for localization 1ocale h contains prototypes for the following functions localeconv setlocale Indicates a standard ANSI header Table 1 2 Ultra C Header Files continued File Description lock h Used for the OS 9 resource lock functions lock h contains prototypes for the following functions O8 acglk i os cagqlki OS Crlk os dellk os rellk os waitlk math h Defines the mathematical functions and macros available with Ultra C math h contains prototypes for the following functions acos asin atan atan2 ceil cos cosh exp fabs Eloor fmod frexp hypot ldexp log loglO modf pow sin Sinhi sqrt tan tanh Indicates a standard ANSI header WX MICROWARE Table 1 2 Ultra C Header Files continued File Description memory h moddir h Functions related to acquiring examining and releasing memory memory h contains prototypes for the following functions 089 allbiti 059 delbiti os get blkmap os mem _os_move _os9_schbit _os_srgmem
323. g System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l WX MIC ROWARE getuid Determine User ID Number Syntax finclude lt process h gt int getuid void Description getuid returns the group user ID of the current process The upper word two bytes of the value is the group number the lower word is the user number If unsuccessful 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l See Also os 3301 aos oad FSID OS 9 for 68K Technical Manual F_ID OS 9 Technical Manual getw Read Word from File Syntax include lt stdio h gt int getw FILE stream Description getw returns a word from a file converted to an integer It returns 1 on error Therefore use the macros feof and ferror to check the success of getw stream is a pointer to the C I O FILE structure Note getw is a machine dependent function because the size of a word varies from machine to machine getw assumes no particular alignment in the file getw reads two bytes from the file and sign extends them to four bytes Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library SyS clib l See Also feof j ferror
324. g save 59 375 list of functions 59 mask interrupts 59 371 373 remove device from fast IRQ table 59 remove device from IRQ table 59 686 688 reset signal intercept context stack 58 restore interrupt level 59 374 return current interrupt level 59 375 from interrupt exception 59 731 set IRQ level 59 370 unmask interrupts 59 372 inw 45 369 io h 18 ioctl 367 ioctlh 18 ioedt h 18 IRQ table ABCDEFGHIJKLMNOPQRSTUVWXYZ os firq 625 add device fast 625 remove device fast 625 IRQ level irg change 370 mask interrupts 371 373 restore interrupt level 374 return current interrupt level 375 set 370 unmask interrupts 372 IRQ table os irq 686 688 add device 686 688 remove table 686 688 irg change 59 370 irg disable 59 371 irg enable 59 372 irq_maskget 59 373 irqg restore 59 374 irqg save 59 375 isalnum 36 91 376 isalpha 36 378 isascii 380 isatty 382 iscntrl 36 91 383 isdigit 36 385 isgraph 36 391 islower 36 91 395 isprint 36 91 397 ispunct 36 399 isspace 37 405 isupper 37 407 isxdigit 37 409 Japanese Industrial Standard 401 403 JST 84 Julian date and time 411 ABCDEFGH Julian day defined 122 IJKLMNOPQRSTUVWXYZ kill 76 107 413 labs 61 415 LC ALL 428 935 LC COLLATE 935 1001 LC CTYPE 935 LC MONETARY 428 935 LC NUMERIC 428 935 LC TIME 935 936 1006 Idexp 61 418 Idiv 61 419 Iftocr
325. ge the wait increment is applied to the event value The actual event value is returned as the value of the function ev id specifies the event ID ev min specifies the minimum range value for the event ev max Specifies the maximum range value for the event ev wait returns the value of the event after completion of the wait If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Clear the global variable errno prior to calling ev wait to distinguish between return of a current event value of 1 and an error Further if a signal was received by the process the event value returned is outside of the range ev min to ev max errno 0 if ev_val ev wait ev id 5 0 1 amp amp errno exit errmsg errno error waiting on event if ev val 5 ev val gt 0 errmsg l1 received signal while waiting for event n WX MICROWARE For More Information Refer to your operating system technical manual for more information about events Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l1 See Also os ev wait 0S9 ev wait FSEvent OS 9 for 68K Technical Manual F_EVENT OS 9 Technical Manual EV_WAIT OS 9 Technical Manual ev waitr Wait for Relative Event Syntax include lt events h gt int ev waitr int ev id int ev
326. ger is active it runs in system state and effectively stops timesharing When used in user state os sysdbg can only be called by users in group zero When used in system state anyone may use os sysdbg Never use this call when other users are on the system You must enable the system debugger before installing breakpoints or attempting to trace instructions If no system debugger is available the system is reset The system debugger handles some of the exception vectors directly This makes it impossible to use the user debugger when the system debugger is enabled Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 os sysid Return System Identification Service Request Syntax finclude regs h finclude lt types h gt error code os sysid u int32 oem u int32 serial u int32 mpu type u int32 os type u int32 fpu type int32 time zone u int32 kernel ver u int32 resv2 char sys ident char copyright char author Description _os_sysid returns the following information about the system Table 2 23 os sysid Return Information Pointer Information Stored by os sysid oem OEM identification number serial Copy serial number mpu type Processor identifier such as 68020 68030 68040 80386 os type Kernel OS MPU configuration WX MICROWARE Table 2 23 os sysid Return Information cont
327. getuid _os9_allpd o05 alitsk os alocproci o5 aproci gs9 aproci os chain os chainm _os_chkmem _os_cpy_ioproc _os_cpymem _os_ddl1k _os_deltsk _os_exec os9exec _os_exit _os_findpd _os9_findpd OS forki osOtorki i os9forkcelt os forkm os get prtbli Os gprdse _ cso gspump i Gs 1d 5 os9 dl 08 loexit os iofork os9 ioqueue os nproc 059 panic os permit _os_protect _os9_retpd OS rtnprc os setpri os setuid os suspend 05 sysdbg os uacct os wait setpr setuid _sysdbg wait Indicates a standard ANSI header Table 1 2 Ultra C Header Files continued File Description procid h pwd h rbf h regexp h Process descriptor data structure procid his obsolete it has been replaced with process h Contains the password file definitions endpwent fgetpwent getnextpwnam getpw getpwent getpwnam getpwuid setpwent Used for functions using the random block file manager RBF rbf h contains prototypes for the following functions gs Gfd os gs atate OoS gs dsize os gs fd 08 gs fdaddr os gs fdint os gs parity os ss cache os a5 fd os ss tlushmapi cS 55s h liruki os 85 lockt oS ss ticks os ss wtrack 88 lock ss ptd B8 bliks ss wtrkl Contains definitions for regular expression support regcomp regerror regex regexec
328. gister Processor s name Type 403 505 601 603 User Readable sr4 PREG e ers PREG sr6 PREG sr PREG e sr8 PREG sro PREG sr10 PREG e srli PREG sri2 PREG e er13 PREG e sr14 PREG sr15 PREG e srr0 SPR e srrl SPR Sfr SPR srr3 SPR tbhi SPR Table 2 25 set name Valid Name Values continued Register Processor s 403 505 601 603 User Readable lt name gt Type tbl SPR tblo SPR tbu SPR tor SPR tsr SPR xer SPR Attributes Operating System State Threads Re entrant Library cpu l See Also _get_ lt name gt OS 9 User and System Safe Yes WX MICROWARE setbuf Fix File Buffer Syntax include lt stdio h gt void setbuf FILE stream char buf Description setbuf sets up buffering for an I O stream It may be used only after the stream has been associated with an open file and before any other operation is performed on the stream It is similar to set vbuf called with _ with _ IOFBF for mode and BUFSIZ for size or if buf is a null pointer IONBF for mode stream is a pointer to the C I O FILE structure buf is a pointer to the file s buffer setbuf returns no value Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library GLrb See Also fopen getc getc
329. gister image to pass to the function The address of the system state subroutine to execute should be set in regs pc Note Keep cyclic system state alarms as fast as possible Schedule them with as long a cycle as possible to avoid consuming a large portion of available CPU time Attributes Operating System State Threads Re entrant Library os lib l See Also _os9_salarm_set FSAlarm OS 9 for 68K System Safe Yes OS 9 for 68K Technical Manual AA MICROWARE os salarm delete Remove Pending Alarm Request Syntax include lt alarm h gt finclude lt types h gt error_code _os_salarm_delete alarm_id alrm_id Description _os_salarm_delete removes a cyclic alarm or any alarm that has not expired alrm id specifies the alarm ID If a1xm idis 0 zero all pending alarm requests are removed which are owned by the system process forked with TH_SPOWN In a threaded environment the alarm_id is checked to determine the owner of the thread If a O is passed for the alarm id all pending alarm requests for the system will be removed which are owned by the system process forked with TH_SPOWN Attributes Operating System OS 9 and OS 9 for 68K State System Threads Safe Re entrant Yes Library os_lib l See Also FSAlarm OS 9 for 68K Technical Manual F ALARM OS 9 Technical Manual os salarm delete sp Delete Installed Alarms Syntax include lt alarm
330. gnal handler 364 setpr 938 sleep 1062 start 712 suspend 831 1079 terminate 621 O 683 wait for child to terminate 854 1079 wait 1079 process descriptor _get_process desc 320 _os_alocproc 517 OS deltsk 559 os findpd 623 OS get ioproc 643 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z _os_get_prtbl 647 os gprdsc 651 os rtnprc 732 os setpr 78 allocate 517 deallocate 559 732 find 623 get copy 320 651 of block table 647 initialize 517 set process priority 78 process ID os id 675 os9 id 677 determine 318 get 675 677 process manipulation _get_process desc 320 _get_process table 76 322 os alocproc 76 517 os aproc 76 519 os chain 76 526 os dfork 77 565 os dforkm 77 569 os exec 77 611 os findpd 77 623 os fork 77 628 os forkm 77 633 os get prtbl 77 647 os getstat 77 648 os getsys 77 649 os gprdsc 77 651 os id 77 675 os nproc 78 712 os rtnprc 78 732 os setpr 764 os sleep 78 782 os suspend 78 831 os wait 78 854 os9 allpd 76 515 os9 aproc 76 520 ABCDEFGH _os9_dfork 77 567 _os9_gspump 77 672 _os9_id 78 677 _os9_sleep 78 784 allocate fixed length block of memory 76 515 process descriptor 76 517 chain 155 chainc 76 155 create process 77 78 628 630 633 deallocate process descriptor 78 732 determine parent process ID number 319 determine process ID number 76 318 enter process in active process queue 76 520
331. gt error code _os_get_ioproc process id proc id io proc pbroc Description os get ioproc returns a pointer to the I O process descriptor for the specified process proc id specifies the process ID of the process procis a pointer to the location where os get ioproc stores the pointer to the I O process descriptor Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library os_lib l WX MIC ROWARE os get mdp Get Current and Alternate Module Directory Pathlists Syntax include lt moddir h gt finclude lt types h gt error_code _os_get_mdp char current char alternate Description os get mdp returns pathlists to the current and alternate module directories current is a pointer to the location where os get mdp stores the pathlist of the current module directory alternate is a pointer to the location where os get mdp stores the pathlist of the alternate module directory Note current and alternate should point to buffers of at least 64 bytes to accommodate the directory names Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l os get moddir Get Copy of Module Directory Syntax finclude module h finclude lt types h gt error code os get moddir void buffer u_int32 count Description os get moddir copies the process current
332. h gt finclude lt types h gt error_code _os_salarm_delete_sp alrm_id flags Description os salarm delete sp takes a flag value to allow correct deletion of installed alarms thus providing a workaround for a historic OS 9 bug in os salarm delete alrm id specifies the alarm ID If alrm_id is zero all pending alarm requests are removed flags specifies that the alarm s to be deleted are owned by either the system process TH SPOWN or by the current user process flags 0 Attributes Operating System OS 9 and OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l See Also FSAlarm OS 9 for 68K Technical Manual F_ALARM OS 9 Technical Manual WX MICROWARE os salarm reset Reset Alarm Clock Syntax include alarm h finclude lt types h gt error code os salarm reset alarm id alrm id u int32 time u int32 flags u_int32 func void xfunc_pb Description _os_salarm_reset allows you to change the parameters on an existing alarm a1rm id specifies the alarm ID to reset t ime specifies the alarm s time interval or a time A time interval may be specified in system clock ticks or 256ths of a second The minimum time interval allowed is 2 system clock ticks flags specifies the alarm flags func is a pointer to a function to execute func pb is a pointer to the function s parameter block Attrib utes Operating System State Threads
333. h gt error_code _os_makdir char name u int32 mode u int32 perm Description os makdir creates and initializes a new directory as specified by the pathlist os makdir is the only way to create a new directory file os makdir fails on non multifile devices name is a pointer to the pathlist mode specifies the access mode Only the lower 16 bits of mode are used perm specifies the access permissions A variable parameter may be included to specify the initial allocation size os makdir does not return a path number You should use os open to open a directory The new directory automatically has its directory bit set in the access permission attributes The remaining attributes are specified by the bytes passed in mode and perm For More Information Refer to your operating system technical manual for the available modes and attributes Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 WX MICROWARE os makmdir Create New Module Directory Syntax include lt moddir h gt finclude lt types h gt error_code _os_makmdir char name u int32 perm Description os makmdir creates a new module directory The name of the new module directory is relative to the current module directory name is a pointer to the name of the new module directory perm specifies the access permiss
334. h header file stdarg h provides a method for stepping through a list of function parameters whose length and type are unknown ap is an object representing the next unnamed parameter type is a type name va arg expands into an expression The expression returns a value that has the type and value of the next unnamed parameter It also modifies ap such that the next call to va arg returns the next parameter ap must have been previously initialized using va start If there is no actual next parameter or if type is not compatible with the type of the actual next parameter as promoted according to the default parameter promotions the behavior is undefined Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 See Also va start va end End References to Current Variable Parameter List Syntax include lt stdarg h gt void va_end va_list ap Description va_end is amacro associated with the stdarg h header file stdarg h provides a method for stepping through a list of function parameters whose length and type are unknown ap is an object representing the next unnamed parameter va end expands into an expression The expression facilitates a normal return from the function whose variable parameter list was referred to by the expansion of the va start call that initialized ap va end may modify ap so that
335. har putet purchart setvbut 0 _setcrc Re Validate Module CRC Syntax include lt module h gt int setcrc mh com module Description _setcrc updates the header parity and CRC of a module in memory The module must have the correct size and sync bytes other parts of the module are not checked module is a pointer to the module to update If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno WARNING Although os setcrc and setcrc functions do update the header and CRC of a module in memory the copy of the module header in the module directory is not affected Therefore you have an invalid module directory entry for the memory module with the new CRC and an error 236 results if links to the module are attempted Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l WX MICROWARE See Also o5 sereorc t FSSetCRC OS 9 for 68K Technical Manual F SETCRC OS 9 Technical Manual set excpt base Set Exception Table Base Address Syntax finclude lt regs h gt void set excpt base u int32 dsreg Description set excpt base sets the exception table base address It is a system state only system call dsreg is a pointer to the base address of the exception table Note set excpt base is supported only on the 80x86 family of processors version of
336. har mkdata module char name unsigned size int attr int perm Description mkdata module creates a data memory module Other processes on the system can then access the data module by modlink The memory in the data module is initially cleared to zeroes name is a pointer to the desired module name size specifies the size of the module in bytes Note The size value does not include the module header and CRC bytes The specified size is the amount of memory available for actual data storage attr specifies the module s attribute and revision level Only the lower 16 bits of attr are used perm specifies the module access permissions Only the lower 16 bits of perm are used _mkdata_module returns a pointer to the beginning of the module header If the data module cannot be created 1 is returned and the appropriate error code is placed in the global variable errno Attributes Op erating System State Threads Re entrant Library Sys clib 1l1 See Also FS os datmod DatMod E S DATMOD WX MICROWARE OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual mknod Create Directory Syntax include lt modes h gt int mknod char name int perm Description mknod creates a directory file name is a pointer to the name of the directory perm specifies the access permissions for the director
337. he first bit to set Only the lower 16 bits of bit number are used count specifies the number of bits to set Only the lower 16 bits of count are used address is a pointer to the base address of a bit map Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also oso schbaiti o89 delbait t FSAllBit OS 9 for 68K Technical Manual _os9_allpd Allocate Fixed Length Block of Memory Syntax finclude lt process h gt finclude lt types h gt error code _os9_allpd void table u intl16 number void ptr Description _os9_allpd allocates fixed length blocks of system memory It allocates and initializes to zeros a block of storage and returns its address table is a pointer to the process path table number is a pointer to the location where os9 allpd stores the process path number ptr is a pointer to the location where os9 allpd stores the pointer to the process path descriptor Attributes Operating System OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l See Also os9 findpd os9 retpd FSA11PD OS 9 for 68K Technical Manual WX MIC ROWARE os alltsk Allocate Task Syntax finclude lt process h gt finclude lt types h gt error code os alltsk pr desc proc desc Description os alltsk initializes the protection hardware for a newly activated p
338. he low 31 bits are considered a time in 256ths of a second Usually the minimum time interval allowed is 2 system clock ticks Attributes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant Yes Library os lib l1 See Also FSAlarm OS 9 for 68K Technical Manual F ALARM A SET OS 9 Technical Manual os alias Create Device Alias Syntax include lt io h gt finclude lt types h gt error_code _os_alias char alias name char real name Description os alias creates an alternate name for a device pathlist Processes can then reference a specific device pathlist with a shorter or more convenient name alias name is a pointer to the alternate name real name is a pointer to the actual device name it must exist OS 9 does not validate its existence WARNING Do not use a real device name as alias name Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l See Also ALIAS OS 9 Technical Manual WX MICROWARE os9 allbit Set Bits in Bit Map Syntax include lt memory h gt finclude lt types h gt error_code _os9_allbit u_int32 bit_number u_int32 count void address Description _os9_allbit sets bits in a buffer that represents a bit map Bit numbers range from 0 ton 1 wheren is the number of bits in the bit map bit number specifies the bit number of t
339. he number of bits found at the location pointed to by count address is a pointer to the base address of the bitmap bitmap endis a pointer to the end of the bitmap plus one If os9 schbit returns SUCCESS you should check count to make sure that you received the requested number of bits If count is less than the requested amount os9 schbit returned the largest number of bits available starting at bit number Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes WX MICROWARE Library os_lib 1 See Also 89 allbati _os9_delbit 752 Ultra C Library Reference os seek Reposition Logical File Pointer Syntax include lt modes h gt finclude lt types h gt error_code _os_seek path_id path u_int32 position Description _os_seek repositions the path s file pointer The file pointer is the 32 bit address of the next byte in the file to read or write A seek may be performed to any value even if the file is not large enough Subsequent write requests automatically expand the file to the required size if possible read requests return an end of file condition path specifies the path number position specifies the new position in the file Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also I Seek OS 9 for 68K Technical Manual I SEEK OS 9 Technica
340. he standard library functions stdlib h contains prototypes for the following functions abort abs atexit atof atoi atol atou bsearch callo divi dtoa ebrk exit _exit tree _freemem freemem _freemin ibrk getenv labs _lealloe ldiv ft ltfreei y Imalloci lrealloc malloec t mallocmin mblen mbstowcs mbtowc qsort rand realloc sbrk srand Stacksiz stacksiz i Sbrtogdi lsutrtelu strtoul system wcstombs wctomb Indicates a standard ANSI header WX MICROWARE Table 1 2 Ultra C Header Files continued File Description string h f strings h svctbl h Used for manipulating arrays of character type string h contains prototypes for the following functions memchr memcmp memcpy memmove memset strcat strchri strompi strooll i stropytn strcspn strerror strlen strncat i strnomp strncpy Bstrporkilstrrchr Strsoni Stretrt strtok sEkrxfrmi Used for non ANSI string functions strings h contains prototypes for the following functions cmpnam findnstr findstr index os cmpnam os prsnam pause prsnam rindex strass strhogpyt Contains information for the service table svctbl h contains a prototypes for the following function os setsvc Indicates a standard ANSI header Table 1 2 Ultra C Header Files continued
341. he value of the pointer if the memory is to be returned with srtmem Or os srtmem Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1 See Also os srqmem os9 srqmem os srtmem FSSRqMem OS 9 for 68K Technical Manual F SROMEM OS 9 Technical Manual WX MICROWARE _srtmem System Memory Return Syntax include lt memory h gt int _srtmem unsigned size char ptr Description _srtmem is a direct hook into the FSSRtMem OS 9 for 68K or _os_srtmem OS 9 system call It is used to return memory granted by srqmem Or os srqmem Care should be taken to ensure that size and ptr are the same as those returned by _srqmem or os srqmem size specifies the number of bytes to return ptr is a pointer to the memory to return If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l See Also os srqmem os9 srqmem os srtmem FSSRtMem OS 9 for 68K Technical Manual F_SRTMEM OS 9 Technical Manual _ss_attr Set File Attributes Syntax include lt sg_codes h gt int _ss_attr int path int attr Description _ss_attr changes a disk file s attributes os gs fd determines the current attributes of a file
342. herwise full buffering is used If the device is RBF Random Block File Manager the buffer size is 2 current sector size Whether a zero length file actually exists 4 9 3 A zero length file actually does exist The rules for composing valid file names 4 9 3 The rules vary depending on the operating system OS 9for68K File names can contain 1 to 28 upper or lower case letters digits underscores _ periods or dollar signs OS 9 File names can contain 1 to 43 upper or lower case letters digits underscores _ periods or dollar signs A MICROWARE Whether the same file can be open multiple times 4 9 3 A program can open a file more than once but fully buffered reading and writing to the same file has undefined results The effect of the remove function on an open file 4 9 4 1 remove returns 1 with errno set to EOS SHARE if called with the name of an open file The effect if a file with the new name exists prior to a call to the rename function 4 9 4 2 Assuming the calling program has write permission the file with the new name is deleted and recreated with the new information The output for p conversion in the fprintf function 4 9 6 1 The pointer to void is printed as an unsigned hexadecimal integer The input for p conversion in the fscanf function 4 9 6 2 The input for p conversion is an unsigned hexadecimal integer The interpretation of a ch
343. ian equivalents time and date are pointers to the Julian time and date values The values must be in the following format Figure 2 2 _gregorian Input Date and Time Format Time Seconds Since Midnight 0 86399 Date Julian Day Number _gregorian modifies the values to the Gregorian format Figure 2 3 _gregorian Output Date and Time Format Time 0 Hour 0 23 Minute Second Date Year 2 Bytes Month Day Byte 0 Byte1 Byte 2 Byte 3 If successful gregorian returns zero Otherwise 1 is returned Note Be careful to pass pointers for the date and t ime values Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also os julian OS 9 for 68K _os_gregorian OS 9 for 68K WX MIC ROWARE gs devn Get Device Name Syntax include sg codes h int gs devn int path char buffer Description gs devn allows you to determine the name of the device open on a path path is the path number of an open path buffer is a pointer to a character array into which the null terminated device name is placed If the path number is invalid 1 is returned and the appropriate error code is placed in the global variable errno Note You must reserve a buffer of at least 32 bytes to receive the device name Some networked devices using NFM should have a buffer size
344. ib 1l1 See Also os get prtbl FSGPrDBT OS 9 for 68K Technical Manual getpw Get Name from Password File Syntax include lt UNIX pwd h gt int getpw int uid char buf Description getpw searches the password file for the numerical user identification number uid and fills in the buffer buf with the corresponding name It returns non zero if the uid could not be found The name is null terminated Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix l See Also endpwent fgetpwent getpwent getpwuid getpwnam setpwent WX MICROWARE getpwent Get Password File Entry Syntax include lt UNIX pwd h gt struct passwd getpwent void Description getpwent getpwuid and getpwnam each return a pointer to an object with the following structure containing the fields of a line in the password file Each line in the file contains a passwd structure declared in the lt UNIX pwd h gt header file struct passwd char pw_name login name char pw_passwd password int pw_uid user ID int pw_gid group ID int pw prio priority char pw age unsupported zero length string char pw comment unsupported zero length string char pw gecos unsupported zero length string char pw dir initial data directory char pw xdir initial execut
345. ibrary os lib l1 os ss flushmap Flush Cached Bit Map Information for RBF Device Syntax include lt rbf h gt finclude lt types h gt error_code _os_ss_flushmap path_id path Description _os_ss_flushmap flushes the cached bit map information for an RBF device This is normally only performed after the bit map on the disk is changed by a utility such as format path is the path number for any file on the device or the entire device for example a path open to h0 Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os_lib l WX MICROWARE os ss hdlink Make Hard Link to Existing File Syntax include lt rbf h gt finclude lt types h gt error_code _os_ss_hdlink path_id path char link path Description os ss hdlink creates a new directory entry This directory entry points to the file descriptor block of an open file os ss hdlink updates the pathlist pointer path is the path number of an existing file The new name for the directory entry is passed at the location pointed to by link path os ss hdlink also stores the updated pathlist pointer at the location pointed to by 1ink path Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l1 os ss link adj Syntax include sg codes h finclude lt types h gt error code os ss link adj pa
346. ifies the number of blocks to erase Ifblocks is Oxffffffff SBF erases until the end of tape is reached If blocks is positive SBF erases the amount of tape equivalent to that number of blocks Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 os ss fd Write File Descriptor Sector Syntax include lt rbf h gt finclude lt types h gt error code _os_ss_fd path id path fd stats fdinfo Description os ss fd changes the file descriptor sector data The path must be open for write To change the file descriptor sector data you must first read the sector make the changes and then write the sector path specifies the path number fdinfo is a pointer to the file descriptor s buffer Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os ss fillbuff Fill Path Buffer with Data Syntax include lt scf h gt finclude lt types h gt error_code _os_ss_fillbuff path_id path char buffer u int32 size Description os ss fillbuff fills the input path buffer with the data in buffer path specifies the path number buffer is a pointer to the location of your buffer size specifies the size of your buffer Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes L
347. iles The status returned by the exit function if the value of the argument is other than zero EXIT SUCCESS Or EXIT FAILURE 4 10 4 3 The integer value passed to exit is the exit status of the program The set of environment names and the method for altering the environment list used by the getenv function 4 10 4 3 The common set of environment names depends on the operating system Refer to your operating system s user manual for more information The environment list is implemented as a NULL terminated array of pointers to characters Each string is in the form name value name is the name of the environment variable value is the current value of the environment variable To modify the list you must either find the existing entry or enlarge the array and add an entry The base of the array is stored in the external variable environ The contents and mode of execution of the string by the system function 4 10 4 5 The contents of an execution string given to system can be any valid shell command line The shell used to execute the string is either the current value of the SHELL environment variable or she11 if SHELL is unavailable The contents of the error message strings returned by the strerror function 4 11 6 2 The strings generated by the st rerror function are located in the system errmsg file dd SYS errmsg h0 SYS errmsg Or d0 SYS errmsg Refer to
348. imum number of significant digits for the g and G conversions The maximum number of characters to be written from a string in s conversion The precision takes the form of a period followed either by an asterisk or by an optional decimal integer If only the period is specified the precision is taken as zero If a precision appears with any other conversion specifier the behavior is undefined An optional h 1 or L that specifies Table 2 8 fprintf Optional flag descriptions Flag Description The following d i o u x or X conversion specifier applies to a short int oran unsigned short int parameter or the following n conversion specifier applies to a pointer to a short int parameter The following d i o u x or X conversion specifier applies to a 1ong int oran unsigned long int parameter or the following n conversion specifier applies to a pointer to a 1ong int parameter The following e E g or G conversion specifier applies to a long double parameter If anh 1 or L appears with any other conversion specifier the behavior is undefined 5 Acharacter that specifies the type of conversion to apply An asterisk may indicate the field width precision or both In this case an int parameter supplies the field width or precision The parameters specifying field width precision or both appear in that order before the parameter if any to convert A negative field width parameter i
349. inal This is because the operating system sends the abort quit signals to the last process to perform I O to the terminal If you run the program from the shell and type E before the program performs I O to the terminal the shell receives the signal and kills the running program If a program requires immediate control of the terminal perform some I O to one of the standard paths such as printing a program banner or getting the terminal options with gs opt Any I O using the C library for example printf cannot be performed inside both the intercept handler function and the main program Consequently avoid I O within intercept functions Note Generally intercept should not be used with signal Only signals that are under ST this function G DFL handling reach a handler installed with You cannot use floating point math within the intercept handler function Attributes Operating System Sta Thr te eads Re entrant Lib rary Sys clib l See Also os intercept os send _O8 ATgmaski signal F cpt F Send F SigMask F ICPT F_SEND F_SIGMASK OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 for 68K Technical Manual OS 9 for 68K Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual WX MIC ROWARE Example As an example this program is designed to c
350. indscri strstr Ultra C Library Reference 251 WX MIC ROWARE findstr Search String for Pattern Syntax include lt strings h gt int findstr int pos char string char pattern Description findstr searches the string for the first instance of the pattern It starts at position pos where the first position is one not zero The returned value is the position of the first matched character of the pattern in the string or zero if a match is not found findstr stops searching when a null byte is found in string pos specifies the starting position string is a pointer to the string to search pattern is a pointer to the pattern to use for the search Note The current implementation does not use the most efficient pattern matching algorithm strstr is preferred for very long strings Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library sys_clib 1 See Also findnstr Btrstri Ultra C Library Reference 253 WX MIC ROWARE floor Floor Function Syntax include lt math h gt double floor double x Description floor returns the largest integer as a double that is not greater than x Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 See Also ceil fmod Compute Floating Point Remainder
351. ing takes place between overlapping objects the behavior is undefined orig is a pointer to the original string append is a pointer to the string to append to orig count specifies the maximum number of characters to append strncat returns the value of orig Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 strncmp String Comparison Syntax include lt string h gt int strnomp const char stringl const char string2 size t count Description strncmp compares not more than count characters from st ringl to string2 Characters following a null character are not compared The strings do not need to be null terminated stringl is a pointer to a string to compare string is a pointer to a string to compare count specifies the maximum number of characters to compare strnomp returns an integer that is e Positive if stringl is greater than st ring2 e Zero if stringl equals string2 e Negative is string1 is less than string2 Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 WX MICROWARE strncpy String Copy Syntax include lt string h gt char strncpy char dest const char src size t count Description strncpy copies characters from src to dest Characters following a null ch
352. ing I O F TONBIO works with Sockman only path opts block type it gets and checks for ioctl returns zero on success for most requests Some specialized requests may return non zero values on success See the specific description for the request On failure ioct1 returns 1 and sets errno to indicate an error Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes WX MICROWARE Library unix l inw Get Word from I O Address Syntax finclude lt regs h gt finclude lt types h gt u intl16 inw void address Description inw returns the word indicated by the specified I O address on the 80x86 processors or the memory address on all other processors address is the specified address Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library cpu l See Also 11e inltj oute cuui outw WX MICROWARE irq_change Set IRQ Level Syntax finclude lt regs h gt finclude lt types h gt status code irq change status code newval Description irq change sets the interrupt level to newval irq change returns the previous interrupt level It is a system state only system call Attributes Operating System OS 9 and OS 9 for 68K State System Threads Safe Re entrant Yes Library cpu l See Also irq disable irq enable irq maskget irq restore
353. ing on a resource lock before deleting it Failure to release suspended processes prior to deletion could result in system corruption Attributes Operating System State Threads Re entrant Library lock 1 See Also F ACQLK F CAQLK F CRLK E B F RELLK F WAITLK DDLK DELLK OS 9 User Safe Yes OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual WX MICROWARE os delmdir Delete Existing Module Directory Syntax include lt moddir h gt finclude lt types h gt error code _os_delmdir char name Description _os_delmdir deletes an existing module directory The directory must be empty name is a pointer to the module directory Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l See Also F DELMDIR OS 9 Technical Manual os deltsk Deallocate Process Descriptor Syntax finclude lt process h gt finclude lt types h gt error code os deltsk pr desc proc desc Description _os_deltsk returns the process protection resources when the process terminates proc desc is a pointer to the process descriptor Note os deltsk only performs a useful function on MMU SSM systems On non MMU SSM systems os deltsk simply returns without deallocating the process desc
354. ing the signal SIGABRT However if the signal STGABRT is being caught and the signal handler does not return the program is not terminated If SIGABRT returns the program is terminated abnormally This flushes and closes the open streams and removes temporary files The process returns the status EXIT_FAILURE Note abort does not return to the caller Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library labycL abs Integer Absolute Value Syntax include lt stdlib h gt int abs int value Description abs returns the absolute value of its integer parameter value is the integer parameter abs 0x80000000 returns 0x80000000 as the result Note Applying abs to the most negative integer yields a result which is the most negative integer Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 WX MICROWARE access Determine File Accessibility Syntax include lt modes h gt int access char name int perm Description access returns zero if the mode s specified in the file permissions are correct for the user to access the specified file name is a pointer to the name of the file perm may be any legal mode as defined in the modes h header file Use a mode value of zero to v
355. ings 81 1008 determine string length 82 1009 findnstr 81 250 findstr 81 252 get string length 81 1003 index 81 361 list of 81 locate first occurrence of string 82 1013 1016 ABCDEFGHIJKLMNOPQRSTUVWXYZ last occurrence of string 82 1014 string 81 999 map error message string 81 place formatted time in buffer 81 88 1005 1006 rindex 81 907 search for character in string 81 361 907 string for pattern 81 250 252 strcat 81 998 strchr 81 999 stremp 81 1000 strcoll 81 1001 strcpy 81 1002 strcspn 81 1003 strerror 81 strftime 81 88 1005 1006 strhcpy 81 1008 string catenation 81 82 998 1010 comparison 81 82 1000 1001 1011 copy 81 82 1002 1012 to double conversion 82 1017 to long conversion 82 1021 1024 strlen 82 1009 strncat 82 1010 strncmp 82 1011 strncpy 82 1012 strpbrk 82 1013 strrchr 82 1014 strspn 82 1015 strstr 82 1016 strtod 82 1017 strtok 82 1019 strtol 82 1021 strtoul 82 1024 strxfrm 82 1027 transform string 82 1027 string h 32 strings h 32 strlen 82 1009 strncat 82 1010 ABCDEFGHIJKLMNOPQRSTUVWXYZ strncmp 82 1011 strncpy 82 1012 strpbrk 82 1013 strrchr 82 1014 strspn 82 1015 strstr 82 1016 strtod 82 1017 1018 strtok 82 1019 strtol 82 1021 1023 strtoul 82 1024 1026 structure assignment 997 strxfrm 82 1027 suspend process 831 task 869 svctbl h 32 synchr
356. instructions executed so far is passed os dexec also stores the updated total number of instructions at the location pointed to by tot instr status is a pointer to the location where os dexec stores the return status except is a pointer to the location where os dexec stores the exception that the child received addr is a pointer to the location where os dexec stores the violation address exit status is a pointer to the location where os dexec stores the exit status of the child An os dexit call must be made for the resources memory of the debugged process to be returned For More Information Refer to your operating system technical manual for system specific information Note Tracing is allowed through subroutine libraries intercept routines and OS 9 for 68K user state trap handlers This is not a problem but may seem strange at times Attributes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant Yes Library os lib l1 See Also Sm Srorki 0589 dforki os dexit FSDExec OS 9 for 68K Technical Manual F_DEXEC OS 9 Technical Manual F_DFORK OS 9 Technical Manual WX MICROWARE os dexit Exit Debugged Program Synta fincl fincl X lude dexec h lude lt types h gt error code os dexit process id proc id Description _os_dexit terminates a suspended child process created by os dfork To allow examination o
357. int32 path cnt mh com mod head void params u int32 param size u int32 mem size process id proc id u int32 orphan Description _os_forkm creates a new process which becomes a child of the caller It sets up the new process memory MPU registers and standard I O paths The new process is forked by a module pointer _os_forkm assumes that the module pointer is the primary module pointer for the new process priority specifies the priority of the new process Only the lower 16 bits of priority are used If priority is zero the new process inherits the same priority as the calling process path cnt specifies the number of I O paths for the child to inherit Only the lower 16 bits of path cnt are used mod head is the module name pointer params is a pointer to the parameter block param size specifies the size of the parameter block mem size specifies any additional stack space to allocate proc idis a pointer to the location where os forkm stores the child process ID WX MICROWARE If the orphan flag is non zero the new process executes without a parent If the orphan flag is zero the new process is the child of the calling process Only the lower 16 bits of orphan are used Attributes Operating System State Threads Re entrant Library os lib l See Also os Fork OS 9 User and System Safe Yes os get blkmap Get Free Memory Block Map Syntax include memory h finclude
358. int32 time u int32 date REGISTERS regs Description os9 salarm atjul executes a system state subroutine at a specific Julian date and time The alarm subroutine is executed anytime the system date time becomes greater than or equal to the alarm time alrm idis a pointer to the location where os9 salarm atjul stores the alarm ID time is the time for the alarm to go off in seconds after midnight date is the Julian day number for the alarm to go off regs s a pointer to the register image to pass to the function The address of the system state subroutine to execute should be set in regs pc Note os9 salarm atjul only allows the time to be specified to the nearest second However it does adjust if the system s date and time have changed using _os9_setime Attributes Operating System OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l See Also _os9_setime FSAlarm OS 9 for 68K Technical Manual WX MICROWARE os salarm cycle Set Cyclic Alarm Clock Syntax include alarm h finclude lt types h gt error code os salarm cycle alarm id alrm id u int32 time u int32 flags u_int32 func void xfunc_pb Description _os_salarm_cycle executes the specified subroutine after the specified time interval has elapsed Then the alarm is reset to provide recurring periodic execution of the specified subroutine alrm idis a pointer
359. inter if the character does not occur in the string Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library elib l WX MICROWARE strcmp String Comparison Syntax include lt string h gt int strcmp const char stringl const char string2 Description strcmp compares stringl to string2 stringl is a pointer to a string to compare string2 is a pointer to a string to compare strcmp returns an integer that is e Positive if stringl is greater than st ring2 Zero if stringl equals string2 Negative if string1 is less than st ring2 Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 strcoll String Comparison Syntax include lt string h gt int strcoll const char stringl const char string2 Description strcoll compares two strings both interpreted as appropriate to the LC COLLATE category of the current locale stringl is a pointer to a string to compare string is a pointer to a string to compare When both stringl and string are interpreted as appropriate to the current locale st rcol1 returns an integer that is e Positive if st ringlis greater than st ring2 e Zero if stringl equals string2 e Negative is stringl is less than st ring2 Attributes Operating System OS 9 and OS 9
360. inter to a string to write to stdout puts returns EOF if an error occurs Otherwise it returns a non negative value Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also fgets gets putw Output Word to File Syntax include lt stdio h gt int putw int num FILE stream Description putw writes an integer converted to a word to a file putw neither assumes nor causes any special alignment in the file num is the integer to write to the structure FILE stream is a pointer to the file If successful putw returns the value it has written Otherwise it returns 1 Note putw like getw is machine dependent because the size of the integer it outputs varies with the integer size of the machine on which it resides This compiler defines int values as 4 byte quantities but putw actually outputs 2 bytes Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l1 See Also getw WX MICROWARE qsort Quick Sort Syntax include lt stdlib h gt void qsort void base size t nmemb size t size int compar const void const void Description qsort sorts an array base is a pointer to the initial array element nmemb is the number of elements in the array size is the size
361. inter to the allocated memory block color specifies the memory type Only the lower 16 bits of color are used e If color is non zero the search is restricted to memory areas of that color The area with the highest priority is searched first If color is zero the search is based only on priority Note The byte count of allocated memory and the pointer to the allocated block must be saved if the memory is ever to be returned to the system Attributes Operating System State Threads Re entrant Library os lib l See Also os9 srqmem os srtmem os mem F SRqCMem F SROMEM OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE os9 srqmemY System Memory Request Syntax include lt memory h gt finclude lt types h gt error_code _os9_srqmem u_int32 size void mem ptr Description os9 srqmem allocates a memory block from the top of available RAM The size of the memory block is passed at the location pointed to by size os9 srqmem also stores the actual number of bytes allocated at the location pointed to by size If size is OxFFFFFFFF the largest block of free memory is allocated to the calling process mem ptr is a pointer to the location where os9 srqmem stores the pointer to the allocated memory block Note The byte count of allocated memory and the pointer to the allocated bloc
362. intercept pflinit none duliam i _os_julian prerr strerror kali 1 _os_send _prgname argv 0 lseek 0s Seek _prsnam _os_prsnam putw putc putc putw isreplaced by performing two calls to putc BS npe os ss enrts read Os read i ss lockt D amp ss lock readdir os read 88 opt o8 S5 popt readimi 63 resdint 56 prar 0S Ss Fay Ultra C Library Reference 107 y Overview WX MICROWARE Table 1 37 sys_clib l Function Equivalents continued sys_clib Function Corresponding Function rewinddir _ss_rel rindex Ss rest sbrk SS size seekdir _ss_ssig _setcrc _ss_tiks setime _ss_wtrk setpr a amp atrassi setstat strhepy _setsys sys mktime Os Seek ncOs ss relea strrchrt 58 585 reset malloc _os_ss_size 06 seek _os_ss_sendsig _os_setcrc D 6 ss tacks t os setime os9 setime t _os_ss_wtrack _os_setpr memcpy on structure assignment ps setest ti none _os_setsys mktime for user programs Ultra C Library Reference Overview Table 1 37 sys clib Function Equivalents continued sys clib Function Corresponding Function setuid b amp setuigi 8ysdate t o08 setime os9 setime sigmask _os_sigmask Sysdbg i _os_sysdbg sleep 08 sleep os9 sleep tel
363. interval has elapsed alarm id is a pointer to the location where os9 salarm set stores the alarm ID time specifies the time interval The time interval time may be specified in system clock ticks or 256ths of a second The minimum time interval allowed is 2 system clock ticks regs s a pointer to the register image to pass to the function The address of the system state subroutine to execute should be set in regs pc Attributes Operating System OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l See Also FSAlarm OS 9 for 68K Technical Manual os scache Cache Control Syntax finclude lt regs h gt include lt cache h gt finclude lt types h gt error code os scache u int32 control void cetl DIS void cctl data void addr u int32 size Description _os_scache performs operations on the system instruction and or data caches if there are any cont rol specifies the cache operation If control is zero the system instruction and data caches are flushed Non super group user state processes may perform this operation The following table shows the bits that are defined in the control parameter for precise operation Only system state and super group processes can use the cont rol parameter for precise operation Table 2 21 control Parameter Bits Defined for os scache Bit Name Description Bit O C ENDATA If set enables the data
364. inued Pointer Information Stored by os sysid fpu type time zone kernel ver resv2 Sys ident copyright author Floating point processor identifier such as 68881 and 80387 System time zone in minutes offset from Greenwich Mean Time GMT The kernel s version number for OS 9 for 68K A reserved pointer A pointer to an application buffer to copy the system identification message into The buffer must be at least 80 bytes in length A pointer to an application buffer to copy the copyright message into The buffer must be at least 80 bytes in length For OS 9 A pointer to an application buffer to copy the author message for OS 9 The buffer must be at least 80 bytes in length For OS 9 for 68K This parameter should be NULL Note On OS 9 for 68K time zone is always returned as 1 Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 WX MICROWARE os thexit Exit a Thread Syntax include lt threads h gt error code _os_thexit error_code status Description _os_thexit causes the calling thread to exit If the calling program is not multi threaded the EOS_PERMIT error is returned status is the value to be returned to any thread waiting for this thread viaan_os_waitid call If successful os thexit does not return to the caller Attributes Operating System OS 9 State User a
365. ion os attach causes a new l O device to become known to the system or verifies that the device is already attached name is a pointer to the I O device s name mode is the access mode It can be FAM READ FAM WRITE S IREAD OrS IWRITE mode may be used to verify that subsequent read and or write operations are permitted Only the lower 16 bits of mode are used dev tbl is a pointer to the location where os attach stores the pointer to the device list entry If the descriptor name is found os attach links to the I O device s file manager and device driver If the device was already attached os attach returns a pointer to the pointer to the device table entry containing the address of the I O device s file manager and device driver in dev tb1 If the device is not already attached os attach creates a new device table entry and initializes the device It returns a pointer to the pointer to the entry in dev tb1 Attributes Operating System State Threads Re entrant Library os lib l See Also _os_detach ISAttach I ATTACH WX MICROWARE OS 9 and OS 9 for 68K User Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual os cache Cache Control Syntax For OS 9 for 68K include lt cache h gt for OS 9 for 68K systems finclude lt regs h gt finclude lt types h gt error code os cache u int32 control For OS 9 finclude l
366. ion directory char pw shell initial command executed char pw junk undefined The fields pw_age pw_comment pw_gecos and pw_junk are unused When first called getpwent returns a pointer to the first passwd Structure in the file thereafter it returns a pointer to the next passwd Structure in the file so successive calls can be used to search the entire file getpwuid searches from the beginning of the file until a numerical user ID matching uid is found and returns a pointer to the particular structure in which it was found getpwnam searches from the beginning of the file until a Login name matching name is found and returns a pointer to the particular structure in which it was found If an end of file or an error is encountered on reading these functions return a NULL pointer A call to setpwent has the effect of rewinding the password file to allow repeated searches endpwent may be called to close the password file when processing is complete fgetpwent returns a pointer to the next passwd structure in the stream which matches the format of the password file dd SYS password getpwent getpwuid and getpwnam return a pointer to struct passwd on success On EOF or error or if the requested entry is not found they return NULL Note The above routines use the standard I O library which increases the size of programs not otherwise using standard I O more than might be expected
367. ions for the new module directory Only the lower 16 bits of perm are used Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 os memY Resize Data Memory Area Syntax include memory h finclude lt types h gt error code os mem u int32 size void mem ptr Description os mem contracts or expands the process data memory area The requested size is rounded up to an even memory allocation block Additional memory is allocated contiguously upward towards higher addresses or deallocated downward from the old highest address The desired memory size in bytes is passed at the location pointed to by size os mem also stores the actual size of the memory at the location pointed to by size If the integer pointed to by size is zero os mem treats the call as a request for information and returns the current upper bound in mem pt r and the amount of free memory in size Otherwise mem ptr is a pointer to the location where os mem stores the pointer to the new end of data segment plus 1 Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also F Mem OS 9 for 68K Technical Manual F MEM OS 9 Technical Manual WX MICROWARE _os_mkmodule Create Data Module of Specified Color Type Syntax include lt module h gt include lt mem
368. is the event mask actv flag specifies which process es to activate e If actv_flag is one all processes in range are activated e If actv_flag is zero the first process in the event queue waiting for that range is activated Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MIC ROWARE See Also F EVENT OS 9 Technical Manual F EVENT EV SETOR OS 9 Technical Manual F EVENT EV SIGNL OS 9 Technical Manual 0S ev setr Set Relative Event Variable and Signal Event Occurrence Syntax include lt events h gt finclude lt types h gt error_code _os_ev_setr event_id ev_id int32 value u int32 actv flag Description os ev setr signals that an event has occurred The current event value is incremented by value Then the event queue is searched for the first process waiting for that event value Arithmetic underflows or overflows are set to 0x80000000 minimum integer or Ox7 fffff maximum integer respectively ev id identifies the event The amount to add to the event value is passed at the location pointed to by value e OS 9ffor 68K os ev setr stores the event value before the increment at value e OS 9 os ev setr stores the event value after the increment at value actv flag specifies which process es to activate e factv flagis one all processes in range are activated e If actv_
369. issjis2 37 403 _julian 87 107 411 _Icalloc 62 416 _lfree 62 420 _Imalloc 62 423 _lrealloc 62 434 _mallocmin 63 445 _mkdata_module 68 105 457 _os_acqlk 79 502 _os_alarm_atime 54 506 os alarm cycle 54 509 os alarm delete 54 510 os alarm reset 54 511 Os alarm set 54 512 Os alias 48 513 OS alltsk 63 516 os alocproc 76 517 os altmdir 69 518 os aproc 76 519 OS attach 48 521 os cache 65 523 os caglk 79 525 os chain 76 526 os chainm 69 528 os chdir 48 530 os chkmem 532 os chmdir 69 534 ABCDEFGHIJKLMNOPQRSTUVWXYZ os close 48 535 Os clrsigs 54 536 os cmdperm 69 537 _os cmpnam 65 538 os config 540 configure 540 OS copy ioproc 48 541 _os cpymem 63 542 Os crc 69 543 OS create 48 545 Os crik 79 549 os datmod 69 550 os ddlk 79 552 os delete 48 555 os dellk 79 557 Os delmdir 69 558 Os deltsk 63 559 os detach 49 560 os dexec 66 561 os dexit 66 564 Os dfork 77 565 os dforkm 77 569 os dup 49 571 os ev allclr 54 573 _os ev allset 54 575 Os ev anycl 54 576 Os ev anyset 54 577 os ev change 54 578 OS ev creat 54 579 OS ev delete 55 581 os ev info 55 582 os ev link 55 585 OS ev pulse 55 586 OS ev read 55 588 OS ev set 55 589 OS ev setand 55 591 OS ev setor 55 593 OS ev setr 55 595 OS ev setxor 55 597 OS ev signal 55 599
370. ive if key is considered less than the array element Zeroif key is equal to the array element Positive if key is considered greater than the array element The array consists of all elements that compare less than equal to and greater than the key object in that order bsearch returns a pointer to a matching array element If no match is found it returns a null pointer If two elements compare as equal which element is matched is unspecified Attributes Operating System State Threads Re entrant Standards Library eli bed WX MICROWARE OS 9 and OS 9 for 68K User and System Safe Yes ANSI Functions buildpath Adds a Filename to the Root Directory Variable Syntax include UNIX os9def h char buildpath char filename Description buildpath adds filename to the value of the environment variable XOS9ROOTDIR If XOS9ROOTDIR is not set a default value of hO is used Note buildpath returns the final string in a static buffer that should be saved if additional calls are made to buildpath For example with XOS9ROOTDIR setto dd ETC buildpath xfile returns the string dd ETC xfile without XOS9ROOTDIR set buildpath xfile returns the string h0 xfile Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l WX MICROWARE bzero Clear Bytes In Mem
371. k must be saved if the memory is ever to be returned to the system Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 See Also os srtmem os mem os srqmem FSSRqMem OS 9 for 68K Technical Manual WX MICROWARE os srtmem Return System Memory Syntax include lt memory h gt finclude lt types h gt error_code _os_srtmem u_int32 size void mem ptr Description os srtmem deallocates memory when it is no longer needed size specifies the byte count of the returned memory mem ptr is a pointer to the memory block to return Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also os srqmem os mem OS ss atti Set File Attributes Syntax include sg codes h finclude lt types h gt error code os ss attr path id path u int32 attr Description os ss attr changes a file s attributes to the new value if possible You cannot set the directory bit of a non directory file or clear the directory bit of a non empty directory path specifies the path number of the file attr specifies the new values for the file attributes Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE oS ss break Send Break Condition
372. ke gdesc Make global descriptor table regs h entry make idesc Make interrupt descriptor table regs h entry set excpt base Set exception table base regs h address set gdtr Set global descriptor pointer regs h WX MIC ROWARE These functions are available only on the PowerPC processors as identified in Table 1 28 ANSI prototypes for non ANSI functions are achieved by defining the macro name OP T_PROTOS during the compile Table 1 28 Power PC Only Functions ANSI Function Standard Description Header File get name Read the value of SPRs getset h DCRs PREGs and TBs set name Set the value of SPRs DORs getset h PREGs and TBs Implementation Defined Behavior The following are the implementation defined issues pertaining to the Ultra C library Each bulleted item contains one implementation defined issue The number in parentheses included with each bulleted item indicates the location in the ANSI specification where you can find more information The null pointer constant to which the macro NULL expands 4 1 5 NULL expands to void 0 The diagnostic printed by and the termination behavior of the assert function 4 2 assert prints a line with the following syntax if the NDEBUG macro is not defined if the assertion fails Assertion failed expression file lt file gt line lt line gt n expression is the expression being tested file is the file na
373. l Manual F EVENT EV SIGNL OS 9 Technical Manual os ev signal Signal Event Occurrence Syntax include lt events h gt finclude lt types h gt error_code _os_ev_signal event_id ev_id int32 value u int32 actv flag Description os ev signal signals that an event has occurred The current event variable is updated with the signal auto increment that was specified when the event was created Then the event queue is searched for the first process waiting for that event value ev id identifies the event that has occurred value is a pointer to the location where os ev signal stores the event value prior to the signal operation actv flag specifies which process es to activate If actv 1ag is one all processes in the event queue with a value in range are activated If act v_flag is zero the first process in the event queue waiting for that range is activated Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 WX MIC ROWARE See Also FSEvent OS 9 for 68K Technical Manual F_EVENT OS 9 Technical Manual F_EVENT EV_SIGNL OS 9 Technical Manual os ev tstset Wait for Event to Occur Syntax include lt events h gt finclude lt types h gt error_code _os_ev_tstset event_id ev_id int32 value signal code signal u int32 mask Description _os_ev_tstset
374. l Manual WX MICROWARE os sema init Initialize Semaphore Data Structure for Use Syntax include lt semaphore h gt error code _os_sema_init semaphore sema Description OS 9 for 68K os sema init is valid in version 3 0 and greater os sema init initializes a semaphore data structure for subsequent use The application should call os sema init before the first use of the semaphore The semaphore may be part of a data module or it may be part of any data structure within the application sema is a pointer to the semaphore data structure to initialize Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also os sema p OS Sema term oS sema v os sema p Reserve Semaphore Acquire Exclusive Access Syntax include lt semaphore h gt error code _os_sema_p semaphore sema Description OS 9 for 68K os sema p is valid in version 3 0 and greater os sema p attempts to reserve the semaphore If the semaphore is busy the caller is suspended until the current holder releases the semaphore sema s a pointer to the semaphore to reserve os sema p returns an error code if a signal arrives while a process is waiting for a semaphore i e it signals that the process is resuming execution because of the incoming signal without obtaining the semaphore Attributes Operating System OS 9 and
375. l of the old block s contents begin the new block The results of 1realloc NULL 10 0 and l1malloc 10 are the same lrealloc returns NULL if the requested memory is not available or if newsize is specified as zero Note Use of the low overhead allocation functions 1calloc lmalloc and l1realloc instead of the general allocation functions calloc malloc and realloc saves 8 bytes per allocation because the low overhead functions do not save the allocation size or the 4 byte check value The low overhead functions require that you keep track of the sizes of allocated spaces in memory Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library elib I See Also calloc free _freemin eel lot _lfree _imalloc mal toc mallocmin os srqmem os srtmem realloc Ultra C Library Reference 435 WX MIC ROWARE Iseek Position File Pointer Syntax include modes h long lseek Tn path long position int place Description lseek repositions the file pointer for the file open on path to the byte offset given in position path is the path number of the open file position is the new file position offset place determines from which file position the offset is based 0 From the beginning of the file 1 From the current position 2 From the end of the file
376. l while in the event queue it is activated even though the event has not actually occurred mask specifies the activation mask Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MIC ROWARE See Also F EVENT OS 9 Technical Manual F EVENT EV ALLCR OS 9 Technical Manual F EVENT EV SIGNL OS 9 Technical Manual os ev allset Wait for Event to Occur Syntax include lt events h gt finclude lt types h gt error_code _os_ev_allset event_id ev_id int32 value signal code signal u int32 mask Description os ev allset waits for an event to occur That is it waits until an os ev signal occurs that sets all of the bits corresponding to the set bits in the mask ev id identifies the event value is a pointer to the location where os ev allset stores the actual event value signal is a pointer to the location where os ev allset stores the signal code If the process receives a signal while in the event queue it is activated even though the event has not actually occurred mask specifies the activation mask Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l See Also F EVENT OS 9 Technical Manual F EVENT EV ALLSET OS 9 Technical Manual F EVENT EV SIGNL OS 9 Technical Manual WX MICROWARE os ev anycir Wait for Event to Occur
377. ld status is available to the caller The lower 16 bits of the status value contains the parameter of the exit Or exit call as executed by the child process or the signal number if it was interrupted with a signal A normally terminating C program with no explicit call to exit in main returns a status equal to the returned value of main wait returns 1 if there is no child process for which to wait 0 if a signal was received before a child process terminated Note The status codes used in the operating system may not be compatible with other operating systems A wait must be executed for each child process created WX MICROWARE HM Note The thread enabled version of this function contains a cancel point For more information see Using OS 9 Threads Attributes Operating System State Threads Re entrant Library Sys clib 1l1 See Also exlti Sexl1p0 oS wait os8 fork FSWait F WAIT OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual waitpid Wait for Process Syntax include lt sys wait h gt pid_t waitpid pid_t pid int stat_loc int options Description waitpid allows a thread to wait for a process and get its exit status The pid and options arguments determine how the wait is done For values of pid less than or equal to 0 the next available child process status is returned For value
378. ldir 8 gs post srqcmem os srqmem tsleep _os_sleep _srqmem os srqmem os9 srqmem unlink oe delete Srtmem os srtmem unlinkx 08 delete Bs attri OS os sttr4d wait oS wait aBSLAGOEET _OS_ss_dcort write _os_write 556 deoni D5 ss deon writeln oS writeln Ultra C Library Reference 109 WX MICROWARE Table 1 37 sys clib l Function Equivalents continued sys clib Function Corresponding Function 8 9 dsrtst 03 ss dsrtsu The Function Description Each function description includes a minimum of the following sections e Syntax e OS 9 Attributes Description Library In addition descriptions may also contain sections for the following Examples Errors References to other calls See Also Syntax The syntax shows how the function and parameters look if written as a C function definition even if the actual function is a macro or is written in assembly language For example the syntax for open appears as follows include lt stdio h gt FILE fopen const char name const char action This indicates that fopen requires the lt stdio h gt header file returns a pointer to a structure of type FILE and requires two parameters both pointers to constant character strings The parameter names are suggestions only you can use any name OS 9 Attributes The OS 9 Attributes section lists various attributes of each fun
379. le in the libraries sc1ib 1 and sclib il unix l The UNIX like library functions For More Information The primary purpose of the sys clib 1 library is to provide a library for compatibility with the Microware K amp R C compiler For additional information refer to Appendix A Prototyping sys clib Functions For More Information For information on sclib 1 small library functions see Chapter 2 of Using Ultra C C Program Globals WX MICROWARE Ultra C defines a number of globals for use by library functions and or the application They are divided into two classes 1 Globals that are unlikely to change from release to release and 2 Globals that are used by library functions that may change from release to release see header file cglob h for current information Class 1 Globals u int32 totmem u intl16 pathcnt void sysglob mh exec modhead char modname u int32 procid u int32 maxstack Total number of bytes that are in the data area for the program includes stack global data and parameters Number of open paths the process inherited from the parent process usually 3 Pointer to the kernel s system globals This variable is only initialized when the program is a system state process otherwise it is NULL OS 9 for 68K only Pointer to the primary module for the current process Pointer to the module name for the current process unmodifiable P
380. lean up work files and exit when it receives a keyboard quit signal signal 2 which normally is caused by typing E on the terminal include lt stdio h gt char tempname tempfile FILE tempfp int quittime 0 the signal handler gotsignl signum int signum switch signum case 2 the quit signal quittime 1 break default ignore all others break main if tempfp fopen tempname w NULL exit _errmsg errno can t open file s n tempname intercept gotsignl do do work while quittime fclose tempfp unlink tempname exit _errmsg 1 quittin time n ioctl Control Device Syntax include ioctl h include UNIX os9def h int ioctl unsigned int fd unsigned int request caddr_t arg Description ioctl performs some of the UNIX like I O control functions fd is the path to the device that is affected by the function request is the function to perform arg has various meanings depending on the function to be performed The two functions that are supported are FIONREAD Return the number of bytes available for reading from the path The number of bytes is returned at the unsigned long pointed to by arg FIONREAD Works with RBF SCF Pipe and Sockman e FIONBIO Set the I O blocking status on the path arg is a pointer to 0 blocking I O or 1 non block
381. lid range The specified message length msg len exceeds the message size attribute of the message queue mq send not supported OS 9 User Safe No POSIX WX MICROWARE mq setattr Set Message Queue Attributes Syntax finclude lt mqueue h gt int mq setattr mqd t mqdes const struct mq attr mqstat struct mq attr omqstat Description mq setattr is used to set attributes associated with the open message queue description referenced by the message queue descriptor specified by mqdes The message queue attributes corresponding to the following members defined in the mq attr structure are set to the specified values upon successful completion of mg setattr mq flags The value of this member is the bitwise logical OR of zero or more of O NONBLOCK and any implementation defined flags The values of the mq maxmsg mq msgsize and mq curmsgs members of the mq attr structure are ignored by mq setattr If omqstat is non NULL the function mq setattr stores in the location referenced by omqstat the previous message queue attributes and the current queue status These values are the same as would be returned by a call to mq getattr at that point OS 9 specifies the following user defined flag for use with mq getattr andmq setattr MQ O NOTIFY IMMEDIATE When this flag is specified by the mq setattr function mq 1ags field of mqstat parameter then calls to either mq notify write Oormq
382. ll character is not written str is a pointer to the string stream is a pointer to the stream to write fputs returns EOF if a write error occurs Otherwise it returns a non negative value Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also fgets fread Read Data from File Syntax include lt stdio h gt int fread void ptr size_t size size_t nmemb FILE stream Description fread reads up to nmemb elements into an array The file position indicator for the stream if defined is advanced by the number of characters successfully read If an error occurs the resulting value of the file position indicator for the stream is indeterminate If a partial element is read its value is indeterminate ptr is a pointer into the array size specifies the size of each array element nmemb specifies the number of array elements to read stream is a pointer to the C I O FILE structure fread returns the number of elements successfully read which may be less than nmemb if a read error or end of file is encountered If size Or nmemb is zero fread returns zero and the array contents and stream state remain unchanged For More Information The sclib 1 and sclib i1 libraries contain a smaller version of the fread function Refer to the Using Ultra C C manual for more information about the
383. ll processes waiting for the event that have a value in range are activated OS 9 for 68K ev set returns the value of the event before changing to ev value If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Clear the global variable errno prior to calling ev set to distinguish between return of a prior event value of 1 and an error OS 9 ev set returns zero If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno WX MICROWARE For More Information Refer to your operating system technical manual for more information about events Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also ev creat ev link t os ev creat Jos ev link os ev set FSEvent OS 9 for 68K Technical Manual F_EVENT OS 9 Technical Manual EV_CREAT OS 9 Technical Manual EV_LINK OS 9 Technical Manual EV_SET OS 9 Technical Manual ev seti Set Relative Event Variable and Signal Event Occurrence Syntax include lt events h gt int _ev_setr int ev_id int ev value int allflag Description ev setr indicates that an event has occurred The event variable is incremented by the value given by ev value Processes waiting for the event are then activated ev idis the event ID returned from a call to ev
384. lock table into the caller s buffer for inspection buffer is a pointer to the buffer The maximum number of bytes to copy is passed at the location pointed to by count os get prtbl1 also stores the actual number of bytes copied at the location pointed to by count Although os get prtb1 returns pointers to all process descriptors never access the process descriptors directly Instead use os gprdsc to inspect specific process descriptors Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also os alocproc 08 gprdsci WX MICROWARE os getstat Get File Device Status Syntax include sg codes h finclude lt types h gt error code _os_getstat path id path u int32 code void pb Description _os_getstat is a wildcard call used to handle individual device parameters that are not uniform on all devices or are highly hardware dependent path is the path number code is the Get Stat code pb is a pointer to the parameter block The exact operation of this call depends on the device driver and file manager associated with the path The mnemonics for the status codes are located in the sg codes h header file The status codes that are currently defined by Microware and the functions that they perform are described in this manual The functions havean os gs prefix Attributes Operating System
385. lt types h gt error code os get blkmap void start void buffer u_int32 size u int32 min alloc u int32 num segs u int32 tot mem u int32 free mem Description os get blkmap copies the address and size of the system s free RAM blocks into your buffer for inspection It also returns information concerning the free RAM as noted by the parameters A series of structures showing the address and size of free RAM blocks is returned in your buffer start is a pointer to the address to begin reporting the segments buffer is a pointer to the buffer to use size specifies the buffer size in bytes min alloc is a pointer to the location where os get blkmap stores the minimum memory allocation size for the system num segs is a pointer to the location where os get blkmap stores the number of memory fragments in the system tot memis a pointer to the location where os get blkmap stores the total RAM found by the system at startup free mem is a pointer to the location where os get blkmap stores the current total free RAM available WX MICROWARE Note Although os get blkmap returns the address and size of the system s free memory blocks you cannot assume that these blocks are free to use Use os srqmem to request free memory blocks Attributes Operating System State Threads Re entrant Library os lib l See Also os mem os srqmem FSGB1kMap F GBLKMP OS 9 and
386. lts may occur Use low level functions when using gs rdy Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes WX MICROWARE Library Sys clib 1l1 See Also OS gs ready oS read _os_readin ISGetStt OS 9 for 68K Technical Manual I GETSTAT OS 9 Technical Manual SS READY OS 9 Technical Manual gs size Get Current File Size Syntax include sg codes h int gs size int path Description _gs_size determines the current size of the file open on path path is the path number of the open file If the path is invalid or the device is not an RBF device 1 is returned and the appropriate error code is placed in the global variable errno Otherwise the file size is returned Note This call is effective only on RBF and PIPEMAN devices Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also oS gs size ISGetStt OS 9 for 68K Technical Manual I GETSTAT OS 9 Technical Manual SS SIZE OS 9 Technical Manual WX MICROWARE 356 Ultra C Library Reference hypot Euclidean Distance Function Syntax finclude lt math h gt double hypot double x double y Description hypot returns the Euclidean distance function Sqrt x x y y hypot ignores overflows Attributes Operating System OS 9 and OS 9 for 68K
387. lude modes h int unlink char name Description unlink decrements the link count of a file When the link count reaches zero 0 the space occupied by the file on the disk is freed and the file no longer exists name is a pointer to the name of the file If successful unlink returns 0 Otherwise 1 is returned and the appropriate error code is placed in the global variable errno Note OS 9 for 68K does not yet support multiple links to a file unlink always causes the file to be removed from the disk Attempting to delete an open file by the calling or another process results in an EOS_SHARE error Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library sys_clib 1 See Also _os_delete ISDelete OS 9 for 68K Technical Manual I DELETE OS 9 Technical Manual unlinkx Unlink Delete File Syntax include modes h int unlinkx char name int mode Description unlinkx decrements the link count of a file name is a pointer to the name of the file mode specifies the file s access mode If the execution bit FAM EXEC OrS IEXEC in the mode is set the path is assumed to be based in the current execution directory The header file modes h defines the legal mode values When the link count reaches zero the space occupied by the file on the disk is freed and the file no longer exists Only the lower 16 bits of mode are use
388. lude lt modes h gt lude lt types h gt error code os delete name mode char u int32 Description os delete deletes a file The caller must have non sharable write access to the file the file may not already be open or an error results name is a pointer to the file to delete mode specifies the access mode Possible values for mode include FAM REA D FAM WR TE FAM EXEC S IREAD S IWR DE S EXEC Attempts to delete from non multifile devices result in an error The access mode specifies the data or execution directory but not both in the absence of a full pathlist Only the lower 16 bits of mode are used Attrib Operating System State utes Threads Re en trant Library os lib l OS 9 and OS 9 for 68K User and System Safe Yes WX MICROWARE See Also os attach oS create os detach os open ISDelete OS 9 Technical Manual I_DELETE OS 9 Technical Manual os dellk Delete Existing Lock Descriptor Syntax incl incl lude lt lock h gt lude lt types h gt error code _os_dellk lk_desc lock Description lockisa OS del OS del 1k deletes an existing lock descriptor pointer to the 1k_desc structure for the lock to delete 1k does not check for suspended processes still waiting to acquire the lock an implementation using locks must release all processes wait
389. lue for uppercase letters isupper returns a non zero value for ASCII characters with values in the range from 0x41 A to 0x5a Z c is the character to test Note This routine available as a function or a macro in ctype h does not operate well with values outside the range of an unsigned char The function checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b isupper c Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Ultra C Library Reference 407 WX MICROWARE Library ctype h See Also isalnum isalpha lISCUDEL lepunct isspace H n Q D is 5 K CT ae ge eS vog I Mam N 408 Ultra C Library Reference isxdigit See If Parameter Is Hexadecimal Syntax include lt ctype h gt int isxdigit int c Description isxdigit is a C macro that returns a non zero value for any hexadecimal digit character c is the character to test Note This routine available as a function or a macro i
390. m isalpha TBEBEEL isspace isupper islower LE 398 Ultra C Library Reference ispunct See If Parameter Is Punctuation Character Syntax include lt ctype h gt int ispunct int c Description ispunct is a C macro that returns a non zero value for any printing character that is neither a space nor a character for which isalnum is non zero c is the character to test Note This routine available as a function or a macro in ctype h does not operate well with values outside the range of an unsigned char The function checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b ispunct c Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI oo oO c Ultra C Library Reference WX MICROWARE Library ctype h See Also isalnum isalpha TBEBEEL isspace isupper uiti did LE 0 400 Ultra C Library Reference _issjis1 See If Parameter Is
391. m number of bytes to copy is passed at the location pointed to by count os gprdsc also stores the actual number of bytes copied at the location pointed to by count Attributes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant Yes Library os lib l See Also os get prtbl WX MICROWARE os gregorian Get Gregorian Date Syntax include lt time h gt finclude lt types h gt error_code _os_gregorian u_int32 time u int32 date Description os gregorian converts Julian dates to Gregorian dates Gregorian dates are considered the normal calendar dates time is a pointer to the location where the time in seconds since midnight os gregorian stores the time in the form 00hhmmss in the location pointed to by t ime date is a pointer to the location where the Julian date is passed os gregorian stores the date in the form yyyymmdd in the location pointed to by date Refer to your operating system technical manual for more information Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also oS julian OS get ime _os9 gs cdfd Return File Descriptor Syntax include lt cdi h gt finclude lt types h gt error_code _os9_gs_cdfd path_id path u_int32 count void fdbuf Description 0S9 gs cdfd reads the file descriptor describing the
392. mages far in excess of the value of the copies involved For additional copies of this software documentation or if you have questions concerning the above notice please contact your OS 9 supplier Trademarks OS 9 OS 9000 DAVID and MAUI are registered trademarks of Microware Systems Corporation SoftStax FasTrak UpLink and Hawk are trademarks of Microware Systems Corporation All other product names referenced herein are either trademarks or registered trademarks of their respective owners Address Microware Systems Corporation 1500 N W 118th Street Des Moines lowa 50325 515 223 8000 Table of Contents Chapter 1 Overview 7 8 Using Functions and Macros 10 Library Files 12 Program Globals 12 Class 1 Globals 13 Class 2 Globals 14 Header Files 35 The C Library 35 Communicating with Environment Functions 36 Character Classification Functions 37 Character Conversion Functions 38 File Positioning Functions 39 GetStat SetStat Functions 45 Input Output Device Functions 45 Input Output Functions 52 Interprocess Communication Functions 59 Interrupt Manipulation Functions 60 Mathematical Functions 62 Memory Management Functions 65 Miscellaneous Functions 68 Module Manipulation Functions 72 Multibyte Character and String Functions 73 OS System Functions 74 POSIX Messaging Functions 76 Process Manipulation Functions 79 Resource Locks 80 Searching and Sorting Functions 81 String Handling Functions Ultra C Libr
393. me of the file containing the assert macro line is the line number of the file containing the assert macro The abort function is called after the assertion failure line is printed This raises the SIGABRT signal that may be handled by the application For More Information Refer to the description of signal for more information about SIGABRT e The sets of characters tested for by the isalnum isalpha iscntrl islower isprint and isupper functions 4 3 1 isalnum returns non zero for any character which isdigit or isalpha returns non zero isalpha returns non zero for any character which islower or isupper returns non zero iscntrl returns non zero for ASCII characters with values from 0 to Ox1f and Ox7f islower returns non zero for ASCII characters with values from 0x61 to Ox7a isprint returns non zero for ASCII characters with values from 0x20 to 0x7e isupper returns non zero for ASCII characters with values from 0x41 to Ox5a The values returned by the mathematics functions on domain errors 4 5 1 The mathematics functions return HUGE VAL on domain errors WX MICROWARE Whether the mathematics functions set the integer expression errno to the value of the macro ERANGE on underflow range errors 4 5 1 errno is not set to E RANGE on underflow errors Whether a domain error occurs or zero is returned when the fmod fun
394. meter is printable ctype h character ispunct Test if parameter is punctuation ctype h character Table 1 4 Character Classification Functions continued ANSI Header Function Standard Description File issjisl Test if parameter is the first byte ctype h of Kanji Lissjis2 j Test if parameter is the second ctype h byte of Kanji isspace Test if parameter is white space ctype h isupper Test if parameter is uppercase ctype h isxdigit Test if parameter is ctype h hexadecimal Character Conversion Functions The character conversion functions allow you to convert a string of characters to their numeric representation and to change the case of characters Table 1 5 identifies character conversion functions Table 1 5 Character Conversion Functions ANSI Header Function Standard Description File atof Alpha to floating conversion stdlib h atoi Alpha to integer conversion stdlib h atol Alpha to long conversion stdlib h aton Alpha to numeric translation aton h KX MICROWARE Table 1 5 Character Conversion Functions continued ANSI Header Function Standard Description File atou Alpha to unsigned conversion stdlib h _dtoa Double to ASCII conversion stdlib h toascii Integer to ASCII translation ctype h toasciti _tolower Convert character to lowercase ctype h tolower Convert character to lowercase ctype h _toupper Convert character to uppercase c
395. mh_com modcload char modname int mode int memtype Description modcload opens the file specified by the pathlist It reads one or more memory modules from the file into memory until an error or end of file is reached modname is considered a pathlist and all modules in the specified file are loaded A link is made to the first module loaded from the file and a pointer to it is returned modname is a pointer to the path to the module mode is the mode which opens the file to load If any access mode is acceptable specify zero for mode memt ype indicates the specific memory type in which to load the module The memory h header file contains definitions of the memory types that may be specified Table 2 16 modcload Memory Types Memory Type Description SYSRAM or MEM_SYS System RAM memory VIDEO Video memory for plane A VIDEO2 Video memory for plane B MEM ANY No specific memory type If memt ype is MEM ANY the module may be loaded in whatever memory the system allocates If the load is successful modcload returns a pointer to the module If the load fails 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l1 AA MICROWARE modf Return Parts of Real Number Syntax include lt math h gt double modf double valu
396. min int ev max Description _ev_waitr waits for the specified event to occur The event value is compared to the relative values specified by ev min and ev max The current event value is added to the range values before the comparison If the event value is not in the specified range the process waits until some other process places the value within the range Once in range the wait increment is applied to the event value The actual event value is returned as the value of the function ev id specifies the event ID for the event ev min specifies the minimum range value for the event ev max Specifies the maximum range value for the event _ev_waitr returns the value of the event after completion of the wait If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Clear the global variable errno prior to calling ev waitr to distinguish between return of a current event value of 1 and an error Further if a signal was received by the process the event value returned is outside of the relative range ev mintO ev max For More Information Refer to your operating system technical manual for more information about events Attributes Operating System State Threads Re entrant Library Sys clib 1l1 See Also OS ev waitr FSEvent F EVENT EV WAITR WX MICROWARE OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual
397. mod name mh com mod head void mod exec u int32 mode u_int16 type_lang u_intl6 attr rev u int32 color Description _os_load opens a file specified by the pathlist It reads one or more memory modules from the file into memory until an error or end of file is reached Then it closes the file Modules are loaded into the highest physical memory available of the specified color type mod name is a pointer to the module name mod head is a pointer to the location where os 1oad stores the pointer to the module mod exec is a pointer to the location where os 1oad stores the pointer to the module execution entry point mode specifies the access mode Only the lower 16 bits of mode are used The type and language of the module are passed at the location pointed to by type lang os load also stores the actual type and language at the location pointed to by type lang lf type langis zero any module can be linked to regardless of the type and language attr rev is a pointer to the location where os load stores the attribute and revision level of the module When a module is loaded its name is added to the system module directory and the first module read is linked The returned parameters are the same as those returned by a link call and apply only to the first module loaded Note os load does not work on SCF devices Attributes Operating System OS 9 and OS 9 for 68K State User and System
398. module 457 Os get blkmap 635 os link 697 os linkm 699 os loadp 702 _os9 allpd 515 _os9 findpd 624 _os9 retpd 730 _setcrc 927 allocate fixed length block 515 allocate from arena 423 444 allow access to 716 arena 423 change size of block 898 check accessibility 532 compare 453 copy 454 455 copy external 542 create data memory module 457 create module 441 fill 456 find fixed block 624 get free block map 635 link to module 467 469 471 697 699 702 load module 469 471 700 702 into colored memory 464 make_module 441 modcload 464 modlink 467 modload 469 modloadp 471 prevent access to block 720 request internal 358 resize block 898 ABCDEFGHIJKLMNOPQRSTUVWXYZ resize block of 434 resize data area 707 return 271 420 return fixed block 730 return pointer to memory block 358 re valicate module CRC 927 search 452 set minimum allocation size 445 set reclamation bound 274 translate address 844 846 update CRC 927 header parity 927 memory area clear bzero 150 compare bemp 145 copy bcopy 146 memory arena 444 memory management _cpymem 62 179 _freemem 62 272 _Icalloc 62 416 _lfree 62 420 _Imalloc 62 423 _lrealloc 62 434 mallocmin 63 445 os alltsk 63 516 os chkmem 532 os cpymem 63 542 os deltsk 63 559 os mem 63 707 os permit 64 716 os protect 64 720 os srqmem 64 790 os srimem 64 794 _os9 srqmem 64 792 os9 translate 64 846
399. mory string h memset Fill memory string h 708 saJltskt os chkmem oS cpymem os deltsk os get blkmap os mem os move Allocate task Check memory block s accessibility Copy external memory Deallocate process descriptor Get free memory block map Resize data memory area Move data low bound first process n process n process n process n memory h memory h memory h WX MICROWARE Table 1 13 Memory Management Functions continued Function Standard Description Header File _os_permit _os_protect os srqgmem os9 srqmem os srtmem _os transadd _os9_translate realloc sbrk srqcmem _srqmem _srtmem Allow access to memory block Prevent access to memory block System memory request System memory request Return system memory Translate memory address OS 9 Translate memory address OS 9 for 68k Resize block of memory Extend data memory segment Allocate colored memory System memory request System memory return process h process h memory h memory h memory h virtual h memory h stdlib h stdlib h memory h memory h memory h Miscellaneous Functions Miscellaneous functions in Table 1 14 appear in the Ultra C libraries to relieve you from routine tasks ANSI prototypes for non ANSI functions are achieved by defining the macro nam
400. munication Functions continued Function ANSI Standard Description Header File _os_ev_tstset _os_ev_unlink os ev wait os9 ev wait os ev waitr os9 ev waitr _os_intercept _os9_salarm_atdate _os_salarm_atime _os9_salarm_at jul _os_salarm_cycle Wait for event to occur Unlink event Wait for event to occur Wait for event to occur Wait for relative event to occur Wait for relative event to occur Set up signal intercept trap Execute system state subroutine at events h events h events h events h events h events h signal h alarm h Gregorian date time Execute system state subroutine at specified time Execute system state alarm h alarm h subroutine at Julian date time Set cyclic alarm clock alarm h Table 1 10 Interprocess Communication Functions continued ANSI Function Standard Description Header File os9 salarm cycle Execute alarm h system state subroutine every n ticks seconds _os_salarm_delete Remove pending alarm h alarm request _os_salarm_reset Reset alarm clock alarm h _os_salarm_set Set alarm clock alarm h _os9_salarm_set Execute alarm h system state subroutine after specified time interval _os_sema_init Initialize semaphore semaphore os sema p oS sema term os sema v os send data structure for use Reserve sem
401. n Functions continued AN MICROWARE Function ANSI Standard Description Header File _os9_id 08 nproc 35 thaposi os setpr _os_sleep _os9_sleep _os_suspend Ds wait os9exec osO9forkt osSforkcti os9kexec setpr sleep Get process ID user ID Start next process Deallocate process descriptor Set process priority Put calling process to sleep Put calling process to sleep Suspend process Wait for child process to terminate OS 9 for 68K system call processing Create process OS 9 create process Set process priority Suspend execution for specified time process h process n process n process n signal h signal h process n process n process n process n types h process h signal h Table 1 19 Process Manipulation Functions continued ANSI Function Standard Description Header File tsleep Sleep for specified signal h interval wait Wait for process process h termination Resource Locks On OS 9 for 68K systems the functions identified in Table 1 20 are available for use with resource locks For more information about resource locks refer to the OS 9 for 68K Technical Manual Table 1 20 Resource Lock Functions ANSI Header Function Standard Description File _os_acqlk Acquire ownership of resource lock h lock _os_caqlk Conditionally acquire ownership 1ock h
402. n ctype h does not operate well with values outside the range of an unsigned char The function checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b isxdigit c Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Ultra C Library Reference 409 410 Library ctype h See Also isalnum isalpha lSCUDEL ispunct isspace isupper WX MICROWARE Ultra C Library Reference _julian Convert Date Time to Julian Value Syntax include lt time h gt int _julian int time int date Description julian converts the time and date from Gregorian format to the Julian equivalents time and date are pointers to the Gregorian format time and date values The following format is assumed Figure 2 5 julian Input Date and Time Formats Time 0 Hour 0 23 Minute Second Date Year 2 bytes Month Day Byte 0 Byte 1 Byte 2 Byte 3 julian modifies the objects to which its parameters point as follows Fig
403. n errno occurs if x is zero 10910 returns HUGE VAL for both errors Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clin i Possible Errors EDOM ERANGE WX MICROWARE longjmp Non Local Goto Syntax include setjmp h void longjmp jmp buf env int val Description longjmp and set jmp allow program control to return directly to a higher level function They are most useful when dealing with errors and signals encountered in a low level routine env is the program environment buffer val is the error status value longjmp restores the environment saved by the most recent call to set jmp in the same execution of the program with the corresponding jmp buf parameter If there has been no such call or if the function containing the set jmp call has returned in the interim the behavior is undefined All accessible objects have values as of the time 1ong jmp was called except that the value of objects of automatic storage duration that are local to the function containing the call to the corresponding set jmp call and 1ong jmp call are indeterminate Because it bypasses the usual function call and return mechanisms longjmp executes correctly in contexts of interrupts signals and any of their associated functions However if 1ong jmp is called from a nested signal handler that is from a f
404. n math h sqrt Square root function math h srand Set seed for random number stdlib generator tan Tangent function math h tanh Hyperbolic tangent function math h WX MICROWARE Memory Management Functions The memory management functions are provided for requesting and freeing memory in a machine and operating system independent manner ANSI prototypes for non ANSI functions are achieved by defining the macro name OPT_PROTOS during the compile Table 1 13 Memory Management Functions Function Standard Description Header File calloc Allocate storage for array stdlib h cpymem Copy external memory process h ebrk Get external memory stdlib h free Return memory stdlib h _freemem Determine size of unused stdlib h freemem stack area _freemin Set memory reclamation stdlib h bound ibrk Request internal memory stdlib h Qqealies Allocate storage for array stdlib h low overhead _lfree Return memory stdlib h low overhead J 1malloc Allocate memory from stdlib h arena low overhead lrealloc Resize block of memory stdlib h low overhead Table 1 13 Memory Management Functions continued ANSI Function Standard Description Header File malloc Allocate memory from stdlib h arena _mallocmin Set minimum allocation stdlib h size memchr Memory search string h memoemp Compare memory string h memcpy Copy memory string h memmove Move me
405. n through the os dexec and os dexit system calls priority is the priority of the new process Only the lower 16 bits of priority are used path cnt is the number of the I O paths for a child to inherit Only the lower 16 bits of path cnt are used mod name is the module name pointer params is a pointer to an additional parameter block param size is the size of the parameter block mem size specifies any additional stack space to allocate mem size is specified in bytes WX MICROWARE proc idis a pointer to the location where os9 dfork stores the child process ID type lang specifies the desired type and language Only the lower 16 bits of type lang are used reg buf is a pointer to a copy of all child registers Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also OS dexec os dexit oS fork FSDFork OS 9 for 68K Technical Manual os dforkm Fork Process Under Control of Debugger Syntax include lt dexec h gt finclude lt types h gt error code os dforkm int32 priority u int32 path cnt mh com mod head void params u int32 param size u int32 mem size process id proc id regs reg stack fregs fregstack Description os dforkm creates a new process which becomes a child of the caller It sets up the process memory MPU registers and standard I O paths In additi
406. n time Because the system time and date may be changed the alarm signal is sent when the system time and date become greater than or equal to the alarm time If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno If errors do not occur alm atjul returns the alarm ID For More Information Refer to your operating system technical manual for information about alarms Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library Sys clrb L See Also os9 alarm atjul oS alarm set WX MICROWARE alm cycle Set Alarm at Specified Time Intervals Syntax include lt alarm h gt int alm_cycle int sigcode int time interval Description alm cycle sends a signal to the requesting process after the specified time has elapsed and then resets the alarm to provide a recurring periodic signal sigcode specifies the signal to be sent to the caller time interval specifies the periodic interval at which the signal is to be sent For example if the request is made at time x and time intervalis t the signal is sent to the requesting process at times X t X 2t X 3t and so forth until the alarm is deleted If the most significant bit of time intervalis set time interval is assumed to be in 256ths of a second Otherwise time intervalis assumed to be in
407. nam 66 722 os rdalst 49 725 os read 49 726 os readin 49 728 os rellk 80 729 Os rte 59 731 os rtnprc 78 732 Os salarm atime 56 735 os salarm cycle 56 738 os salarm delete 57 742 743 OS salarm reset 57 744 Os salarm set 57 745 OS scache 66 747 OS seek 39 753 OS sema init 57 754 Os sema p 57 755 OS sema term 57 ABCDEFGHIJKLMNOPQRSTUVWXYZ Os sema v 57 757 os send 57 758 OS setcrc 70 759 OS setime 88 760 OS setpr 78 764 OS setstat 41 765 OS setsvc 66 766 OS setsys 41 770 Os setuid 66 771 OS sgetstat 41 772 os sgs devnm 41 773 _os_sigmask 58 777 OS sigreset 58 779 Os sigrs 58 781 os sleep 78 782 os slink 70 786 os slinkm 71 788 os srqmem 64 790 OS srtmem 64 794 OS ss attr 41 795 OS ss break 41 796 OS ss cache 42 797 OS ss close 42 798 os ss dcoff 42 799 _os_ss dcon 42 800 os ss dopt 42 801 OS ss dsrts 42 802 OS ss enrts 42 803 OS ss erase 42 804 os ss fd 42 805 Os ss fillbuff 42 os ss flushmap 42 807 os ss hdlink 42 808 Os ss lock 42 810 os ss luopt 43 811 OS ss popt 43 813 Os ss relea 43 814 OS ss rename 43 815 OS ss reset 43 816 OS ss reten 817 OS ss rfm 43 ABCDEFGHIJKLMNOPQRSTUVWXYZ Os ss sendsig 43 819 OS Ss size 43 820 Os ss skip 43 821 OS ss skipend 43 822 OS ss ticks 43 823 OS ss wfm 43 824 OS ss wtrack
408. nclude lt modes h gt int close int path Description close closes an open path The path number is usually obtained by a previous call to open creat create or dup The standard paths 0 1 and 2 standard input standard output and standard error respectively are not normally closed by user programs path specifies the open path to close If an error occurs during the close 1 is returned and the appropriate error code is placed in the global variable errno Note Be sure to use only a path number not a file pointer assigned by fopen Note The thread enabled version of this function contains a cancel point For more information see Using OS 9 Threads Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Functions Library Sys clib l See Also open creat create dup os close Ultra C Library Reference 173 WX MICROWARE closedir Close Named Directory Stream Syntax include dir h void closedir DIR dirp Description closedir closes the named directory stream and frees the structure associated with dirp dirp is a pointer to the directory stream Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library Sys clib 1l1 See Also opendir readdir rewinddir seekdir telldir _cmpnam Compare Tw
409. nd return mechanism set jmp h contains prototypes for the following functions longjmp setjmp System global symbolic names This is obsolete It has been replaced with sysglob h setsys h contains prototypes for the following functions getsys setsys Data structures and functions used to trap user state exceptions sett rap h contains prototypes for the following functions s strap os9 strap i Indicates a standard ANSI header WX MICROWARE Table 1 2 Ultra C Header Files continued File Description sg_codes h Symbolic names for Set Stats and GetStats sg_codes h contains prototypes for the following functions getstat _gs_devn gs_eof _gs_opt gs pos ge rdyt _gs_size _os_getstat 05 qs epypdi os gs d vnm 058 gs devtyp os gs dopt os gs eof os9 gs free 05 gs luopti os gs popt i Os gs pos os gs ready OS gs size os setstat os sgetstat os sgs devnm 05 5s attri os ss breaki os ss dopt os ss link adj E ss luspti os 5ssS popti O5 ss relea l os ss rename OS ss reset os ss sendsig oS SS size setstat S8 alter ss opti ss rell ss resti _ss_size _ss_ssig sgstat h Path descriptor option section definitions Indicates a standard ANSI header Table 1 2 Ultra C Header Files continued File Description signal h f stat h stdarg h f stddef h f Used for handling vario
410. nd OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 0S sS wWtrack Write Format Track Syntax include lt rbf h gt finclude lt types h gt error_code _os_ss_wtrack path_id path void trkbuf void ilvtbl u int32 track u int32 head u int32 interleave Description OS ss wtrack causes a format track operation used with most floppy disks to occur For hard or floppy disks with a format entire disk command this formats the entire media only when the track number and side number are both zero path is the path number trkbuf is a pointer to the track buffer ilvtbl is a pointer to the interleave table The interleave table contains byte entries of LBNs ordered to match the requested interleave offset track is the track number head is the side number interleave is the interleave value Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes WX MICROWARE Library os lib l See Also I SetStt OS 9 for 68K Technical Manual I SETSTAT OS 9 Technical Manual os strap Set Error Trap Handler Syntax include lt settrap h gt finclude lt types h gt finclude lt regs h gt error code os strap u int32 excpt stack strap init tb1 Description os strap enables user programs to catch process local program exceptions such as illegal instructions and divide by zeroes
411. nd System Threads Safe Re entrant Yes Library Sys clib l See Also 089 link os loadt FSLink F_LI NKM WX MICROWARE OS 9 for 68K Technical Manual OS 9 Technical Manual modload Load and Link to Memory Module Syntax include lt module h gt mh_com modload char modname int accessmode Description modload loads all modules in the file specified by the path modname modname is a pointer to the name of the module accessmode specifies the module s access mode If any module access mode is acceptable specify zero for accessmode Only the lower 16 bits of accessmode are used A link is made to the first module loaded from the file and a pointer to it is returned The module h header file contains a structure appropriate for accessing the elements of system defined memory modules If the load is successful modload returns a pointer to the module If the load fails 1 is returned and the appropriate error code is placed in the global variable errno To load a module using the shell PATH variable list see os 1oadp or modloadp Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l1 WX MICROWARE See Also os lIinkt os load _os loadpi FSLoad OS 9 for 68K Technical Manual F_LOAD OS 9 Technical Manual modloadp Load and Link to Memory Module Using PATH Synt
412. nd System Threads Safe Re entrant Yes Library os lib l mt os lib l1 See Also os thtork os thfork Fork a Thread Syntax include lt threads h gt error code os thfork thread t threagd thread attr t attr void stack top u int32 stack size void func void arg void gata Description os thfork forks a new thread of control in the current process thread is a pointer to a thread t object which is used to return the newly created thread s ID attr is a pointer to a thread attribute structure The thread attribute structure is declared in threads h stack top is a pointer to the top of user stack to be used by this thread stack top will be the initial stack pointer for the thread If the value pointed to by stack size is non zero the thread s user stack will be allocated by the system and a pointer to the allocated memory will be returned in the location pointed to by stack top The size of the actual stack allocated will be returned at stack size If stack size points to zero the value pointed to by stack top will be used as the thread s stack func is the address of the initial function to be executed by the forked thread arg is passed as the only argument to the function specified by func data is the address of thread specific data The value pointed to by data is maintained while the thread runs Attributes Operating System State Threads Re entrant Library
413. nd line e fstringisa null pointer system returns non zero only if a command processor is available e Ifstringis nota null pointer system returns the exit status of the forked shell The shell used to execute the string is either the current value of the SHELL environment variable or shel11 if SHELL is unavailable Note The thread enabled version of this function contains a cancel point For more information see Using OS 9 Threads Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library GlIbsl WX MIC ROWARE system_addr Address Translation Function Syntax finclude lt regs h gt void system_addr void addr Description system_addr returns the system state version of the specified address If the passed address is already in the system state address space or address translation is not applicable on the host processor it is returned untouched addr is the address to be converted to its system state address system addr returns the system state version of the specified address Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library cpu l See Also user addr tan Tangent Function Syntax include lt math h gt double tan double x Description tan returns the tangent of x x is presumed to be in radians Attributes Operating System
414. ndef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b isalnum c Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Ultra C Library Reference Library clib 1 See Also isspace isupper H n je Hh H m 2 ct E oe utm eS ae ee unm cai me Ultra C Library Reference 377 WX MIC ROWARE isalpha See If Parameter Is Alphabetic Syntax include lt ctype h gt int isalpha int c Description isalpha returns a non zero value for any character for which isupper Orislower is non zero isalpha returns non zero only for the characters for which isupper or islower is non zero c is the character to test co Note This routine available as a function or a macro in ctype h does not operate well with values outside the range of an unsigned char The function checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b isalpha c
415. ndicate any type or language Only the lower 16 bits of type and lang are used datasize allocates extra memory to the new program If no extra memory is required datasize can be zero prior is the new priority at which to run the program Specify zero if no priority change is desired Only the lower 16 bits of prior are used pathent is the number of open paths for the new process to inherit Only the lower 16 bits of pathent are used Regardless of whether the chain is successful chainc never returns to the caller you must verify that the program to chain to exists and is executable before chaining Use modlink to check the module directory for the program or modload to check the execution directory chain is the same as chainc without the pathent parameter The number of open paths for the new process to inherit is three For More Information os exec is the preferred method by which to chain to C programs Note Beware of chaining to a system state program chain is an historical function and is likely to be removed in a future release os exec is the recommended function Attributes Operating System State Threads Re entrant Library Sys clib l1 See Also modlink modload os chain os9fork0 osSforkel cos Porkt _os_exec FSChain F Fork F_CHAIN F_FORK OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 T
416. ndicated by the control string vsprintf is similar to sprintf However arg replaces the variable parameter list str is a pointer to a string format is a pointer to a control string arg is initialized by va start and possibly subsequent va arg calls vsprintf does not call va end If copying takes place between overlapping objects the behavior is undefined vsprintf returns the number of characters written in the array not counting the terminating null character For More Information The sclib 1 and sclib il libraries contain a smaller version of the vsprintf function Refer to the Using Ultra C C manual for more information about the small library functions Attributes Operating System State Threads Re entrant Standards Library clib l See Also fprintf sprintf va arg va end va starti WX MICROWARE OS 9 and OS 9 for 68K User and System Safe No ANSI wait Wait for Process Termination Syntax finclude process h int wait unsigned int status int wait 0 Description wait Suspends the current process until a child process has terminated status is a pointer to a storage location where the exit status of the terminating child process is stored wait returns the process ID of the terminating child process and places the exit status of that process in the unsigned int pointed to by status If status is passed as zero no chi
417. ner of File Syntax include lt modes h gt int chown char name int newowner Description chown changes the owner number of a file name is a pointer to the name of the file newowner Is the new owner ID to assign to the file The owner ID consists of a group ID and a user ID For More Information Refer to your operating system technical manual for information about how the owner ID is stored chown returns zero after a successful call If the caller does not have permission to change the owner ID or the file cannot be found 1 is returned and the appropriate error code is placed in the global variable errno Note Only the super user may change the owner ID Attributes Operating System State Threads Re entrant Library Sys clib l See Also dom 38 Oc ISSetStt I SETSTAT SS FD OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual AN MICROWARE chxdir Change Current Execution Directory Syntax include modes h int chxdir char dirname Description chxdir changes the current execution directory for the calling process dirname is a pointer to a string containing the directory name chxdir returns 0 after a successful call If dirname is not a directory path name or some other error occurs 1 is returned and the appropriate error code is placed in the global variable errno Note chxdir
418. ng strtod nptr char NULL Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 See Also strtod WX MIC ROWARE atoi Alpha to Integer Conversion Syntax include lt stdlib h gt int atoi const char string Description atoi converts a string into its equivalent representation in type int string is a pointer to the string Except that no error indication is given atoi is equivalent to the following int strtol nptr char NULL 10 Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 See Also strtolt atol Alpha to Long Conversion Syntax include lt stdlib h gt long atol const char string Description atol converts a string into its equivalent representation in type long string is a pointer to the string Except that no error indication is given ato1 is equivalent to the following strtol nptr char NULL 10 Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 See Also setrtolti WX MICROWARE _aton Alpha to Numeric Translation Syntax include lt aton h gt _number_type _aton char put number value Description _aton converts a string into its as
419. ng System OS 9 State System Threads Safe Re entrant Yes Library lock l See Also F ACOLK OS 9 Technical Manual F CAQLK OS 9 Technical Manual F CRLK OS 9 Technical Manual F DDLK OS 9 Technical Manual F DELLK OS 9 Technical Manual F RELLK OS 9 Technical Manual F WAITLK OS 9 Technical Manual WX MICROWARE os datmod Create Data Module Syntax include lt module h gt finclude lt types h gt error_code _os_datmod char mod name u int32 size u intl6 attr rev u_int16 type_lang u_int32 perm void mod exec mh data mod head Description os datmod creates a data module with the specified attribute revision and clears the data portion of the module The module is created and entered into the system module directory mod name is a pointer to the module name string size is the size of the data portion The module s desired attribute and revision are passed at the location pointed to by attr rev os datmod also stores the module s attribute and revision at the location pointed to be attr rev The module s desired type and language are passed at the location pointed to by type lang os datmod also stores the module s actual type and language at the location pointed to by type 1ang perm specifies the access permissions for the module Only the lower 16 bits of perm are used mod exec is a pointer to the location where os datmod stores the pointer to the module da
420. ng System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l Example main int date time tick short day _sysdate 0 amp time amp date amp day amp tick See Also _os_getime _os_julian FSJulian OS 9 for 68K Technical Manual FSTime OS 9 for 68K Technical Manual F_TIME OS 9 Technical Manual WX MICROWARE _sysdbg Call System Debugger Syntax finclude lt process h gt int _sysdbg void Description _sysdbg starts the system level debugger if one exists This allows you to debug system state routines such as drivers The system level debugger runs in system state and effectively stops timesharing whenever it is active Only the super user can make this call Note If the system does not have a system level debugger the system is reset Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library sys_clib 1 See Also s syvedbgi F SysDbg OS 9 for 68K Technical Manual F SYSDBG OS 9 Technical Manual system Shell Command Execution Syntax include lt stdlib h gt int system const char string Description system passes a string to the shell for execution A null pointer may be used for the string to inquire whether a command processor exists string is a pointer to the string to pass to the shell The string may be any valid shell comma
421. ng of one or more unrecognized characters including the terminating null character of the input string strtol then attempts to convert the subject sequence to an integer and returns the result WX MICROWARE If base is zero the subject sequence is expected to be an integer constant optionally preceded by a plus or minus sign An integer suffix is not included If the subject sequence is an integer constant the character sequence starting with the first digit is interpreted as an integer constant If base is between 2 and 36 the subject sequence is expected to be a sequence of letters and digits representing an integer base specifies the radix optionally preceded by a plus or minus sign An integer suffix is not included The letters from a through z regardless of case are assigned the values 10 to 35 Only letters with assigned values less than base are permitted If base is 16 the characters 0x or OX may optionally precede the sequence following the sign if present If the subject sequence has the expected form it is used as the base for conversion ascribing to each letter its value If the subject sequence begins with a minus sign the value resulting from the conversion is negated A pointer to the final string is stored in end unless end is a null pointer If the subject sequence is empty or does not have the expected form no conversion is performed begin is stored in end unless end is a null pointer strtol
422. ngs h gt finclude lt types h gt error_code _os_cmpnam char pattern char string u int32 length int32 cmp result Description os cmpnam compares a target name to a source pattern to determine if they are equal os cmpnam is not case sensitive it does not differentiate between upper and lower case characters pattern is a pointer to the pattern string Two wildcard characters are recognized in the pattern string Aquestion mark matches any single character e An asterisk matches any string string is a pointer to the target name string The target name must be terminated by a null byte length specifies the length of the pattern string cmp result is a pointer to the location where os cmpnam stores the lexicographic result of the comparison os cmpnam returns zero if the target string is the same as the pattern string OS 9 for 68K If the error Eos PNNF is returned the strings differ and the integer at the address passed in cmp result is not changed OS 9 If the error EOS DIFFER is returned the strings differ and the integer at cmp result has the following meaning Table 2 17 os cmpnam Parameter cmp result Values Integer Description positive The target name is less than the pattern string negative The target string is greater than the pattern string Note On OS 9 for 68K you never receive an EOS DIFFER error On OS 9 you never receive an EOS PNNF err
423. nkmi Link to memory module module h by module pointer os load Load module s from module h file os loadp Load and link to a module h memory module using PATH _os_makmdir Create new module moddir h directory OS mkmodule Create module of module h specified color type os modaddr Find module given module h pointer Jos setcrc Generate valid CRC in module h module _os_slink Install subroutine module h module Table 1 15 Module Manipulation Functions continued Function Standard Description Header File _os_slinkm Install user subroutine module h library module by module pointer _os_tlink Install system state trap module h handling module os tlinkm Install user trap module h handling module by module pointer s unlink Unlink module by module h address _os_unload Unlink module by name module h os vmodul Verify module module h _os9_vmodul Validate module module h _setcrc Re validate module module h CRC _subcall Call subroutine module module h AN MICROWARE Multibyte Character and String Functions Five functions identified in Table 1 16 are available for handling multibyte characters and strings Table 1 16 Multi byte Character String Functions ANSI Header Function Standard Description File mblen Determine number of bytes in stdlib h multibyte character mbstowcs Convert sequence of multibyte stdlib h characters
424. nlink call need not block until all references have been closed it may return immediately Upon successful completion mq unlink returns a value of 0 Otherwise the named message queue is not changed by this function call and the function returns a value of 1 and sets errno to indicate the error Errors EACCES Permission is denied to unlink the named message queue ENAMETOOLONG The length of the name string exceeds NAME MAX while POSIX NO TRUNC is in effect ENOENT The named message queue does not exist ENOSYS mq unlink not supported Attributes Operating System OS 9 State User Threads Safe Re entrant No Standards POSIX Library mq l See Also mq_close mq_open WX MICROWARE munlink Unlink from Module Syntax include lt module h gt int munlink mh_com module Description munlink informs the system that the process no longer requires the specified module The module s link count is decremented and the module is removed from memory if the link count reaches zero module is a pointer to the module It must have been a pointer returned by modcload modload modloadp modlink os link _os_load Of _os_loadp On error 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library sys_clib 1 See Also modcload
425. nly 20K even if 200K is available elsewhere If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library Sys clib l1 See Also os mem os srqmem F Mem OS 9 for 68K Technical Manual F MEM OS 9Technical Manual scanf Input Strings Conversion Syntax include lt stdio h gt int scanf const char format Description scanf reads input from stdin format is a pointer to the control string scanf returns EOF if an input failure occurs before any conversion Otherwise scanf returns the number of input items assigned which can be fewer than provided for or zero in the event of an early matching failure Note The sclib 1and sclib il libraries contain a smaller version of the scanf function Refer to the Using Ultra C C manual for more information about the small library functions Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also fscanf sscanf AN MICROWARE sched yield Yield Processor Syntax include lt sched h gt int sched_yield void Description sched yield gives up a thread s timeslice allowing the kernel to reschedule the active threads If there are other active threads at the same pri
426. nt time int date short day int tick Description _sysdate obtains the current time date day of week and clock tick from the system Note that all the parameters except format are pointers to the receiving locations format specifies the format of the date and time to return format can be any of the following e 0 Gregorian e 2 Gregorian with ticks e 1 Julian e 3 Julian with ticks time is a pointer to the location where sysdate stores the time value date is a pointer to the location where sysdate stores the date value day is a pointer to the location where sysdate stores the day of week value tick is a pointer to the location where sysdate stores the tick value WX MICROWARE The values are returned in the following format Figure 2 10 sysdate Return Format Byte 0 Byte 1 Byte 2 Byte 3 Time 0 Hour 0 23 Minute Second Gregorian Seconds Since Midnight 0 86399 Julian Date Year 2 bytes Month Day Gregorian Julian Day Number Julian Day Day of Week 0 Sunday 1 Monday Tick No of Ticks Second Current Clock Tick If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Note Be careful to pass pointers to the date t ime and day values Also be sure day is declared to be a short or the value appears as day 05536 Attributes Operati
427. nt index to use to begin the search size specifies the buffer size buffer is a pointer to the buffer containing the event information On OS 9 the name of the event is appended to the end of the information structure buffer and size must be large enough to accommodate the name of the target event OS ev info returns the event information block for the first active event whose index is greater than or equal to this index If no such event exists an error is returned Attributes Operating System State Threads Re entrant Library os lib l See Also FSEvent F EVENT F EVENT EV INFO F EVENT EV SIGNL OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual OS 9 for 68K Technical Manual OS 9 for 68K Technical Manual OS 9 for 68K Technical Manual WX MICROWARE os9 ev info Return Event Information Syntax include lt events h gt finclude lt types h gt error code os9 ev info int32 index ev infostr bufter Description os9 ev info returns event information in the caller s buffer The returned information is defined by the ev infostr event information structure defined in events h The event index to begin the search for a valid event is passed at the location pointed to by index os9 ev info also stores the event index of the valid event found if any at the location pointed to by index buffer is a pointer to a b
428. nt location 1041 pointer to 893 rewinddir 906 seekdir 913 set alternate working module directory 518 position of next readdir 913 telldir 1041 disable RBF caching 797 RTS line 802 977 div 60 193 double to ASCII conversion 194 driver Os ss close 798 _os9 ss open 812 notify of open path 812 notify that path has closed 798 dtoa 194 dup 103 196 dup2 197 duplicate path 196 197 571 ebrk 62 103 198 EDT 84 EET 84 ABCDEFGHIJKLMNOPQRSTUVWXYZ enable RBF caching 797 RTS line 803 978 end references to current variable parameter list 1071 endpwent 200 enter O queue 685 process in active process queue 520 environment change or add value 885 environment functions _exit 35 232 os exit 35 621 abnormal program termination 35 114 abort 35 114 atexit 35 136 exit 35 233 get value for environmentname 35 307 getenv 35 307 listed 35 register function to call at normal program termination 35 136 shell command execution 35 1037 system 35 1037 task termination 35 232 233 terminate calling process 35 621 environment name get value for 307 environment names common set of 101 environment variables TERM 1043 TERMCAP 1043 TZ 84 102 ERANGE 92 erase tape 804 errno 92 value to which macro is set on failure 100 errno h 16 error _errmsg 201 os perr 718 ABCDEFGHIJKLMNOPQRSTUVWXYZ os strap 827 OS9 strap 829 check buffered file for error condition 242 clear 170 displ
429. nt memory is not available in the arena 1malloc calls srqmem to get more memory from the system lmalloc returns NULL if no memory is available or if the arena is detected to be corrupted Note Use of the low overhead allocation functions 1calloc lmalloc and l1realloc instead of the general allocation functions calloc malloc and realloc saves 8 bytes per allocation because the low overhead functions do not save the allocation size or the 4 byte check value WX MICROWARE Note Use extreme care to ensure that you only access the memory assigned by 1malloc Modifying addresses immediately above or below the assigned memory or passing 1free a value not assigned by lmalloc causes unpredictable program results The low overhead functions require that you keep track of the sizes of allocated spaces in memory Note the 1 ree and 1realloc parameters Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library CIE See Also _Lealloc lfree lrealloc malloc mallocmin calloc free os srqmem realloc localeconv Numeric Formatting Convention Inquiry Syntax include lt locale h gt struct lconv localeconv void Description localeconv sets the components of an object with type struct lconv with values appropriate for formatting numeri
430. nter If the subject sequence is empty or does not have the expected form no conversion is performed begin is stored in end unless end is a null pointer strtoul returns the converted value if any If no conversion could be performed zero is returned If the correct value is outside the range of representable values ULONG MAX is returned and ERANGE is stored in errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library elib il 1026 See Also isspace Birctodtf strrteli Possible Error ERANGE WX MICROWARE Ultra C Library Reference strxfrm Transform String Syntax include lt string h gt size t strxfrm char dest const char trans size t count Description strxfrm transforms t rans and places the result in dest You can then use strcmp to compare two transformed strings The result of the strcmp on the transformed strings is the same as the result of strcoll applied to the two original strings dest is a pointer to the destination string trans is a pointer to the string to transform count specifies the maximum number of characters to place in dest count includes the terminating null character If count is zero dest can be a null pointer If copying takes place between overlapping objects the behavior is undefined strxfrm returns the length of the transformed string not inclu
431. o Strings Syntax include lt strings h gt error code cmpnam uchar pattern uchar string uint32 length Description cmpnam compares the target string to the pattern string to determine if they match target is a pointer to the target string The target name must be terminated by a null byte Upper and lower case characters are considered to match pattern is a pointer to the pattern string Two metacharacters are recognized in the pattern string e A question mark matches any single character Anasterisk matches any string of characters patlen specifies the length of the pattern string cmpnam returns zero if the strings match 1 is returned if no match Occurs Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l WX MICROWARE See Also os ecmpnam FSCmpNam OS 9 for 68K Technical Manual F_CMPNAM OS 9 Technical Manual cos Cosine Function Syntax include lt math h gt double cos double x Description cos returns the cosine of x as a double The value of x is in radians A domain error EDOM placed in errno occurs if x is or oe cos returns HUGE VAL on error Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 Possible Error EDOM WX MICROWARE cosh Hyperbolic
432. o a Universal Coordinated Time value tp is a pointer to a broken down time structure Broken down time has the following format struct tm int tm_sec seconds after the minute 0 59 int tm_min minutes after the hour 0 59 a int tm_hour hours after midnight 0 23 int tm_mday day of the month 1 31 int tm_mon months after January 0 11 int tm_year years after 1900 T int tm wday days after Sunday 0 6 i int tm yday days after January 1 0 365 int tm isdst Daylight Savings Time DST flag 0 no 1 yes 1 unknown e sys mktime ignores the input values of tm_wday and tm_yday It does not require the other fields of tm to be within the ranges specified in the structure Instead it normalizes the fields and sets tm wday tm yday and tm isdst This allows you to easily do temporal arithmetic without having to worry about mixed base operations WX MICROWARE HM Note If time t 1 returns to indicate an error there is a one second interval that appears to be non representable The encoding of times for time_t only represents times ranging from approximately 1902 to 2038 Attributes Operating System OS 9 State User and System Threads Safe Re entrant No Library Sys clib l See Also mktime Ultra C Library Reference _sysdate Get Current System Date Time Syntax include lt time h gt int _sysdate int format i
433. o place the file position indicator place has three possible values Table 2 11 fseek place Values Value Description SEEK SET The new file position is offset SEEK CUR The new file position is the current file position offset offset can be negative SEEK END The new file position is the current file size o set usually offset is negative or zero in this case A successful call to fseek clears the end of file indicator for the stream and undoes the effects of the ungetc function on the same stream After an seek call the next operation may be either input or output fseek returns non zero only for a request that cannot be satisfied WX MICROWARE For More Information The sclib 1 and sclib il libraries contain a smaller version of the fseek function Refer to the Using Ultra C C manual for more information about the small library functions Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also Freel j getc getchar putei putchari ungetc DQR ltr thrary Rafarar 286 Ultra C Library Reference fsetpos Set Current File Position Syntax include lt stdio h gt int fsetpos FILE stream const fpos t pos Description fsetpos sets the file position indicator for a stream stream is a pointer to the C I O FI
434. ode Values Mode Description _IOFBF I O is fully buffered _IOLBF I O is line buffered IONBF I O is unbuffered size specifies the array size The contents of the array at any time are indeterminate WX MICROWARE setvbuf returns zero if successful If an invalid value is given for mode or if the request cannot be honored setvbuf returns a non zero value Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 sigmask Control Process Signal Handling Syntax include signal h int sigmask int level Description sigmask controls the process signal mask A signal mask is an internal variable in each process descriptor which determines the signal handling for the process level specifies the signal level 0 specifies clear e 1 specifies increment e 1 specifies decrement The process signal level is not decremented below zero If a signal is received by a process whose signal mask is zero normal program flow is interrupted and the signal is processed by executing the program s intercept routine If a signal is received by a process whose signal mask is non zero the signal is placed in a queue of signals waiting to be processed The queued signals become active only when the process signal mask becomes zero Regardless of the signal mask value a process wakes up from event waits and
435. of a suspended child process created by os dfork The process performing os dexec is suspended and its debugged child process is executed instead This process terminates and control returns to the parent after the specified number of instructions have been executed a breakpoint is reached or an unexpected exception occurs The parent and the child processes are never active at the same time OS 9 os dexec controls the execution of a suspended child process created by F DFORK The process performing the F_DEXEC is suspended and its debugged child process is executed instead This process terminates and control returns to the parent after the specified number of instructions have been executed a breakpoint is reached or an unexpected exception occurs The parent and the child processes are never active at the same time WX MICROWARE proc idis the process ID of the child to execute mode specifies the debug mode params is the parameter list pointer num instr points to the location where the number of instructions to execute is passed os dexec also stores the number of instructions not executed at the location pointed to by num instr If the integer at num instr is zero commands are executed continuously num bpts specifies the number of breakpoints in the list Maximum of 16 break points allowed brk pts is a pointer to the pointer to the breakpoint list tot instr points to where the number of
436. ointed to by size os gs dopt also stores the actual number of bytes copied at the location pointed to by size dopts is a pointer to a buffer for the device path options Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os gs dsize Get Number of Blocks on Media Syntax include lt rbf h gt finclude lt types h gt error code os gs dsize path id path u int32 totblocks u int32 blocksize Description os gs dsize gets information about the number of blocks on the media path specifies the drive s path number totblocks is a pointer to the location where os gs dsize stores the total number of blocks on the device blocksize is a pointer to the location where os gs dsize stores the size of a disk block in bytes Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l1 os gs edt Get I O Interface Edition Number Syntax include ioedt h finclude lt types h gt error code os gs edt path id path u int32 edition Description OS gs edt returns the I O interface edition number of the driver and validates the compatibility of drivers and file managers path specifies the driver s path number edition is a pointer to the location where os gs edt stores the driver I O interface edition number Attributes Operating
437. on readin reads bytes from a path path specifies the path number of the file from which to read The path number is an integer indicating one of the standard path numbers 0 1 or 2 or a path number returned from a successful call to open creat create 0rdup buffer is a pointer to a space with at least count bytes of memory into which read puts the data read from the path count is the minimum buffer size It is guaranteed that at most count bytes are read Often less are read either because the path serves a terminal and input stops at the end of a line or the end of file has been reached readln causes line editing such as echoing to take place and returns once a n is read in the input or the number of bytes requested has been read read1n is the preferred call for reading from the terminal readln returns the number of bytes actually read 0 indicating end of file If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Note End of file is returned as zero bytes being read not an error indication Note The thread enabled version of this function contains a cancel point For more information see Using OS 9 Threads Attributes Operating System State Threads Re entrant Library Sys clib l See Also creat create dup open os readin read ISReadLn I READLN OS 9 and OS 9 for 68K User and Sys
438. on os dforkm allows a debugger utility to create a process whose execution can be closely controlled The created process is not placed in the active queue but is left in a suspended state This allows the debugger to control its execution through the os dexec and os dexit calls os dforkm is similar to _os_dfork However os dforkm is passed a pointer to the module to fork rather than the module name priority is the priority of the new process Only the lower 16 bits of priority are used path cnt is the number of I O paths for the child to inherit Only the lower 16 bits of path cnt are used mod headis a pointer to the module header params is a pointer to the parameter block param size specifies the size of the parameter block WX MICROWARE mem size specifies any additional stack space to allocate proc idis a pointer to the location where os dforkm stores the child process ID reg stack is a pointer to the register buffer fregstack is a pointer to the floating point register buffer Attributes Operating System State Threads Re entrant Library os lib l See Also s forkt os dexec _os_dexit 08 dtorkt OS 9 User and System Safe Yes _os_dup Duplicate Path Syntax include lt modes h gt finclude lt types h gt error code os dup path id dup path path id new path Description os dup returns a synonymous path number for an existing file
439. onous I O multiplexing 914 sys clib 11 102 sys mktime 88 108 1031 sysglob h 33 SYSRAM 442 464 709 966 system os sysid 833 _os9_setime 762 catastrophic occurrence 715 memory request 792 968 return 970 return identification 833 set date time 762 system call processing 611 617 691 system debugger os sysdbg 832 sysdbg 1036 call 832 1036 system global variables getsys 336 os getsys 649 os setsys 770 _setsys 942 change 770 942 ABCDEFGHIJKLMNOPQRSTUVWXYZ examine 649 942 get 336 set 770 942 system 35 1037 system_addr 1038 tan 61 1039 tangent function 1039 arc 134 135 hyperbolic 1040 tanh 61 1040 tape _os_ss erase 804 _os_ss reset 816 _os_ss reten 817 _os_ss rfm 818 Os ss skip 821 OS ss skipend 822 OS ss wim 824 erase 804 restore head to track zero 816 retension 817 skip blocks 821 marks 818 toend 822 write marks 824 task _os_alltsk 516 allocate 516 pause 869 suspend 869 termination 232 233 telldir 109 1041 tempnam 1042 temporary files create names for 1042 TERM 1043 TERMCAP 1043 ABCDEFGHIJKLMNOPQRSTUVWXYZ Termcap get entry 1043 tgetent 1043 termcap h 33 terminal check capability reference 1045 get capability ID 1046 1047 tgetflag 1045 tgetnum 1046 tgetstr 1047 terminal manipulation functions check terminal capability presence 83 1045 get cursor movement capability 83 1049 termcap entries 83 1043 t
440. operation resulting in overflow This signal is generated on target specific conditions SIGILL Detection of an invalid function image such as illegal instruction This signal is generated on target specific conditions SIGINT Receipt of an interactive attention signal generated by the keyboard interrupt character on OS 9 for 68K and OS 9 SIGSEGV An invalid access to storage This signal is generated on target specific conditions SIGTERM A termination request sent to the program WX MIC ROWARE Table 1 30 More Signals Signal Condition SIGKILL A death request sent to the program This signal cannot be ignored or handled SIGWAKE A wakeup request sent to the program If a process is active when this signal arrives it is ignored Otherwise the process is activated but the signal handling function is not called SIGQUIT Receipt of an interactive abort signal generated by the keyboard quit character on OS 9 SIGHUP Modem hangup signal This signal is sent to a process when a modem connection is lost SIGALRM Not automatically sent Programs can use this signal for an alarm call SIGPIPE Not automatically sent SIGUSR1 Condition is user defined SIGUSR2 Condition is user defined Overview Uverview Processor Specific Family Signals For More Information For information related to the exceptions see the reference manual for your specific processor 68K Family Processors Th
441. opies the bytes from src to dest until it reaches the null terminator strhcpy then removes the high bit from the last character and appends a null byte to the output string strhcpy is used primarily for copying file names from the directory entries on RBF disks st rhcpy returns its first parameter Note strhcpy assumes that dest contains adequate space for the copy The calling routine is responsible for verifying the space Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1 strlen Determine String Length Syntax include lt string h gt size t strlen const char str Description strlen determines the length of str str is a pointer to a string strlen returns the number of characters that precede the terminating null character Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 WX MICROWARE strncat String Catenation Syntax include lt string h gt char strncat char Org const char append size t count Description strncat appends characters a null character and characters that follow it are not appended from append to the end of orig The initial character of append overwrites the null character at the end of orig A terminating null character is always appended to the result If copy
442. or Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also FSCmpNam OS 9 for 68K Technical Manual F CMPNAM OS 9000 Technical Manual WX MICROWARE os config Configure an Element Syntax include lt sysglob h gt error_code _os_config u int32 code void param Description os config is a wildcard call that configures elements of the operating system which may or may not be process specific It dynamically reconfigures operating system resources at runtime The target resources may be system wide resources or they may be process specific depending on the nature of the configuration call being made code is the configuration command code Reference the OS 9 Technical Manual for a list of valid codes for your version of the operating system paramis a pointer to any additional parameters required by the specified configuration function Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes See Also Dg ioconfigi os cpy ioproc Get Pointer to I O Process Descriptor Syntax finclude process h finclude lt types h gt error code os cpy ioproc process id proc id void buffer u_int32 count Description _os_cpy_ioproc copies the I O process descriptor for the specified process into a buffer process idis the process ID buffer is a pointe
443. ore a process is created os9forkc and chainc are C level hooks to the system calls By themselves they provide no real parameter information This leaves the interpretation of a raw parameter string up to the cstart portion of the C program Problems can occur when handling quotes and control characters os9exec provides more precise control over the parameter strings and enables the environment variables to be easily inherited from the parent process os9exec closely resembles the UNIX execve system call func is a pointer to a function that creates a new process This function is normally chain chainc os9fork Oros9forkc func passes information to a new process as binary data specified by a pointer and size It is up to the forked process to interpret the data modname is a pointer to a string naming the new primary module argv is a pointer to the parameter pointer list that the new process receives By convention argv 0 is the name of the new module and a null pointer marks the end of the argv list WX MIC ROWARE envp is a pointer to the environment pointer list that the new process receives A null pointer marks the end of the envp list You can set envp to point to the environment list of the current process to allow the child to inherit that environment stacksize specifies the additional memory in bytes to allocate to the new process stack memory A stacksize of zero indicates the default sta
444. ore any calls to srand have been made the same sequence is generated as when srand is first called with a seed value of one seed is used as a seed for a new sequence of pseudo random numbers srand does not return a value Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib l See Also Fonda WX MICROWARE srqcmem Allocate Colored Memory Syntax include lt memory h gt char srqcmem int bytecnt int memtype Description srqcmem is a direct hook to the F SRqCMem for OS 9 for 68K or os srqmem for OS 9000 system call bytecnt is rounded to a system defined block size The size of the allocated block is stored in the global integer variable _srqcsiz If bytecnt is Ox fffff the largest contiguous block of free memory in the system is allocated memt ype indicates the specific type of memory to allocate memory h contains definitions of the memory types that you may specify Table 2 34 srqcmem Memory Types Memory Type Description SYSRAM Or MEM SYS System RAM memory VIDEO Video memory for plane A VIDEO2 Video memory for plane B MEM ANY No memory type specified If memt ype is MEM ANY any available system memory may be allocated If successful a pointer to the memory granted is returned The returned pointer always begins on an even byte boundary If the request was not granted
445. ority as the calling thread one of them will be given the processor The standard aging process occurs at every sched yield call sched yield works much like os sleep with a ticks value of 1 except that it does not implicitly unmask signals If successful 0 is returned otherwise an error number is returned Attributes Operating System OS 9 and OS 9 for 68K State Threads Re entrant Library Sys clib 1 See Also os sleep tsleep Example while not ready sched yield allow other threads to run User and System Safe Yes seekdir Set Position of Next Readdir Syntax include dir h void seekdir DIR dirp long LOG Description seekdir sets the position of the next readdir operation on the directory stream to loc dirp is a pointer to the directory Loc is the location for the next xeaddir operation loc is a specific position in the directory stream returned by a previous call to telldir Values returned by telldir are valid only for the lifetime of the associated di rp pointer If the directory is closed and then reopened the telldir value may no longer be valid It is safe to use a previous telldir value immediately after a call to opendir and before any calls to readdir Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also closedir opendir read
446. ority at which to run the program Indicate zero if no priority change is desired pathcnt is the number of the parent s open paths for the new process to inherit If the fork is unsuccessful 1 is returned and the appropriate error code is placed in the global variable errno If the fork is successful the process ID number of the new process is returned os9fork is the same as os9forkc without a pathcnt parameter os exec is the preferred method to fork C programs Note Beware of forking to a system module It only makes sense to fork to a program of type object module os9fork is a historical function and is likely to be removed in a future release Use os9forkc instead Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l WX MICROWARE For More Information The primary purpose of the sys clib 1 library is to provide a library for compatibility with the Microware K amp R C compiler For additional information refer to Appendix A Prototyping sys clib l Functions See Also os chain _os_exec Os rorkti FSChain OS 9 for 68K Technical Manual FSFork OS 9 for 68K Technical Manual F_CHAIN OS 9 Technical Manual F_FORK OS 9 Technical Manual os forkm Create New Process by Module Pointer Syntax finclude lt process h gt finclude lt types h gt error code os forkmQ u int32 priority u
447. ory count specifies the byte count for the section of memory accum is a returned value It is a pointer to the CRC accumulator If the CRC of a new module is to be generated the CRC is accumulated over the module excluding the CRC The accumulated CRC is complemented and stored in the correct position in the module The CRC is calculated over a specified number of bytes starting at the source address It is not necessary to cover an entire module in one call because the CRC may be accumulated over several calls The CRC accumulator must be initialized to 1 before the first os crc call for any particular module To generate the CRC of an existing module the calculation must be performed on the entire module including the module CRC The CRC accumulator contains the CRC constant bytes if the module CRC is correct The CRC constant is defined in module h as CRCCON The value is 0x00800fe3 To generate the CRC for a module 1 Initialize the accumulator to 1 WX MICROWARE 2 Perform the CRC over the module 3 Call F_CRC with a NULL value for start 4 Complement the CRC accumulator 5 Write the contents of the accumulator to the module The CRC value is three bytes long in a four byte field To generate a valid module CRC you must include the byte preceding the CRC in the check You must initialize this byte to zero For convenience if a data pointer of zero is passed the CRC is updated with one zero data byte
448. ory Syntax include UNIX os9def h void bzero void addr unsigned int len Description bzero clears bytes in memory starting from an address addr for a number of bytes 1en Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library unix l See Also bcopy bcmp frs1 calloc Allocate Storage for Array Syntax include lt stdlib h gt void calloc size_t nmemb size_t size Description calloc allocates space for an array The allocated memory is cleared to zeroes nmemb is the number of elements in the array size is the size of each array element If the allocation is successful calloc returns a pointer to the area If the allocation fails or if size is zero NULL is returned The space designated by the returned pointer is suitably aligned to hold an object of any type Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 2 Functions WX MIC ROWARE See Also ebrk free malloc _os_srqmem os9 srqmem realloc 152 Ultra C Library Reference cbrt Cube Root Syntax include UNIX os9def h double cbrt double x Description cbrt returns the cube root of x Note The declaration double cbrt must be included in any code that uses cbrt Attrib
449. ory h gt finclude lt types h gt error code os mkmodule char mod name u int32 size u intl6 attr rev u_int16 type_lang u_int32 perm void mod exec mh com mod head u int32 color Description os mkmodule creates a memory module with the specified name and attributes in the specified memory The module is created with a valid CRC and entered into the system module directory You can specify the type language of the module and color of memory in which to make the module mod name is a pointer to the name of the data module size specifies the size of the data portion to clear attr rev is a pointer to the location where os mkmodule stores the module s attribute and revision The type and language for the module are passed at the location pointed to by type lang os mkmodule also stores the actual type and language at the location pointed to by type lang perm specifies the access permissions for the module Only the lower 16 bits of perm are used mod exec is a pointer to the location where os mkmodule stores the pointer to the module data mod headis a pointer to the location where os mkmodule stores the pointer to the module header color is the memory color type SYSRAM VIDEO1 Or VIDEOZ2 If color is zero no memory type is specified Consequently the module is made in whatever memory the system allocates Note The created module always begins at offs
450. os crc always returns 0xff in the most significant byte of the accum parameter so accum may be directly stored after complement in the last 4 bytes of a module as the correct CRC For More Information Refer to your operating system technical manual for more information on how your operating system uses CRCs for modules Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also FSCRC OS 9 for 68K Technical Manual F_CRC OS 9 Technical Manual os create Create Path to New File Syntax include lt modes h gt finclude lt types h gt error code os create char name u int32 mode path id path u int32 perm axe Description _os_create creates a new file e Onmultifile devices the new file is entered in the directory structure e Onnon multifile devices create is synonymous with open name is a pointer to the path name of the new file mode specifies the access mode If data is to be written to the file mode must have the FAM WRITE Or S IWRITE bit set Only the lower 16 bits Of mode are used path is a pointer to the location where os create stores the path number that identifies the file in subsequent I O service requests until the file is closed perm specifies the attributes to use for the new file Only the lower 16 bits of perm are used If either the FAM SIZE bit or the S_ISIZ
451. os dup Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also os create os detach AE dupi os exit os open ISClose OS 9 for 68K Technical Manual I CLOSE OS 9 Technical Manual WX MICROWARE os cirsigs Clear Process Signal Queue Synta fincl fincl X lude process h lude lt types h gt error code os clrsigs process id proc id Description _os_clrsigs removes any queued signals that have been sent to the target process proc id specifies the target process ID number Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l See Also _os_sigmask os cmdperm Change Permissions of Module Directory Syntax include moddir h finclude lt types h gt error code os cmdperm char name u int32 perm Description os cmdperm changes the access permissions of an existing module directory This makes it possible to restrict access to a particular module directory name is a pointer to the name of the existing module directory perm specifies the new permissions Only the lower 16 bits of perm are used Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os cmpnamY Compare Two Names Syntax include lt stri
452. os ss wfm os s5 wrerack Write logical unit options Notify driver that path has been opened Write option section of path descriptor Release device Rename file Restore head to track zero Retension pass on tape drive Skip tape marks Send signal on data ready Set file size Skip blocks Skip to end of tape Wait specified number of ticks for record release Write tape marks Write format track Sg codes h modes h Sg codes h Sg codes h Sg codes h Sg codes h sbf h sbf h Sg codes h Sg codes h sbf h sbf h rbf h sbf h rbf h AN MICROWARE Table 1 7 GetStat SetStat Functions continued ANSI Function ad Description Header File setstat Set file status sg_codes h ee a ore Set file attributes sg_codes h _ss_dcoff Send data carrier lost scf h signal to process _ss_dcon Send data carrier scf h present signal to process _ss_dsrts Disable RTS line scf h Ss enrts Enable RTS line scf h _ss_lock Lock out record rbf h ss_opt Set path options sg_codes h _ss_pfd Put file descriptor sector rbf h ss rel Release device sg codes h ss rest Restore device sg codes h ss size Set current file size sg codes h ss ssig Send signal on data sg codes h ready ss tiks t Wait for record release rbf h SS wtrk Write track rbf h Input Output Device Functions The following functions are available for performing input output on device
453. os wait os exit os chain FSFork F_FORK OS 9 and OS 9 for 68K User and System Safe Yes OS 9 Technical Manual OS 9 Technical Manual AA MICROWARE os9fork os9forkc Create Process Syntax include lt process h gt include lt types h gt int os9fork ch in ch sh sh in sh ar t ar ort ort t ort int os9forkc ch in ch sh sh in sh sh ar t ar ort ort t ort ort Description modname parmsize parmptr type lang datasize prior modname parmsize parmptr type lang datasize prior pathcnt os9forkc creates a process that runs concurrently with the calling process When the new process terminates its exit status is available to the forking parent process The new process inherits the standard paths 0 1 and 2 plus any additional paths indicated by pathcnt modname is a pointer to a null terminated module name parmsize specifies the size of the parameter list Generally you must Set parmsize equal to strlen parmptr 41 parmptr is a pointer to a null terminated string to pass to the new process type specifies the type of module If type is zero any module may be forked regardless of type lang specifies the module language If 1ang is zero any module may be forked regardless of language datasize gives extra memory to the new program If no extra memory is required set datasize to zero prior is the new pri
454. ot be found 0 is returned If the terminal name is found 1 is returned and the data is placed in the buffer By defining the shell environment variables TERMCAP and TERM you can modify the behavior of tgetent If TERMCAP is found in the environment and its value string begins with a slash that string is used as the path to the file to use instead of the default termcap file If the value string does not begin with a slash and name is the same as the environment string for TERM tgetent uses this file to search for the terminal entry This mode is useful for testing or for custom termcap definitions If the TERMCAP value string does not begin with a slash the string is used as the termcap string instead of reading a file WX MICROWARE HM Note tgetent must be called before any of the other termcap library functions Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library termlib l See Also tgetflag tgetnum tgetstri tgetflag Check Terminal Capability Presence Syntax include lt termcap h gt extern char BC extern char UP int tgetflag char id Description tgetflag returns 1 if the capability ID was specified for the terminal type and 0 if not specified for the terminal type Note tgetent must be called before any of the other termcap library functions idis a pointer to the capability ID Att
455. otify returns a value of 0 Otherwise the function returns 1 and sets errno to indicate the error Errors EBADF The mqdes argument is not a valid message queue descriptor EBUSY ENOSYS Attributes Operating System State Threads Re entrant Standards Library masl See Also mq_open mq_send ma sSertattr AA MICROWARE A process is already registered for notification by the message queue mq notify not supported OS 9 User Safe No POSIX MQ O0 NOTIFY MME ATE mq notify write Notify Process That a Space in the Message Queue is Available Syntax finclude mqueue h int mq notify write mqd t mqdes const struct sigevent notification Description If the arguement notification is not NULL this function registers the calling process to be notified of message removal at a full message queue associated with the specified message queue descriptor mqdes The notification specified by the notification arguement is sent to the process when the message queue transitions from full to nonfull At any time only one process may be registered for notification by a message queue If the calling process or any other process has already registered for notification of the specified message queue subsequent attempts to register for that message queue will fail If notification is NULL and the process is currently registered for notification by the specified message queue
456. ough the nested intercept routines with multiple os rte calls the states must be left where they are and os sigreset should not be called Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 See Also dm quie WX MICROWARE Ultra C Library Reference OS sigrs Resize Current Process Signal Queue Block Syntax include signal h finclude lt types h gt error code os sigrs u int32 signals Description _os_sigrs allows a process to change the maximum number of signals that are queued on its behalf signals is the new maximum number of signals os sigrs can be used to increase or decrease the number of signals queued An error is returned EOS PARAM if a request is made to reduce the number of queued signals while there are signals pending The initial default for the system is specified in the system Init module Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os sleep Put Calling Process to Sleep Syntax include signal h finclude lt types h gt error code os sleep u int32 ticks signal code signal Description os sleep deactivates the calling process until the requested number of ticks have elapsed The length of time to sleep in ticks second is passed at the location pointed to by ticks e
457. outine library module 71 788 user subroutine module 786 user trap handling module 71 842 link to memory module 68 70 467 469 471 697 699 702 load memory module 69 70 469 471 702 module into colored memory 68 464 module s from file 70 700 make_module 68 441 modcload 68 464 modlink 68 467 modload 69 469 modloadp 69 471 munlink 69 494 munload 69 495 re validate module CRC 71 927 set alternate working module directory 69 518 unlink from module 69 494 module 71 849 850 unload module 69 495 validate module 71 851 852 module h 22 543 move data 711 memory 455 mq 11 MST 84 multibyte character convert sequence 72 448 convert to from wide 72 1085 convert to from wide characters 72 1083 determine number of bytes in 72 446 450 list of functions 72 mblen 72 446 mbstowcs 72 448 ABCDEFGHIJKLMNOPQRSTUVWXYZ mbtowc 450 wcstombs 72 1083 wctomb 72 1085 multiply float by exponent of 2 418 munlink 69 106 494 munload 69 106 495 natural logarithm 430 non local goto 432 933 notify driver that path has been opened 812 numeric formatting convention inquire 425 offsetof 497 open directory 501 file 256 498 path 713 re open file 276 open 48 106 498 opendir 48 106 501 os lib 11 102 os ss fillbuff 806 Os ss rfm 818 os9def h 23 os9exec 78 106 617 620 os9fork 78 106 630 633 os9forkc 630 633 os9kexec 78 106 691 696 o
458. ower Convert Character to Lowercase Syntax include lt ctype h gt int tolower int c Description tolower converts an uppercase letter to the corresponding lowercase letter c is the character to convert If the parameter c is such that islower c returns a non zero value is uppercase tolower returns the corresponding character Otherwise c is returned unchanged Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 See Also islower WX MICROWARE toupper Convert Character to Uppercase Syntax include lt ctype h gt int _toupper int c Description _toupper is a macro that changes the lowercase parameter to uppercase The parameter must be lowercase or the results are unpredictable and useless Use toupper if the parameter is not guaranteed to be lowercase c is the character to convert Only the lower 8 bits of c are used _toupper is hard coded to the ASCII character set Changing the locale does not cause toupper to recognize a non ASCII character You must use t oupper if you are not using ASCII characters Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library ctype h See Also tolower toupper 3858450130 ieasciii toupper Convert Character to Uppercase Syntax include l
459. pace from the value for a non negative formatted monetary quantity char n cs precedes Set to one or zero if the currency synbo1 respectively precedes or succeeds the value for a negative formatted monetary quantity char n sep by space Set to one or zero if the currency_symbol respectively is or is not separated by a space from the value for a negative formatted monetary quantity char p sign posn Set to a value indicating the positioning of the positive signfora non negative formatted monetary quantity The value may be 0 Parentheses surround the quantity and currency symbol 1 The sign string precedes the quantity and currency symbol 2 The sign string succeeds the quantity and currency symbol 3 The sign string immediately precedes the currency symbol 4 The sign string immediately succeeds the currency symbol WX MICROWARE char n sign posn Set to a value indicating the positioning of the negative sign for a negative formatted monetary quantity The values are the same as for p sign posn localeconv returns a pointer to the filled in object You cannot modify the structure pointed to by the return value but a subsequent call to Localeconv can overwrite the structure In addition calls to setlocale with categories LC ALL LC MONETARY or LC NUMERIC may overwrite the contents of the structure Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No
460. path The mnemonics for the status codes are located in the sg_codes h header file This manual describes the status codes currently defined by Microware and the functions that they perform These calls have an os ss prefix Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os setsvc Service Request Table Initialization Syntax include svctbl h finclude lt types h gt error code os setsvc u int32 count u int32 state flag void init tbl void params Description _os_setsvc adds or replaces a system service in OS 9 s user and privileged system service request tables count is a count of the entries in the initialization table state flag specifies whether user or system state tables or both are updated If state flagis USER STATE 1 only the user table is updated If state flagis SYSTEM STATE 2 only the system table is updated If state flagis USER STATE OR ed with SYSTEM STATE 3 both tables are updated init_tbl is a pointer to the initialization table An example initialization table might look like this error code printmsg service svctbl syscalls F_PRINT printmsg O ly lb F SERVICE service O 1 1 params may be a pointer to anything but is intended to be a pointer to global static storage When a system call is used the params data pointer is used as the
461. path number The file ber dd may be read for informational purposes only as there are no user changeable parameters path specifies the path number count is the number of bytes to copy Only the lower 16 bits of count are used fdbuf is a pointer to the buffer area for the file descriptor Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os gs cpypd Copy Contents of Path Descriptor Syntax include sg codes h finclude lt types h gt error code os gs cpypd path id path u int32 size void path desc Description os gs cpypd copies the contents of the specified path s path descriptor to your buffer path is the path number The number of bytes to copy from the path descriptor is passed at the location pointed to by size os gs cpypd also stores the actual number of bytes copied at the location pointed to by size path desc is a pointer to the buffer for the path descriptor data If the size value is greater than the size of the target path descriptor the actual size of the path descriptor is returned Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l1 os gs cstats Get Cache Status Information Syntax include rbf h finclude lt types h gt error code os gs cstats path id path cachestats cache inf
462. perating System OS 9 State System Threads Safe Re entrant Yes Library lock 1 See Also 058 acglk 08 Ccaqiki coe Orie os cdlk _os_del1lk _os_waitlk F_RELLK OS 9 Technical Manual WX MIC ROWARE _os9_retpd Return Fixed Block of Memory Syntax finclude lt process h gt finclude lt types h gt error_code _os9_retpd u_int32 number void table Description os9 retpd deallocates a fixed block of memory number is the number of the table element Only the lower 16 bits of number are used table is a pointer to the address of the table to use Attributes Operating System OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l See Also o89 allpat me finapsti os rte Return from Signal Interrupt Routine Syntax include signal h finclude lt types h gt error code os rte void Description _os_rte terminates a process signal intercept routine and continues executing the main program Attributes Operating System State Threads Re entrant Library os lib l See Also os intercept FSRTE F RTE OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE os rtnprc Deallocate Process Descriptor Synta fincl fincl X Lude lt process h Lude lt types h error code os rtnprc process id proc id Description
463. popti os ss relea os ss reset e ss FEM os ss sendsig OoS ss size D08 58 skip 08 88 ticks OS ss wimi os ss wtrack OoSs9 ss open ISSetott OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual WX MICROWARE setsys Set Examine System Global Variables Syntax include lt sysglob h gt finclude lt setsys h gt int _setsys int glob int size int value Description _setsys changes or examines a system global variable These variables are defined in sys 1 The same values are defined in the setsys h header file for C program use These variables begin with a D prefix glob is the offset to the intended variable Only the lower 16 bits of glob are used sizeisthe size of the variable size 0x80000000 is used to examine the variable value is an optional parameter used only when changing a variable Setsys returns the value of the variable on an examination request On a change request _setsys returns the value of the variable before the change If the examine or change request fails 1 is returned and the appropriate error code is placed in the global variable errno Note Use getsys to examine variables without the possibility of accidental change Attributes Operating System State Threads Re entrant Library Sys clib l See Also _getsys _os_getsys _os_setsys FSSetSys OS 9 and
464. ption as set when the message queue was opened and as modified by subsequent mq setattr calls mq 1ags The following attributes of the message queue shall be returned as set at message queue creation mq maxmsg mq msgsize Upon return the following members within the mg attr structure referenced by the mqstat argument shall be set according to the current state of the message queue mq curmsgs the number of messages currently on the queue OS 9 specifies the following user defined flag for use with mq getattr andmq setattr MQ O NOTIFY IMMEDIATE When this flag is specified by the mq setattr function mq 1ags field of mqstat parameter then calls to either mq notify write Oormq notify Will notify immediately if appropriate Message queue nonfull for mq notify write and message queue non empty for mq notify This extension provides message queue notification consistency with other OS 9 services such the send signal on data ready concept Upon successful completion mq getattr returns 0 Otherwise the function returns 1 and sets errno to indicate the error Errors EBADF ENOSYS Attributes Operating System State Threads Re entrant Standards Library mq 1l See Also mq open mq send liy SOLGaLLE WX MIC ROWARE The mqdes argument is not a valid message queue descriptor mq getattr not supported OS 9 User Safe No POSIX mq notify Notify
465. pu l See Also Set name OS 9 User and System Safe Yes getc getchar Get Next Character from File Stdin Syntax include lt stdio h gt int getc FILE stream int getchar void Description getc returns a character as an unsigned converted to an int from the file and advances the associated file position indicator for the stream if defined If getc is implemented as a macro it may evaluate st ream more than once Therefore the parameter should never be an expression with side effects get char is a macro that is equivalent to getc stdin stream is a pointer to the C I O FILE structure getc returns the next character from the input stream pointed to by stream If the stream is at end of file the end of file indicator for the stream is set and getc returns EOF If a read error occurs the error indicator for the stream is set and getc returns EOF getchar returns the next character from the input stream pointed to by stdin If the stream is at end of file the end of file indicator for the stream is set and getchar returns EOF If a read error occurs the error indicator for the stream is set and getchar returns EOF Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 WX MICROWARE See Also fgetc fopen putei purohart 304 Ultra C Library Reference get
466. r 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also errmsg os9exec WX MICROWARE printf Formatted Output Syntax include lt stdio h gt int printf const char format Description printf is a standard C library function that performs formatted output to stdout It converts formats and prints any parameters as indicated by the control string format is a pointer to a control string printf returns the number of characters transmitted or a negative value if an output error occurred Note The sclib 1and sclib il libraries contain a smaller version of the printf function Refer to the Using Ultra C C manual for more information about the small library functions Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library elaby I See Also fprintri scanf sprinttfi Ultra C Library Reference 881 WX MICROWARE _prsnam Parse Path Name Segment Syntax include lt strings h gt int _prsnam char string Description _prsnam parses a path name segment string is a pointer to the path name segment _prsnam returns the number of characters in a valid path name segment If the path name segment is invalid 1 is returned Use _parsenam to determine if a path is a valid disk file RBF pathlist You can use successive calls to prsnam to pa
467. r 68K header file is unavailable change the source code to use I_SETSTAT SS_PATHOPT or I_SETSTAT SS_LUOPT Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also os gs popt DO0s ss popt ISSetott OS 9 for 68K Technical Manual I BETSTAT OS 9 Technical Manual tmode Using OS 9 for 68K or Using OS 9 ss pfd Put File Descriptor Sector Syntax include rbf h include lt direct h gt int _ss_pfd int path struct fd buffer Description _ss_pfd copies certain fields from the file descriptor information pointed to by buffer into the file descriptor sector of the file open on path The buffer is usually obtained from _gs_gfd Only the owner ID the modification date and creation date fields are changed path is the path number of the file buffer is a pointer to the buffer containing the file descriptor information The structure fa declared in the direct h header file provides a convenient means to access the file descriptor information If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Note The buffer must be at least 32 bytes long or unanticipated data could be written into the file descriptor sector Only the super user can change the owner ID field You cannot change the file attributes with this call Instead use ss at
468. r and System Threads Safe Re entrant Yes Library os lib l1 _os sgs devnm Return Device Name Syntax include sg codes h finclude lt types h gt error code os sgs devnm path id path char namebuf Description _os_sgs_devnm returns the name of the device associated with the specified system path number path is the system path number namebuf is a pointer to the location where os sgs devnm stores the device name Attributes Operating System OS 9K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os siglngj Set Signal Mast Value and Return on Specified Stack Image Syntax include lt signal h gt finclude lt types h gt error code _os_siglngj void usp u intl16 siglvl Description F SIGLNGJ allows processes to perform 1ong jump operations from their signal intercept routines and unmask signals in one operation usp s a pointer to the new process stack image siglvl is the new signal level value This call is usually used by nested intercept routines to resume execution in the process at a different location from where the process was interrupted by the original signal When this call is made the operating system performs the following functions e Validates and copies the target process stack image from the memory buffer pointed to by the usp variable to the process system state stack e Sets the process
469. r code _os_fork u int32 priority u int32 path cnt char mod name void params u int32 param size u int32 mem size process id proc id u int32 type lang u int32 orphan Description os fork creates a new process which becomes a child of the caller It sets up the new process memory MPU registers and standard I O paths priority specifies the priority of the new process Only the lower 16 bits of priority are used If priority is zero the new process inherits the same priority as the calling process path cnt specifies the number of I O paths for the child to inherit Only the lower 16 bits of path_cnt are used mod_name is the module name pointer params is a pointer to the parameter block param_size specifies the size of the parameter block mem_size specifies any additional stack space to allocate proc_id is a pointer to the location where os fork stores the child process ID type lang specifies the desired type and language Only the lower 16 bits of type lang are used If type_lang is zero any module may be loaded regardless of type and language If the orphan flag is non zero the new process executes without a parent If the orphan flag is zero the new process is the child of the calling process On OS 9 for 68K if the orphan flag is set to a non zero value the EOS PARAM error is returned Attributes Operating System State Threads Re entrant Library os lib l See Also
470. r ensure that the macro expansion does not occur by placing the function name within parentheses For example b isjis kana c Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Ultra C Library Reference 393 WX MICROWARE Library ctype h See Also isalnum isalpha TBEBEEL islower isprint ispunct isspace isupper isxdigit 0 394 Ultra C Library Reference islower See If Parameter Is Lowercase Syntax include lt ctype h gt int islower int c Description islower is aC macro that tests for lowercase letters is lower returns a non zero value for ASCII characters from 0x61 a to 0x7a CZ is c is the character to test Note This routine available as a function or a macro in ctype h does not operate well with values outside the range of an unsigned char The function checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b islower c Attributes Operating System OS
471. r time The value time t 1 is returned if the calendar time is unavailable If t imer is not a null pointer the return value is also assigned to the object to which it points Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 See Also getenv _os_getime os9 getime WX MICROWARE times Get Process Times Syntax include UNIX times h int times struct tms buffer Description times returns time accounting information for the current process and for the terminated child processes of the current process All times are in 1 60 seconds buffer points to the following structure struct tms clock t tms utime user time clock t tms stime system time clock t tms cutime user time children clock t tms cstime system time children This information comes from the calling process tms_utime is the CPU time used while executing instructions in the user space of the calling process tms_stime is the CPU time used by the system on behalf of the calling process tms_cutime and tms_cutimes are not implemented and set to zero by times Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix 1 tmpfile Create Temporary Binary File Syntax include lt stdio h gt FILE tmpfile void
472. r to the library s static data area for subsequent calls to the subroutine The calling program must store and maintain the subroutine s entry point and data pointer The calling program must also set the subroutine library s data pointer and dispatch to the correct subroutine sub numis the subroutine number Only the lower 16 bits of sub num are used mod headis a pointer to the module header lib exec is a pointer to the location where os slinkm stores the pointer to the subroutine library entry point mem ptr is a pointer to the location where os slinkm stores the pointer to the subroutine library static memory Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l1 See Also os slink os tlink Ultra C Library Reference 789 WX MICROWARE os srqmem System Memory Request Syntax include lt memory h gt finclude lt types h gt error code _os_srgmem u int32 size void mem ptr u int32 color Description os srqmem allocates a block of a specific memory type The byte count of the requested memory is passed at the location pointed to by size os srqmem also stores the actual number of bytes allocated at the location pointed to by size If size is OxFFFFFFFF the largest block of free memory of the specified type is allocated to the calling process mem ptr is a pointer to the location where os srqmem stores the po
473. r to the buffer in which to copy the process descriptor count specifies the number of bytes to copy Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os cpymem Copy External Memory Syntax finclude lt process h gt finclude lt types h gt error code os cpymem process id proc id void from void CO u_int32 count Description _os_cpymem copies external memory into your buffer for inspection proc_id specifies the process ID of the owner of the external memory from is a pointer to the external process memory to copy to is a pointer to the caller s destination buffer count is the number of bytes to copy _os_cpymem can copy portions of the system s address space This is especially helpful in examining modules Any memory in the system may be viewed in this way Attributes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant Yes Library os lib l1 See Also os move os crc Generate CRC Syntax include module h finclude lt types h gt error code os crc void start u int32 count int32 accum Description os crc generates or checks the CRC cyclic redundancy check values of sections of memory Compilers assemblers and other module generators use os crc to generate a valid module CRC start is a pointer to the section of mem
474. ra C Library Reference Table 2 25 set name Valid Name Values continued Register Processor s name Type 403 505 601 603 User Readable bro DCR e br1 DCR bra DCR brs DCR e br4 DCR br5 DCR br6 DCR e e br DCR cmpa SPR cmpb SPR cmpc SPR cmpd SPR cmpe SPR cmpf SPR cmpg SPR e cmph SPR e counta SPR WX MICROWARE Table 2 25 set name Valid Name Values continued Register Processor s lt name gt Type 403 505 601 603 User Readable countb SPR er PREG i Ctr SPR dabr SPR dacl SPR dac2 SPR dar SPR e dbat01 SPR dbatOu SPR e dbat11 SPR dbatlu SPR dbat21 SPR e dbat2u SPR e dbat31 SPR dbat3u SPR e dbcr SPR dbsr SPR Table 2 25 set name Valid Name Values continued Register Processor s name Type 403 505 601 603 User Readable deer SPR dcmp SPR dec SPR der SPR e dmacc0 DCR dmacr0 DCR dmacrl DCR e e dmacr2 DCR dmacr3 DCR e dmact 0 DCR e dmact1 DCR dmact2 DCR e e dmact3 DCR e dmada0 DCR dmadal DCR e e dmada2 DCR e e dmada3 DCR e WX MICROWARE Table 2 25 set name Valid Name Values continued Register Processor s name Type 403 505 601 603 User Readable dmasa0 DCR dmasal DCR dmasa2 DCR dmasa3 DCR dmasr DCR dmiss SPR dpdr SPR e dsi
475. rand of the unary operator with the resulting expression being the entire controlling expression of a selection or iteration statement For example while set jmp env Attributes Operating System State Threads Re entrant Standards Library clib l See Also longjmp WX MICROWARE OS 9 and OS 9 for 68K User and System Safe Yes ANSI setlocale Locale Control Syntax include locale h char setlocale int category const char locale Description setlocale selects the appropriate portion of the program s locale as specified by category and locale You can use setlocale to change or query the program s entire current locale or portions of it category can be one of the following values Table 2 26 setlocale Category Values Name Description C ALL Names the program s entire locale The other values for category name only a portion of the program s locale C COLLATE Affects the behavior of strzcoll and strxfrm LC CTYPE Affects the behavior of the character handling functions and the multibyte functions C MONETARY Affects the monetary formatting information returned by localeconv C NUMERIC Affects the decimal point character for the formatted I O functions and the string conversion functions as well as the non monetary formatting information returned by localeconv LC TIME Affects the behavior of st rftime
476. rary os lib l mt os lib l1 See Also os exit os thexit os wait os waitlk Activate Next Process Waiting to Acquire Lock Syntax finclude lt lock h gt finclude lt types h gt error code os waitlk lk desc LOCK signal code signal Description os waitlk activates the next process waiting to acquire the lock The next process in the lock s queue is activated and granted exclusive ownership of the resource lock If no other process is waiting on the lock the lock is simply marked free for acquisition The calling process in either case is suspended and inserted into a waiting queue for the resource based on relative scheduling priority lock is a pointer to the lock on which to wait signal is a pointer to the location where os waitlk stores the received signal If a process receives a signal while waiting on a lock the process is activated without gaining ownership of the lock The process returns from the wait lock call with an EOS SIGNAL error code and the signal code is returned through the signal pointer Note If an S WAKEUP signal is received by a waiting process the signal code does not register and is zero Attributes Operating System State Threads Re entrant Library lock 1 See Also os acqlk oe caglkt 5s orlik os ddlik os dellk 08 rellk F WAITLK WX MICROWARE OS 9 System Safe Yes OS 9 Technical
477. rate the international currency symbol from the monetary quantity char currency_symbol The local currency symbol applicable to the current locale char mon_decimal_point The decimal point used to format monetary quantities char mon_thousands_sep The separator for groups of digits before the decimal point in formatted monetary quantities char mon_grouping A string whose elements indicate the size of each group of digits in formatted monetary quantities The string may contain the following CHAR_MAX 0 other No further grouping is to be performed The previous element is to be repeatedly used for the remaining digits The integer value is the number of digits that comprise the current group The next element is examined to determine the size of the next group of digits before the current group char positive_sign The string used to indicate a non negative valued formatted monetary quantity char negative sign The string used to indicate a negative valued formatted monetary quantity char int frac digits The number of fractional digits those after the decimal point to display in an internationally formatted monetary quantity char p cs precedes Set to one or zero if the currency synbo1 respectively precedes or succeeds the value for a non negative formatted monetary quantity char p sep by space Set to one or zero if the currency synbo1 respectively is or is not separated by a s
478. rds ANSI Library cla See Also atexit os exik os wait tmpfile FSExit F EXIT WX MIC ROWARE OS 9 for 68K Technical Manual OS 9 Technical Manual exp Exponential Function Syntax finclude lt math h gt double exp double x Description exp returns the exponential function of x e 2 71828 raised to the x power A range error ERANGE stored in errno occurs if the magnitude of x is too large In this case exp returns HUGE VAL Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 Possible Error ERANGE WX MIC ROWARE fabs Floating Absolute Value Syntax include lt math h gt double fabs double x Description fabs returns the absolute value of x Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 fclose Close File Syntax include lt stdio h gt int fclose FILE stream Description fclose flushes the file pointed to by st ream and closes the associated file Any unwritten buffered data for the stream are written to the file any unread buffered data are discarded The stream is disassociated from the file If the associated buffer was automatically allocated it is deallocated If st ream was returned from tmpfile it is deleted stre
479. re All ordinary multibyte characters including the terminating null character are copied unchanged into the array If copying takes place between overlapping objects the behavior is undefined No more than maxsize characters are placed in the array AA MICROWARE Each conversion specifier is replaced by appropriate characters as described in the following list These characters are determined by the LC TIME category of the current locale and by the values contained in the structure pointed to by timeptr Table 2 35 strftime Conversion Values Value Replaced By The locale s abbreviated weekday name oo w SA The locale s full weekday name Sb The locale s abbreviated month name B The locale s full month name c The locale s appropriate date and time representation sd The day of the month as a decimal number 01 31 SH The hour 24 hour clock as a decimal number 00 23 SI The hour 12 hour clock as a decimal number 01 12 amp j The day of the year as a decimal number 001 366 m The month as a decimal number 01 12 3M The minute as a decimal number 00 59 sp The locale s equivalent of the AM PM designations associated with a 12 hour clock SS The second as a decimal number 00 61 SU The week number of the year the first Sunday as the first day of week 1 as adecimal number 00 53 The weekday as a decimal number 0 6 where Sunday is 0 oo z Table 2
480. re used Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l Example The following example code fragment looks for a period in the string and sets pt r to point to it The search starts from the end of the string and progresses to the front of the string Note that ch is a character not a pointer to a character func char ptr string if ptr rindex string WX MICROWARE process ptr else printf No found n See Also index sbrk Extend Data Memory Segment Syntax include lt stdlib h gt char sbrk unsigned size Description sbrk allocates memory from the top of the data area upwards Table 2 24 sbrk Memory Allocation Table t sbrk Area Grows toward Higher Address Stack Area ibrk Area Program Data Area Lowest Address size Specifies the size of the memory block sbrk grants memory requests by calling the F MEM for OS 9 for 68K or the F MEM for OS 9 system call This method resizes the data area to a larger size The new memory granted is contiguous with the end of the previous data memory WX MICROWARE On systems without an MMU sbrk fails quickly because it may keep growing in size until the data area reaches other allocated memory At this point it is impossible to increase in size and an error is returned A program may increase its data size by o
481. rea dopts is a pointer to the default options for the device Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE 0S ss dsrts Disable RTS Line Syntax include lt scf h gt finclude lt types h gt error_code _os_ss_dsrts path_id path Description _os_ss_dsrts disables the RTS line on serial devices path specifies the path number Attributes Operating System State Threads Re entrant Library os lib l See Also ISSetStt I SETSTAT SS DSRTS OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual 0S ss enrts Enable RTS Line Syntax include lt scf h gt finclude lt types h gt error code os ss enrts path id path Description JOoS ss enrts enables the RTS line on serial devices path specifies the path number Attributes Operating System State Threads Re entrant Library os lib l See Also ISSetStt I SETSTAT SS ENRTS OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE OS SS erase Erase Tape Syntax include lt sbf h gt finclude lt types h gt error code _os_ss_erase path_id path u_int32 blocks Description _os_ss_erase erases a portion of the tape path specifies the tape drive s path number blocks spec
482. res the current system date day is a pointer to the location where _os9_getime stores the day of the week where 0 is Sunday and 6 is Saturday ticks is a pointer to the location where _os9_getime stores the clock tick data If ticks are requested the clock tick rate in ticks per second is returned in the most significant word at the location pointed to by ticks The least significant word contains the current tick The following figures illustrate values returned at the pointers Figure 2 7 Gregorian Formats Byte MSB LSB TIME hour minute second 00000000 0 23 0 59 0 59 Byte MSB LSB year month day DARE four decimal digits 1 12 1 31 Figure 2 8 Julian Formats Bits 0 31 TIME seconds since midnight 0 86399 Bits 0 31 DATE Julian day number WX MICROWARE Note _os9_getime returns a date and time of zero with no error if no previous Call to _os9_setime is made after the system start up A tick rate of zero indicates the clock is not running Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also os9 setime _os_ Tulran oS getime FSTime OS 9 for 68K Technical Manual ihraru Rafaranra ary neterence Ilta CI Ultra v LID os get ioproc Get Pointer to I O Process Descriptor Syntax include lt io h gt finclude lt types h
483. returns the converted value if any If no conversion could be performed zero is returned If the correct value is outside the range of representable values LONG MAX or LONG MIN is returned according to the sign of the value and ERANGE is stored in errno Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 See Also isupper strtodi srrtouli Possible Error ERANGE Ultra C Library Reference 1023 WX MICROWARE strtoul String to Long Conversion Syntax include lt stdlib h gt include lt limits h gt unsigned long strtoul char begin char end int base Description strtoul converts the initial portion of begin to unsigned long int representation begin is a pointer to the beginning of the string end is a pointer to the pointer to the first character after the converted string base is the base of the number string strtoul separates the input string into three parts 1 An initial possibly empty sequence of white space characters as specified by isspace 2 A subject sequence resembling an unsigned integer represented in some radix determined by base The subject sequence is the longest initial subsequence of the input string starting with the first non white space character of the expected form The subject sequence contains no characters if the input string is empty or consi
484. ributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix l See Also os9 alarm atdate os alarm set alloca Allocates Bytes of Space in Stack Frame Syntax include UNIX os9def h void alloca unsigned int size Description alloca allocates size number of zero bytes from the malloc pool This space is not automatically freed alloca returns a pointer to the allocated bytes If an error occurs NULL is returned and the global variable errno is set Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix l WX MICROWARE alm atdate Set Alarm at Gregorian Date Time Syntax include lt alarm h gt int alm_atdate int sigcode int time int date Description alm_atdate requests that a signal be sent to the requesting process at a specific Gregorian time and date The time and date must be in the following format Figure 2 1 alm_atdate Time and Date Format Byte 0 Byte 1 Byte 2 Byte 3 Time 0 Hour 0 23 Minute Second Date Year two bytes Month Day sigcode specifies the signal to be sent to the caller time specifies the time to send the signal date specifies the Gregorian date for the signal to be sent Because the system time and date may be changed the alarm signal is sent when the system time and
485. ributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes See Also Os unlznkf FSUnLoad OS 9 for 68K Technical Manual F_UNLOAD OS 9 Technical Manual os vmodul Verify Module Syntax include module h finclude lt types h gt error code os vmodul mh com mod head mh com mod block u int32 block size Description os vmodul checks the module header parity and CRC bytes of an OS 9 module If the header values are valid the module is entered into the module directory The current module directory is searched for another module with the same name If a module with the same name and type exists the module with the highest revision level is retained in the module directory Ties are broken in favor of the established module mod headis a pointer to the address of the module mod blockisa pointer to the memory block containing the module block size specifies the size of the memory block containing the module Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library os lib l See Also Gee pe os load WX MICROWARE os9 vmodul Validate Module Syntax include lt module h gt finclude lt types h gt error code os9 vmodul u int32 mod group u int32 size mh com mod head mod dir gir entry Description os9 vmodul checks the module header parity and CRC bytes of an OS
486. ributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library termlib 1 WX MICROWARE tgetnum Get Terminal Capability ID Syntax include lt termcap h gt extern char BC extern char UP int tgetnum char id Description tgetnum returns the numeric value given for the capability ID Note tgetent must be called before any of the other termcap library functions idis a pointer to the capability ID If id was not specified for the terminal type 1 is returned Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library termlib 1 tgetstr Get Terminal Capability Syntax include lt termcap h gt extern char BC extern char UP char tgetstr char id char strptr Description tgetstr places the string given for the capability ID into a buffer Note tgetent must be called before any of the other termcap library functions idis a pointer to the capability ID strptr is a pointer to the pointer to the buffer for the capability string strptr is advanced past the last character of the returned data tgetstr returns null or 0 upon error Cursor motion and padding information are interpreted when the string is actually output with tgoto and tputs Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entran
487. ributes Operating System State Threads Re entrant Library Sys clib 1l1 See Also bs 65 lock i I Setstt I SETSTAT SS LOCK WX MIC ROWARE OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual ss opt Set Path Options Syntax include sg codes h finclude sgstat h int ss opt int path struct sgbuf buffer Description Ss opt copies a buffer into the options section of the path descriptor open on path path specifies the path number of the path descriptor buffer is a pointer to a buffer containing the path descriptor information Generally a program gets the options with gs opt changes the appropriate values and updates the path options with ss opt The structure sgbuf declared in the sgstat h header file provides a convenient means to access the individual option values If the path was invalid 1 is returned and the appropriate error code is placed in the global variable errno Note It is common practice to preserve a copy of the original options so the program can restore them before exiting The option changes take effect on the currently open path and any paths created with 1 Dup or I DUP to the same WX MICROWARE Note If you use ss popt on OS 9 you must use the OS 9 for 68K header file ss luopt is provided on OS 9 solely for compatibility with OS 9 If the OS 9 fo
488. riptor Attributes Operating System State Threads Re entrant Library os lib l See Also os alltski os chkmem os protect oS permit FSDelTsk F_DELTSK OS 9 and OS 9 for 68K System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE os detach Remove Device from System Syntax incl incl lude lt io h gt lude lt types h gt error code os detach dev list dev_tbl Description os detach removes a device from the system device table if no other process is using the device dev tbl is a pointer to the address of the device table entry Note On OS 9 for 68K if an invalid address is passed in dev tb1 the system may crash or undergo severe damage Attributes Operating System State Threads Re entrant Library os lib l See Also oS attach os closet I Detach I_DETACH OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual os dexec Execute Debugged Program Syntax include dexec h finclude lt types h gt error code os dexec process id proc id dexec mode mode void params u int32 num instr u int32 num bpts void brk pts u int32 tot Instr dexec status status u int32 except void addar error code exit status Description OS 9 for 68K os dexec controls the execution
489. rmat difftime Find temporal difference time h getime Get system time time h gmt ime Convert calendar time to time h Greenwich Mean Time _gregorian Convert date time to Gregorian time h value julian Convert date time to Julian time h value localtime Convert calendar time to local time h time mktime Convert broken down time to time h calendar time Get system date and time time h _os_getime WX MICROWARE Table 1 26 Time Functions continued ANSI Header Function Standard Description File _os9_getime Get system date time time h _os_gregorian Get Gregorian date time h os julian Get Julian date time h os setime Set system date time time h _os9_setime Set system date time time h setime Set system time time h strftime Place formatted time in buffer time h sys mktime Convert local time to time h Greenwich Mean Time _sysdate Get current system date time time h time Get calendar time time h Processor Specific Functions Functions available only on the 80x86 family of systems are identified in Table 1 27 ANSI prototypes for non ANSI functions are achieved by defining the macro name OPT PROTOS during the compile Table 1 27 80x86 Only Functions ANSI Header Function Standard Description File get current tss Get current task segment regs h get excpt base Return exception table base regs h address get gdtr Get global descriptor pointer regs h ma
490. rocess proc desc is a pointer to the process descriptor Note os alltsk only performs a useful function on MMU SSM systems On non MMU SSM systems os alltsk simply returns without initializing the protection hardware Attributes Operating System OS 9 and OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l1 See Also FSAllTsk OS 9 for 68K Technical Manual F ALLTSK OS 9 Technical Manual os alocproc Allocate Process Descriptor Syntax finclude lt process h gt finclude lt types h gt error code os alocprocQ process id proc id pr desc proc desc Description _os_alocproc allocates and initializes a process descriptor The descriptor s address is stored in the process descriptor table proc idis a pointer to the location where os alocproc stores the process ID proc desciis a pointer to the location where os alocproc stores the pointer to the process descriptor Attributes Operating System OS 9 and OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l See Also FSAllPrc OS 9 for 68K Technical Manual WX MICROWARE os altmdir Set Alternate Working Module Directory Syntax include lt moddir h gt finclude lt types h gt error code _os_altmdir char name Description os altmdir establishes an alternate working module directory for a process name specifies the name of the module dir
491. rocess ID of the current process Maximum number of bytes consumed from the stack so far This variable does not contain a useful value unless stack checking is enabled Print this variable prior to exiting to examine how much stack space your application required void glob data char environ char environ Class 2 Globals void sttop void mtop void stbot void csl a6 void csl glob u int32 sbsize FILE fcbs void ofcbs int32 stklimit Pointer to the current processes global static storage _glob_data canbe used as an argument to os intercept Pointer to the environment variable strings for the current process This variable is used when forking other processes to pass the current environment along Same as environ except that it is available only in K amp R source mode for OS 9 for 68K environ is provided for compatibility with Microware K amp R C compiler Address of the top of the stack Address of data memory mtop is used to check for stack overflow Deepest stack pointer so far Global static storage pointer for attached cs1 OS 9 for 68K only Global static storage pointer for attached cs1 OS 9 only Size of process memory area sbsize is used by sbrk Pointer to _niob array Pointer to compatibility _i ob array Amount of verified area left on stack This value contains the number of bytes that can be consumed from the stack befor
492. ropriate error code is placed in the global variable errno Clear the global variable errno prior to calling ev read to distinguish between return of an event value of 1 and an error For More Information Refer to your operating system technical manual for more information about events Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l WX MICROWARE Example errno 0 if ev val ev read ev id 1 amp amp errno exit errmsg errno Can t read event value See Also OS ev read FSEvent OS 9 for 68K Technical Manual F_EVENT OS 9 Technical Manual EV READ OS 9 Technical Manual ev set Set Event Variable and Signal Event Occurrence Syntax include lt events h gt int _ev_set int ev_id int ev value int allflag Description _ev_set indicates that an event has occurred The event variable is set to the value given by ev value and the normal signal increment is not applied Processes waiting for the event are then activated ev idis the event ID returned from a call to ev creat ev link os ev creat Of os ev link ev value sets the value of the event variable allflag specifies the process es to activate Only the lower 16 bits of allflag are used e fallflag is zero the first process waiting for the event is activated e fallflagis 0x8000 a
493. rrnum Description _os_perr is the system s error reporting facility It writes an error message to the standard error path Most OS 9 for 68K systems print ERROR mmm nnn Error numbers 000 000 to 063 255 are reserved for the operating system path is the path to the error message file If path is zero standard format is specified errnumis the error number Only the lower 16 bits of errnum are used If an error path number is specified the path is searched for a text description of the error encountered The error message path contains an ASCII file of error messages Each line may be up to 80 characters long If the error number matches the first 7 characters in a line that is 000 215 the rest of the line is printed along with the error number Error messages may be continued on several lines by beginning each continuation line with a space An example error file might contain lines like this 000 214 ESFNA File not accessible An attempt to open a file failed The file was found but is inaccessible to you in the requested mode Check the file s owner ID and access attributes 000 215 ESBPNam Bad pathlist specified The specified pathlist is syntactically incorrect Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os protect Prevent Access to Memory Block Syntax finclude lt process h gt finclude
494. rse a complete path name Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also os presnami FSPrsNam OS 9 for 68K Technical Manual F PRSNAM OS 9 Technical Manual putc putchar Put Next Character to File Standard Out Syntax include lt stdio h gt int putc int cnr FILE stream int putchar int chr Description putc converts a character to an unsigned char It writes the character to the output stream at the position indicated by the associated file position indicator for the stream if defined and advances the indicator appropriately If the stream cannot support positioning requests or if the stream was opened with append mode the character is appended to the output stream If it is implemented as a macro it may evaluate the stream more than once Therefore the parameter should never be an expression with side effects putchar is similar to putc with the second parameter stdout chr is the character to write Only the lower 16 bits of chr are used stream is a pointer to the C I O FILE structure putc returns the character written If a write error occurs the error indicator for the stream is set and putc returns EOF Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library eliabs L WX MICROWARE See Also
495. rted to decimal notation in the style ddd ddd The number of digits after the decimal point character is equal to the precision specification The default precision is 6 If the precision is zero and the flag is not specified no decimal point character appears If a decimal point character appears at least one digit appears before it The value is rounded to the appropriate number of digits g G The double parameter is converted in the style f or e or in style E in the case of a G conversion specifier with the precision specifying the number of significant digits If the precision is zero it is taken as one The style used depends on the value converted style e or E is used only if the exponent resulting from the conversion is less than 4 or greater than or equal to the precision Trailing zeros are removed from the fractional portion of the result A decimal point character appears only if it is followed by a digit n The parameter is a pointer to an integer into which is written the number of characters written to the output stream so far by this call to fprintf No parameter is converted o u x The unsigned int parameter is converted to unsigned octal o X unsigned decimal u or unsigned hexadecimal notation x or X in the style aaaa The letters abcdef are used for x conversion and letters ABCDEF for x conversion The precision specifies the minimum number of digits to appear If the value being converted can
496. ry Cou Mes V liheany Dataranes Ultra lorary Reference get gdtr Get Global Descriptor Pointer Syntax include lt types h gt finclude lt regs h gt void get_gdtr void Description get_gdtr returns a pointer to the global descriptor Note get gdtr is only supported on the 80x86 family of processors version of the compiler Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library Cou WX MICROWARE getime Get System Time Syntax include lt time h gt int getime struct sgtbuf timebuf Description getime returns the system time in a time buffer The time units are defined in the time h header file timebuf is a pointer to the time buffer If successful get ime returns the buffer pointer Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library sys_clib 1 See Also _os_getime FSTime OS 9 for 68K Technical Manual F_TIME OS 9 Technical Manual get module dir Get Module Directory Entry Syntax include module h int get module dir void buffer int count Description _get_module_dir copies the system s module directory into the buffer for inspection A maximum of count bytes are copied _get_module_dir returns the number of bytes actually copied buffer is a pointer to the buffer count specifies the maximum number of
497. ry os lib 1l1 See Also FSAlarm OS 9 for 68K Technical Manual F ALARM F_DELET OS 9 Technical Manual os alarm reset Reset Existing Alarm Request Syntax include alarm h finclude lt types h gt error code os alarm reset alarm id alrm id signal code signal u int32 time Description os alarm reset sets an existing alarm to send after the specified time interval has elapsed alrm idis the alarm ID to reset signal is the signal code of the signal to send time may be specified in system clock ticks or if the high order bit is set the low 31 bits are considered a time in 256ths of a second Usually the minimum time interval allowed is 2 clock ticks Attributes Operating System OS 9 State User Threads Safe Re entrant Yes Library os lib l See Also oS alarm set FSAlarm OS 9 for 68K Technical Manual F_ALARM A_RESET OS 9 Technical Manual WX MICROWARE os alarm set Send Signal After Specified Time Interval Syntax include lt alarm h gt finclude lt types h gt error_code _os_alarm_set alarm_id alrm id signal code signal u int32 time Description os alarm set sends one signal after the specified time interval has elapsed alrm idis a pointer to the location where os alarm set stores the alarm ID signal is the signal code of the signal to send time may be specified in system clock ticks or if the high order bit is set t
498. ry variable buildpath 149 address translation function system addr 1038 user addr 1069 alarm 118 alarm h 14 alarms os alarm atime 506 os alarm cycle 509 os alarm delete 510 os alarm reset 511 os alarm set 512 os salarm atime 735 os salarm cycle 738 os salarm delete 742 743 os salarm reset 744 Os salarm set 745 os9 alarm atdate 504 os9 alarm atjul 507 os9 salarm atdate 733 _os9_salarm_atjul 736 _os9_salarm_cycle 740 _os9_salarm_set 746 alm atdate 120 ABCDEFGHIJKLMNOPQRSTUVWXYZ alm atjul 122 alm cycle 124 alm delete 126 alm set 127 delete 126 execute system state subroutine 740 remove cyclic alarm 510 pending request 126 510 742 743 reset alarm clock 744 existing request 511 send after specified interval 746 at Gregorian date time 733 at Julian date time 736 cyclic 740 signal after specified interval 127 512 signal after specified seconds 118 signal at Gregorian date time 120 504 signal at Julian date time 122 507 signal at specific time 124 506 509 735 system state subroutine 733 736 746 set alarm clock 738 745 alias os rdalst 725 copy system alias list 725 alloca 119 allocate _Icalloc 416 colored memory 966 fixed length memory block 515 low overhead 416 memory from arena 423 444 process descriptor 517 resource lock descriptor 549 storage for array 151 416 task 516 allocate bytes of space in stack frame 119 alm_atdate 52 102 1
499. s Table 1 8 Input Output Functions Function Or iad Description Header File ine Get character from I O address regs h inl Get integer from I O address regs h inw Get word from I O address regs h outc Write character to I O address regs h outl Write integer to I O address regs h outw Write word to I O address regs h Input Output Functions The following functions make up the I O functions of the Ultra C libraries ANSI prototypes for non ANSI functions are achieved by defining the macro name _OPT_PROTOS during the compile Table 1 9 Ultra C I O Functions ANSI Header Function Standard Description File access Determine file accessibility modes h attach Attach to device modes h WX MICROWARE Table 1 9 Ultra C I O Functions continued ANSI Header Function Standard Description File chdir Change current data modes h directory chmod Change file access modes h permissions chown Change owner of file modes h chxdir Change current execution modes h directory _cleareof Clear end of file condition stdio h cleareof clearerr Clear error condition stdio h close Close path modes h closedir Close named directory dir h stream creat Create file modes h create Create file modes h detach Detach device modes h dup Duplicate path modes h fclose Close file stdio h fdopen Attach path to file pointer stdio h Table 1 9 Ultra C I O Functions continue
500. s 5 pos is the address of the long integer into which the current file position is placed The function returns 1 on error and Zero on success 6 The function returns 1 on either EOF or error and 0 if not at EOF Note Only the lower 16 bits of code are used path must be the path number of an open file When getstat returns with the value 1 the appropriate error code is placed in the global variable errno WX MICROWARE Note getstat is supported for the convenience of programs ported from the 6809 Attributes Operating System State Threads Re entrant Library Sys clib 1l1 See Also os gs devnm os gs eof 08 ugs Tad 8 gs fdinf i os gs port os gs pos os gs ready oS gs size IS GetStt OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual get static Return Current Static Storage Pointer Syntax finclude lt regs h gt void get static void Description get static returns a pointer to the current static storage Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library pus See Also change_static WX MICROWARE _getsys Get System Global Variables Syntax include lt sysglob h gt finclude lt setsys h gt int _getsys int glob int size Description _getsys examines a system global variable These variabl
501. s Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library sys_clib 1 See Also fopen freopen feof Check Buffered File for End of File Syntax include lt stdio h gt int feof FILE stream Description feof tests the end of file indicator for the specified stream feof returns a non zero value only if the end of file indicator is set for stream stream is a pointer to the C I O FILE structure Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 See Also clearerr fopen WX MICROWARE ferror Check Buffered File for Error Condition Syntax include lt stdio h gt int ferror FILE stream Description ferror tests the error indicator for the specified stream ferror returns a non zero value only if the error indicator is set for stream stream is a pointer to the C I O FILE structure Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library Glib l See Also clearerr fopen fflush Flush File s Buffer Syntax include lt stdio h gt int fflush FILE stream Description fflush writes any unwritten data for the specified stream to the file Unwritten data is written if the stream was opened in either write or update mod
502. s Re entrant Standards Library mq 1l See Also mq send O_NONBLOCK was set in the message description associated with mqdes and the specified message queue is empty The mqdes argument is not a valid message queue descriptor open for reading The specified message buffer size msg_len is less than the message size attribute of the message queue The mq_receive operation was interrupted by a signal The mq_receive function is not supported by this implementation A data corruption problem with the message has been detected OS 9 User Safe No POSIX WX MICROWARE mq send Send a Message to a Message Queue Syntax finclude lt mqueue h gt int mq send mqd t mqdes const char msg ptr size t msg len unsigned int msg prio Description mq send adds the message pointed to by the argument msg ptr to the message queue specified by mqdes The msg 1en argument specifies the length of the message in bytes pointed to by msg ptr The value of msg 1en is less than or equal to the mq msgsize attribute of the message queue otherwise mq send fails If the specified message queue is not full nq send behaves as if the message is inserted into the message queue at the position indicated by the msg prio argument A message with a larger numeric value of msg prio is inserted before messages with lower values of msg prio A message is inserted after other messages in the queue if any with equal
503. s gs fdaddr returns the file descriptor block number associated with the specified path number path specifies the driver s path number addr is a pointer to the location where os gs daddr stores the block address of the file descriptor Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l1 _os gs fdinf Get Specified File Descriptor Sector Syntax include lt rbf h gt include lt types h gt error_code _os_gs_fdinf path_id path u_int32 size u_int32 fdblk fd stats fdbuf Description _os_gs_fdinf returns a copy of the specified file descriptor sector for the file associated with the specified file descriptor sector path specifies an open path on a particular device size specifies the number of bytes of the file descriptor block to copy fdblk specifies the file descriptor sector number to get fdbuf is a pointer to the buffer for the file descriptor block Note Typically os gs fdinf is used to rapidly scan a directory on a device You do not need to specify the path number of the file for which you want the file descriptor in path However path must be an open path on the same device as the file patn is typically the path number of the directory you are currently scanning WX MICROWARE Note Only super users may use this call Attributes Operating System OS 9 and OS 9 for 68K State User and Syst
504. s a pointer to the area e If the allocation fails 1calloc returns NULL Note Use of the low overhead allocation functions 1calloc lmalloc and 1realloc instead of the general allocation functions calloc malloc and realloc saves 8 bytes per allocation because the low overhead functions do not save the allocation size or the 4 byte check value Note Use extreme care to ensure that you only access the assigned memory Modifying addresses immediately above or below the assigned memory causes unpredictable program results The low overhead functions require that you keep track of the sizes of allocated spaces in memory Note the 1f ree and 1realloc parameters Attributes Operating System State Threads Re entrant Library clib See Also calloc free lfree lmalloc lrealloc malloc mallocmin os9 srqmem realloc OS 9 and OS 9 for 68K User and System Safe No WX MICROWARE Idexp Multiply Float by Exponent of 2 Syntax include lt math h gt double ldexp double fp int exp Description ldexp multiplies a floating point value by an integral power of two ldexp returns the value equal to fp 2 exp fp is the floating point value exp is the integral power of two Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI
505. s an optionally signed integer whose format is the same as expected for the subject sequence of st rtol The base parameter is 0 The corresponding parameter is a pointer to an integer No input is consumed The corresponding parameter is a pointer to an integer into which to write the number of characters read from the input stream so far by this call to fscanf Executing a n directive does not increment the assignment count returned when fscanf finishes execution Table 2 10 fscanf Conversion Specifiers continued Flag Description Matches an optionally signed octal integer whose format is the same as expected for the subject sequence of st rtoul The base parameter is 8 The corresponding parameter is a pointer to an unsigned integer Matches the set of sequences that may be produced by the p conversion of fprintf The corresponding parameter is a pointer to a void The input item is interpreted the same as x If the input item is a value converted earlier during the same program execution the resulting pointer compares equal to that value Otherwise the behavior of the p conversion is undefined Matches a sequence of non white space characters The corresponding parameter is a pointer to the initial character of an array large enough to accept the sequence and a terminating null character The terminating null character is added automatically Matches an optionally signed decimal integer whose format
506. s are always allocated by the binding although only the specified number of bytes are passed back to you Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 os gs pos Get Current File Position Syntax include sg codes h finclude lt types h gt error code os gs pos path id path int32 position Description OS gs pos returns the current position of the file pointer associated with the specified path path specifies the driver s path number positionis a pointer to the location where os gs pos stores the file position Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os9 gspump Return Data for Specified Process Memory Map Syntax finclude lt process h gt finclude lt types h gt error code os9 gspump process id proc id u int32 size void buffer Description os9 gspump returns data about a specified process memory map for debugging purposes proc id specifies the process ID size specifies the size of the buffer buffer Is a pointer to the storage buffer One word in this format is returned for each memory block in the system This information is taken from the process SSM data structure If the specified address space is not large enough only the information that fits in
507. s of pid greater than 1 1 is an invalid process ID the exit status of the specified process is returned The options parameter can either be 0 to indicate a blocking wait or WNOHANG to indicate a non blocking wait If or when a child s exit status is available waitpid returns the process ID and if stat 1oc is non NULL writes the exit status at stat loc lfa blocking waitpid is interrupted by a signal it sets errno to EINTR and returns 1 If options is WNOHANG and the calling process has children but none of the specified children has available exit status 0 is returned Otherwise errno is set to the error number and 1 is returned Attributes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant Yes Library Sys clib l Possible Errors ECHLD The calling process has no children or not the specific child requested WX MICROWARE EINTR A blocking waitpid was interrupted by a signal EINVAL The value of options is invalid Example while waitpid child amp status 0 1 amp amp errno EINTR See Also wait pthread join pthread exit wcstombs Convert Sequence of Wide Chars to Multibyte Chars Syntax include lt stdlib h gt size_t wcstombs char Stf const wchar t pwcs size t maxnum Description wcstombs converts a sequence of codes that correspond to multibyte characters from an array into a sequence of multibyte characters that b
508. s taken as a flag followed by a positive field width A negative precision parameter is taken as if the precision was omitted The conversion specifiers and their meanings are Table 2 9 fprintf Conversion Specifiers Flag Description e E The int parameter is converted to an unsigned char and the resulting character is written The int parameter is converted to a signed decimal in the style 1dddd The precision specifies the minimum number of digits to appear If the value being converted can be represented in fewer digits it is expanded with leading zeros The default precision is 1 The result of converting a zero value with a precision of zero is no characters The double parameter is converted in the style d ddde dd where there is one digit before the decimal point character which is non zero if the parameter is non zero and the number of digits after the decimal point character is equal to the precision The default precision is 6 If the precision is zero and the flag is not specified no decimal point character appears The value is rounded to the appropriate number of digits The E conversion specifier produces a number with E instead of e introducing the exponent The exponent always contains at least two digits If the value is zero the exponent is zero WX MIC ROWARE Table 2 9 fprintf Conversion Specifiers continued Flag Description f The double parameter is conve
509. s the number of the table element Only the lower 16 bits of number are used address is a pointer to the location where os9 findpd stores the table entry pointer table is a pointer to the table to use Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library os lib l See Also os9 allpd os9 retpd FSFindPD OS 9 for 68K Technical Manual os firq Add or Remove Device from Fast IRQ Table System State Only Syntax finclude lt regs h gt error code os firqQ WANES vector u_int32 priority void irg_entry void statics Description os firq installs an IRQ service routine into or removes one from the system s fast IRQ system vector specifies the vector number priority specifies the priority priority is reserved and must be zero irq_entry is a pointer to the IRQ service routine s entry point If irq entry is zero the IRQ service routine is deleted statics is a pointer to the global static storage This fast IRQ system provides a faster interrupt response context than the normal IRQ vector polling scheme provided through _os9_irq e To place a routine into the fast IRQ system set irq entry toa non zero value e To remove a routine from the fast IRQ system set irg entry to zero Only one os firq routine can be active at a time per vector An attempt to install a second routine on a vector using os firq causes an EOS VCTBSY error
510. s wait stores the child process exit status code Note If a signal is received by a process waiting for children to terminate the process is activated In this case child id contains zero because no child process has terminated Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also os exit oes _fork os send FSWait OS 9 for 68K Technical Manual F WAIT OS 9 Technical Manual WX MICROWARE os waitid Wait for a Specified Process or Thread to Exit Syntax finclude lt process h gt error code os waitid process id child id error code status signal code signal Description _os_waitid causes the calling process or thread to wait for the specified thread or process The value pointed by child id specifies the process or thread to wait for If the value of child idis the ID of a thread the caller must be a thread in the same process as child id Otherwise an EOS IPRCID error is returned If the call is successful the status returned from chiid idis returned in the location pointed to by status If the wait is interrupted by a signal a value of EOS_BSIG is returned by os waitid and the value of the signal that caused the interruption is stored in the location pointed to by signal Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Lib
511. s with values from 0 to 0x1 f and 0x7f c is the character to test Note This routine available as a function or a macro in ctype h does not operate well with values outside the range of an unsigned char The function checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b iscntrl c Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Ultra C Library Reference 383 WX MICROWARE Library ctype h See Also isalnum isal ae islower isprinti isspace Supper LE 384 Ultra C Library Reference isdigit See If Parameter Is Digit Syntax include lt ctype h gt int isdigit int c Description isdigit is a C macro that returns a non zero value for any decimal digit character c is the character to test Note This routine available as a function or a macro in ctype h does not operate well with values outside the range of an unsigned char The f
512. s9time h 23 outc 45 864 outl 45 865 output capability string 1060 character to file 267 883 character to standard out 883 string to file 268 886 ABCDEFGHIJKLMNOPQRSTUVWXYZ word to file 887 outw 45 866 parameter _isascii 380 _isjis_kana 387 389 393 issjist 401 _issjis2 403 is it alphabetic 378 is it alohanumeric 376 is it ASCII 380 is it control code 383 is it digit 385 is it Hankaku kana 387 389 393 is it hexadecimal 409 is it Kanji 401 403 is it lower case 395 is it printable 397 is it printing character 391 is it punctuation 399 is it upper case 407 is it white space 405 isalpha 378 isascii 380 iscntrl 383 isdigit 385 isgraph 391 islower 395 isprint 397 ispunct 399 isspace 405 isupper 407 isxdigit 409 parent process ID determine 319 parse disk file pathlist 867 path name 722 segment 882 ABCDEFGHIJKLMNOPQRSTUVWXYZ password file close endpwent 200 get entry 324 get file entry fgetpwent 247 get name 323 327 get next entry for name getnextpwnam 314 get user identification 329 reset for searching 939 path gs opt 350 os Ss fillbuff 806 os dup 571 _os_prsnam 722 OS ss close 798 os tranpn 843 _os9 ss open 812 _prsnam 882 Ss opt 981 close 172 535 copy options 350 create to new file 545 547 dup 196 dup2 197 duplicate 196 197 571 fill buffer with data 806 get options 350 notify driver 798 of open path 812 open 71
513. s_getsys Examine system global sysglob h variable _os9_gs_cdfd Return file descriptor cdi h _os_gs_cpypd Copy contents of path sg_codes h descriptor os_gs_cstats Get cache status rbf h information _os_gs_devnm Return device name sg_codes h _os_gs_devtyp Return device type sg_codes h _os_gs_dopt Read device path sg_codes h options _os_gs_dsize Get size of SCSI devices rbf h _os_gs_edt Get I O interface edition ioedt h number _os_gs_eof Test for end of file sg_codes h _os_gs_fd Read file descriptor rbf h sector os_ga_fdaddr Get file descriptor block rbf h address for open file os gs fdint Get specified file rbf h descriptor sector Table 1 7 GetStat SetStat Functions continued Function ANSI Standard Description Header File os9 gs free OS gs luopt o8 gs parity os qs popt 0 os gs pos oS gs ready OS gs size oS setstat os setsvc _os_setsys _os_sgetstat _os_sgs_devnm os 55 attri OoS ss break Return amount of free space on device Read logical unit options Calculate parity of file descriptor Read path descriptor option section Get current file position Test for data ready Return current file size Set file device status Adds or replaces a System service Set system global variables GetStat call using system path number Return device name Set file attributes
514. sage if insufficient stack area exists to call a function Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also ebrk _freemem freemem sbrk Stacksiz stacksizi WX MICROWARE inc Get Character From I O Address Syntax finclude lt regs h gt finclude lt types h gt u_char inc void address Description inc returns the character indicated by the specified I O address on the 80x86 processors or the memory address on all other processors address is the specified I O address Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library cpu l See Also inl inw oute outl outw index Search for Character in String Syntax include strings h char index char ptr int oh 5 Description index returns a pointer to the first occurrence of a character in a string If the character is not found index returns NULL ptr is a pointer to the string ch is the character for which to search Only the lower 8 bits of cn are used Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l Example This example looks for a period in string and sets the pointer ptr Note that ch is a character not a pointer to a character func char p
515. scriptor 549 temporary binary file 1053 unique filename 461 create temporary filenames 1042 create 46 102 186 crtolf 188 CST 84 cstart r 10 ctime 87 189 ctype h 15 cube root cbrt 153 cursor movement get capability 1049 tgoto 1049 data ABCDEFGHIJKLMNOPQRSTUVWXYZ gs rdy 353 os move 711 carrier detect 799 800 move 711 test for available 353 data module os datmod 550 os mkmodule 708 create 550 708 specify color type 708 deallocate bits in bit map 554 memory 271 process descriptor 559 732 debugged program 561 os dexec 561 os dexit 564 os dfork 565 _os9 dfork 567 execute 3561 exit 564 fork 565 567 terminate 564 debugger control os dforkm 569 fork process 569 delete existing event 581 existing lock descriptor 557 existing module directory 558 file 555 903 1066 1067 detach device 191 560 detach 46 102 191 determine end of file 346 file accessibility 116 number of bytes in multibyte character 450 parent process ID 319 path number from file 249 process ID 318 size of unused stack area 272 ABCDEFGHIJKLMNOPQRSTUVWXYZ string length 1009 user ID 338 device 521 648 gs devn 344 Os alias 513 os close 535 os detach 560 OS getstat 648 OS gs devnm 656 Os gs devtyp 657 OS gs dopt 659 OS gs dsize 660 os irq 686 os open 713 os read 726 OS setstat 765 Os sgs devnm 773 Os ss dopt 801 OS ss relea 814 OS wri
516. semaphore i e the waiting process if running at the same priority was unable to obtain it Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also OoSs sema init os sema p OS Sema term WX MICROWARE os send Send Signal to Another Process Syntax include signal h finclude lt types h gt error code os send process id proc id signal code signal Description os send sends a signal to the specified process A process may send the same signal to all processes of the same group user ID by passing zero as the receiving process ID number proc idis the process ID number for the intended receiver signal specifies the signal code to send Only the lower 16 bits of the signal value are used The upper 16 bits are ignored Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also os wait os intercept os sleep F Send OS 9 for 68K Technical Manual F SEND OS 9 Technical Manual os setcrc Generate Valid CRC in Module Syntax include module h include lt types h gt error code _os_setcrc mh_com mod_head Description os setcrc updates the header parity and CRC of a module in memory The module must have the correct size and sync bytes other parts of the module are not check
517. ser and System Threads Safe Re entrant Yes Library os lib l See Also os sleep Os walt i Example To ensure that an entire structure can be cleared without the reception of a signal one might use _os_sigmask 1 memset sptr 0 sizeof sptr os sigmask 1 The state of the signal mask is preserved using this method To avoid a race condition _os_sigmask 1 sig_received FALSE sleep 0 sleep does an implied os sigmask 0 OS sigreset Reset Signal Intercept Context Stack Syntax include signal h error code os sigreset void Description os sigreset resets the context stack for a signal intercept Normally the operating system keeps the state of the process on the system stack while a signal intercept routine executes If signals are unmasked during the intercept routine and another signal occurs before the intercept routine finishes another state is pushed on the system stack Similarly if the intercept routine does a 1ong jmps and then unmasks signals more states are placed on the system stack by subsequent signals To prevent the system stack from overflowing whenever a program uses long jmp calls out of an intercept routine or unmasks signals in an interrupt service routine with the intent of never using os rte to return it should use os sigreset if setjmp x 0 _os_sigreset _os_sigmask 1 If the code actually expects to return thr
518. sgsize attribute of the message queue the function fails and returns an error Otherwise the selected message is removed from the queue and copied to the buffer pointed to by the msg pt x argument If the argument msg prio is not NULL the priority of the selected message is stored in the location referenced by msg prio If the specified message queue is empty and o NONBLOCK is not set in the message queue description associated with mqdes mq receive blocks until a message is enqueued on the message queue or until mq_receive is interrupted by a signal If more than one thread is waiting to receive a message when a message arrives at an empty queue and the Process Scheduling option is supported then the thread of highest priority that has been waiting the longest is selected to receive the message Otherwise it is unspecified which waiting thread receives the message If the specified message queue is empty and O NONBLOCK is set in the message queue description associated with mqdes no message is removed from the queue and mq receive returns an error Upon successful completion mq receive returns the length of the selected message in bytes and the message is removed from the queue Otherwise no message is removed from the queue the function returns a 1 and sets errno to indicate the error Errors EAGAIN EBADF EMSGSIZE EINTR ENOSYS EBADMSG Attributes Operating System State Thread
519. should be closed with pc1ose which waits for the associated process to terminate and returns the exit status of the command Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l See Also pclose pipe popen WX MIC ROWARE pow Power Function Syntax include lt math h gt double pow double X double y Description pow returns x raised to the y power A domain error occurs Ei DOM stored in errno if x is negative A domain error also occurs if both x and y are zero A range error ERANGE stored in errno occurs on underflow and overflow pow returns HUGE VAL for both errors Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 Possible Errors EDOM ERANGE prerr Print Error Message Syntax include lt stdio h gt int prerr int path int errnum Description prerr prints an error message corresponding to an error number on the standard error path path is the path number of the error message file errnunm is the error number It is divided into two numbers e OS 9 for 68K Error numbers are 2 bytes wide The most significant byte is the error s group number and the least significant byte is the specific error within that group e OS 9 Error numbers are 4 bytes wide The most signifi
520. signal and kills the running program If a program requires immediate control of the terminal perform some I O to one of the standard paths such as printing a program banner or getting the terminal options with gs opt For More Information Refer to your operating system technical manual for more information Note For each signal recognized by signal the default handling is program termination with an exit status related to the exception or the signal number for non exception related signals and the program startup condition is STG_DFL The default handling is reset on all signals Default Handling If you specify default handling the process terminates and the termination status is set to the signal number that occurred This occurs if no signal has been called for the signal or signal was called with SIG DFL as func If the program has used intercept the signal handler assigned to the call is called and execution resumes at the point of interruption instead of terminating Note Donotuse os intercept With signal WX MIC ROWARE Ignore Handling If a signal occurs that is to be ignored the program resumes at the point of interruption If the occurring signal is exception related the process terminates with the appropriate vector as the exit status Effectively exception related signals cannot be ignored Available Signals The set of signals for the signal fun
521. signal is a pointer to the location where os ev anyset stores the signal code If the process receives a signal while in the event queue it is activated even though the event has not actually occurred mask specifies the activation mask Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l See Also F EVENT OS 9 Technical Manual F EVENT EV ANYSET OS 9 Technical Manual F EVENT EV SIGNL OS 9 Technical Manual WX MICROWARE os ev change Wait for Event to Occur Syntax include lt events h gt finclude lt types h gt error_code _os_ev_change event_id ev_id int32 value signal code signal u int32 mask u int32 pattern Description oS ev change Waits for an event to occur That is it waits until an _os_ev_signal occurs that changes any of the bits corresponding to the set bits in mask ev_id identifies the event value is a pointer to the location where _os_ev_change stores the actual event value signal is a pointer to the location where os ev change stores the signal code If the process receives a signal while in the event queue it is activated even though the event has not actually occurred mask specifies the activation mask pattern specifies the wait pattern Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l See Also F EVENT OS 9 Technical Manual F
522. signal mask to the value specified in the siglvl variable Returns to the process restoring the context copied from the user state process stack image The operating system takes appropriate precautions to verify that the memory location pointed to by the usp variable is accessible to the process and to ensure that the process does not attempt to make a state change The stack image pointed to by the usp variable must have the format shown in Figure 2 9 Figure 2 9 os siglngj Required Stack Image Processor High Memor Context FPU User Stac Context Low Memory Pointer usp variable The specific format of the processor context is defined by the 1ongstk structure definition found in the reg lt CPU Family h file for the associated processor The format of the floating point context varies depending on whether the target system has a hardware floating point unit versus floating point emulation software For floating point hardware the stack image is the same as that defined by the regs structure definition found in the associated reg CPU Family h header file For floating point emulation the floating point context differs from the hardware implementation context in that it may contain additional context information specific to the FPU module performing the emulation The definition for the floating point context as used by the FPU module is the pu context structure which is also defined in the associated r
523. sociated numeric value if possible buf is a pointer to a pointer to a string containing a printable representation of a number expressed in base ten The number may be an integer or a real number You may also express the number in the following exponential format number E e exponent value is a pointer to one of the three possible values that can be returned Table 2 3 aton Return Values Value Description ERROR No recognizable number is found or the value cannot be represented it would cause overflow or underflow INTEGER The recognized number is an integer REAL The recognized number is not an integer _aton updates buf to point to the character just after the recognized string It updates value to contain the recognized number unless an error occurs Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library clib 1 WX MICROWARE _atou Alpha to Unsigned Conversion Syntax include lt stdlib h gt unsigned _atou char string Description _atou converts a string into its appropriate unsigned numeric value if possible string is a pointer to a string containing a printable representation of a number expressed in the format t digits _atou treats Long and int values identically Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Y
524. specified as func finclude lt types h gt error code os exec u int32 func u int32 priority u int32 pathcnt void modname char argv char envp u int32 datasize Description os exec prepares the parameter and environment list before creating a process The function to create a new process passes information to the new process as binary data specified by a pointer and size It is up to the forked process to interpret the data func is a pointer to one of the following functions that create a new process e OS 9 for 68K os fork os9 dfork O0f os chain e OS 9 os fork os forkm os chain os chainm os dfork O0f os dforkm priority is the priority value at which the new process is to run Only the lower 16 bits of priority are used If priority is zero the new process receives the priority of the calling process pathcnt is the number of open paths to pass to the new process Normally pathcnt is three causing the three standard paths to be passed A value of zero passes no open paths Only the lower 16 bits of pathcnt are used WX MICROWARE modname is a pointer to a string naming the new primary module or a pointer to the module in the case of the functions ending in m os forkm os chainm and os dforkm argv is a pointer to the parameter pointer list that the new process is to receive By convention argv 0 is the name of the new module The en
525. ss when a modem connection is lost SIGALRM Not automatically sent Programs could use this signal for an alarm call SIGPIPE Not automatically sent SIGUSR1 Condition is user defined SIGUSR2 Condition is user defined AN MICROWARE 680x0 OS 9 for 68K OS 9 Table 2 30 OS 9 for 68K and OS 9 Core Signals for 680x0 Signal Description SIGADDR Address error SIGCHK CHK instruction SIGTRAPV TRAPYV instruction SIGPRIV Privilege violation SIGTRACE Trace exception SIG1010 1010 line A exception SIG1111 1111 line F exception 680x0 OS 9 Table 2 31 OS 9 Core Signals for 680x0 Signal Description SIGCOPRCV Coprocessor protocol violation SIGFMTERR Format error SIGUNIRQ Uninitialized interrupt 80x86 OS 9 Table 2 32 OS 9 Core Signals for 80x86 Signal Description SIGGPROT General protection SIGSTACK Stack exception SIGSEGNP Segment not present SIGINVTSS Invalid TSS SIGDBLFLT Double fault SIGBNDCHK Boundary check SIGBRKPT Breakpoint SIGNM Non maskable interrupt SIGDBG Debug exception AN MICROWARE PowerPC OS 9 Table 2 33 OS 9 Core Signals for PowerPC Signal Description SIGALIGN Alignment SIGCHECK Machine check SIGINST Instruction access SIGPRIV Privilege violation Function Handling If a signal which has an associated function occurs the equivalent of func
526. ss skip 43 821 Os ss skipend 43 822 Os ss ticks 43 823 os ss wim 43 824 OS ss wtrack 43 825 _os9 ss open 43 812 Ss attr 44 971 Ss dcoff 44 975 Ss dcon 44 976 Ss dsrts 44 977 Ss enrts 44 978 Ss lock 44 979 Ss opt 44 981 Ss pfd 44 983 ss rel 44 985 Ss rest 44 986 Ss size 44 987 Ss ssig 44 988 Ss tiks 44 990 Ss wtrk 44 992 break serial connection 41 796 disable RBF caching 42 797 RTS line 42 44 802 977 enable RBF caching 42 797 RTS line 42 44 803 978 erase tape 42 804 fill path buffer with data 42 806 flush cached bit map information for RBF device 42 807 list of functions 39 lock out record 42 44 810 979 make hard link to existing file 42 808 notify driver that path has been closed 42 798 opened 43 812 put file descriptor sector 44 983 IJKLMNOPQRSTUVWXYZ ABCDEFGHIJKLMNOPQRSTUVWXYZ release device 43 44 814 985 rename file 43 815 restore device 44 986 head to track zero 43 816 retension pass on tape drive 817 send data carrier lost signal to process 44 975 present signal to process 44 976 signal on data ready 43 44 819 988 when DCD line goes false 42 799 when DCD line goes true 42 800 set current file size 44 987 device path options 42 801 file attributes 41 44 795 971 size 43 820 status 44 940 file device status 41 765 path options 44 981 system global variable 41 770 setstat 44 940 skip blocks 43 821 t
527. ssors The OS 9 SH3 family signal shown in Table 1 35 is sent when the associated exception occurs Table 1 35 OS 9 SH3 Family Exception Signals Signal Exception SIGALIGN Alignment AN MICROWARE SPARC Family Processors The OS 9 SPARC family signals shown in Table 1 36 are sent when their associated exception occurs Table 1 36 OS 9 SPARC Family Exception Signals Signal Exception SIGALIGN Alignment SIGWINDOWOV Window Overflow SIGWINDOWUV Window Underflow SIGATAGOV Tag Overflow SIGCPE Coprocessor Exception The default handling and the handling at program startup for each signal recognized by the signal function 4 7 1 1 For each signal recognized by signal the default handling is program termination and the program start up condition is SIG_DFL The program terminates with an exit status related to the exception or the signal number for non exception related signals If the equivalent of signal sig SIG_DFL is not executed prior to the call of the signal handler the blocking of the signal that is performed 4 7 1 1 signal sig SIG DFL is executed before the call to the signal handler Signals are blocked for the duration of the signal handler unless the program takes some action that unblocks signal Refer to your operating system technical manual for more information Whether the default handling is reset if the SIGILL signal is received by a handler speci
528. st SPR ear SPR e ecr SPR eid SPR eie SPR e esr SPR evpr SPR exier DCR exisr DCR fpecr SPR Table 2 25 set name Valid Name Values continued Register Processor s name Type 403 505 601 603 User Readable fpscr PREG e e hashl SPR hash2 SPR hido SPR hidl SPR hidl15 SPR s hid2 SPR e hid5 SPR iabr SPR e iac1 SPR e iac2 SPR ibatOl SPR e ibat0u SPR e ibat11 SPR ibatlu SPR ibat21 SPR e ibat2u SPR WX MICROWARE Table 2 25 set name Valid Name Values continued Register Processor s lt name gt Type 403 505 601 603 User Readable ibat31 SPR e ibat3u SPR icadr SPR icer SPR iccst SPR icdat SPR icmp SPR e apta SPR imiss SPR e lcm DCR lctrl1 SPR i lotris SPR das SPR mq SPR nei SPR e msr PREG e e pbll SPR Table 2 25 set name Valid Name Values continued Register Processor s name Type 403 505 601 603 User Readable pbl2 SPR e pbul SPR pbu2 SPR pir SPR pit SPR rpa SPR rte SPR e rtcu SPR sdrl SPR e sprg0 SPR sprgl SPR sprg2 SPR e e sprg3 SPR e sro PREG sr1 PREG e sr2 PREG e sr3 PREG WX MICROWARE Table 2 25 set name Valid Name Values continued Re
529. stination for the copy from is a pointer to the structure to copy count is the number of bytes to copy Note Strass can move at most 65536 bytes No regard is given to overlapping moves Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l WX MICROWARE strcat String Catenation Syntax include lt string h gt char strcat char Or Lg const char append Description strcat appends a copy of append including the terminating null character to the end of orig The initial character of append overwrites the null character at the end of orig If copying takes place between overlapping objects the behavior is undefined orig is a pointer to the original string append is a pointer to the string to append to orig strcat returns the value of orig Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 strchr Locate String Syntax include lt string h gt char strchr const char Src int chr Description strchr locates the first occurrence of chr converted to a char in string src The terminating null character is considered part of the string src is a pointer to the string to search chr specifies the character for which to search strchr returns a pointer to the located character or a null po
530. sts entirely of white space or if the first non white space character is other than a sign or a permissible letter or digit 3 A final string of one or more unrecognized characters including the terminating null character of the input string strtoul then attempts to convert the subject sequence to an unsigned integer and returns the result e fbaseis zero strtoul expects the subject sequence to be an integer constant optionally preceded by a plus or minus sign An integer suffix is not included If the subject sequence is an integer constant the character sequence starting with the first digit is interpreted as an integer constant fbase is between 2 and 36 the subject sequence is expected to be a sequence of letters and digits representing an integer base specifies the radix optionally preceded by a plus or minus sign It does not include an integer suffix The letters a through z regardless of case are assigned the values 10 to 35 Only letters whose assigned values are less than base are permitted If base is 16 the characters Ox or OX may optionally precede the sequence of letters and digits following the sign if present If the subject sequence has the expected form it is used as the base for conversion ascribing to each letter its value If the subject sequence begins with a minus sign the value resulting from the conversion is negated A pointer to the final string is stored in end unless end is a null poi
531. t double atan2 double y double X Description atan2 returns the arc tangent of y divided by x that is atan y x in the range x x radians acan2 uses the signs of both y and x to determine the quadrant of the returned value A domain error E DOM placed in errno occurs if both y and x are zero On error atan2 returns HUGE VAL Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 Possible Error EDOM WX MICROWARE atexit Specify Function to Call at Normal Program Termination Syntax include lt stdlib h gt int atexit void func void Description atexit specifies a function to be called without parameters at normal program termination Thirty two functions may be specified func is a pointer to the function atexit returns zero if it succeeds Otherwise it returns a non zero value Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library Clabes See Also exit atof Alpha to Floating Conversion Syntax include lt stdlib h gt double atof const char string Description atof converts a string into its equivalent representation in type double string is a pointer to the string Except that no error indication is given atof is equivalent to the followi
532. t x lt landvalue x 2 exp value is the floating point value exp is a pointer to the integral exponent of two Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 fscanf Input String Conversion Syntax include lt stdio h gt int fscanf FILE stream const char format Description fscanf reads input from a stream stream is a pointer to the C I O FILE structure format is a pointer to a character sequence format specifies the allowable input sequences and specifies how to convert these sequences for assignments If the format is exhausted while parameters remain the excess parameters are evaluated but are otherwise ignored The format is a multibyte character sequence beginning and ending in its initial shift state The format is composed of zero or more directives e One or more white space characters e An ordinary mutibyte character neither nor a white space character Aconversion specification A percent character introduces each conversion specification After the the following appear in sequence e An optional assignment suppressing asterisk character e An optional non zero decimal integer that specifies the maximum field width e An optional h 1 or L indicating the size of the receiving object The conversion specifiers d i and n are preceded by h if the
533. t No WX MICROWARE Library termlib l See Also togotot tputsi 1048 Ultra C Library Reference tgoto Get Cursor Movement Capability Syntax include lt termcap h gt extern char BC extern char UP char tgoto char motion_string int column int line Description tgoto returns a string suitable for positioning the cursor on the terminal Note tgetent must be called before any of the other termcap library functions motion string Is a pointer to the string given by the cm capability column specifies the column destination for the cursor line specifies the line destination for the cursor The extern variables UP and Bc set to the up and bc capability strings respectively are used to avoid placing a null or newline character into the output string tgoto returns a pointer to the translated motion string if the motion string was successfully created Otherwise the string OOPS is returned WX MICROWARE Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library termlib l time Get Calendar Time Syntax include lt time h gt time t time time t timer Description time determines the current calendar time The encoding of the value is unspecified timer is a returned value It is a pointer to the calendar time time returns the implementation s best approximation to the current calenda
534. t c Description isspace is a C macro that returns a non zero value for standard white space characters c is the character to test The standard white space characters are the following Table 2 14 isspace White Space Characters Description Character Space Form feed f Newline n Carriage return Nr Horizontal tab t Vertical tab v Note This routine available as a function or a macro in ctype h does not operate well with values outside the range of an unsigned char WX MICROWARE The function checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b isspace c Attributes Operating System State Threads Re entrant Standards Library ctype h See Also isalnum isalpha lgemtril H n He O z D K Se E oe oe aed dr OS 9 and OS 9 for 68K User and System Safe Yes ANSI Ultra C Library Reference isupper See If Parameter Is Uppercase Syntax include lt ctype h gt int isupper int c Description isupper is a C macro that returns a non zero va
535. t ctype h gt int toupper int c Description toupper converts a lowercase letter to the corresponding uppercase letter c is the character to convert If the parameter c is such that isupper c returns a non zero value is uppercase toupper returns the corresponding character Otherwise c is returned unchanged Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 See Also isupper WX MICROWARE tputs Output Capability String Syntax include lt termcap h gt extern char BC extern char UP void tputs char str int lines affected int outfunc void Description tputs Is used to output the capability strings to the terminal tputs decodes leading padding information from the st x string Note tgetent must be called before any of the other termcap library functions str is a pointer to the string lines affected is the number of lines the operation affects This should be set to 1 if not applicable out func is a pointer to a function called by tputs to output each successive character of the st x string Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library termlib l See Also gs opt Ultra C Library Reference 1061 WX MIC ROWARE tsleep Sleep for Specified Interval Syntax include
536. t has expired On failure select returns 1 sets errno to indicate the error and the path sets are not changed Note User applications using select can not use the os intercept function Note No paths in the except fds are ever returned since OS 9 for 68K does not support the concept of exceptional condition Attributes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant No Library unix 1 Ultra C Library Reference 915 WX MICROWARE set name Set Value of SPR DCR PREG or TB Syntax include lt getset h gt include lt types h gt void _set_ lt name gt u_int32 val Description The _set_ lt name gt class of functions can be used to set the value of Special Purpose Registers SPRs Device Control Registers DCRs Processor Registers PREG and Time Based Registers TBs Note All functions are provided It is the programmer s responsibility to avoid using system state only registers from user state and accessing registers that do not exist on the target processor All registers are accessible from system state Only those noted are available from user state Attempting to use system state registers from user state causes unpredictable results Table 2 25 _set_ lt name gt Valid Name Values Register Processor s name Type 403 505 601 603 User Readable bar SPR besr DCR tra C ihraryv Dafaran Ult
537. t is to be converted to an alternate form For o conversion it increases the precision to force the first digit of the result to zero For x or X conversion a non zero result has a 0x or 0X prefix For e E f g and G conversions the result always contains a decimal point character even if no digits follow Normally a decimal point character appears in the result of these conversions only if a digit follows it For g and G conversions trailing zeros are not removed from the result For other conversions the behavior is undefined 0 For d i o u x X e E f g and G conversions leading zeros following any indication of sign or base pad the field width no space padding is performed If the 0 and flags both appear the 0 flag is ignored For d i o u x and x conversions the 0 flag is ignored if a precision is specified For other conversions the behavior is undefined 2 An optional minimum field width If the converted value has fewer characters than the field width it is padded with spaces by default on the left or right if the left adjustment flag has been given to the field width The field width takes the form of an asterisk ora decimal integer 4 WX MIC ROWARE An optional precision that gives The minimum number of digits to appear for the d i o u x and x conversions The number of digits to appear after the decimal point character for e E and f conversions The max
538. t regs h gt finclude lt types h gt error code os cache u int32 control void addr u int32 size Description os cache performs operations on the system instruction and or data caches if there are any If cont rol is zero the system instruction and data caches are flushed Only non super group user state processes may perform this operation Any program that builds or changes executable code in memory must flush the instruction cache with os cache before executing the new code This is necessary because the hardware instruction cache is not updated by data write accesses and may contain the unchanged instruction s For example if a subroutine builds a system call on its stack you must execute the os cache call to flush the instruction cache before executing the temporary instructions WX MICROWARE For More Information Refer to your operating system technical manual for a description of the possible values for control addr specifies the target address for the flush operation size indicates the size of the target memory area to be flushed Note The cache should be flushed before trying to disable the data cache Only super group processes may perform precise operations of recon Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os _lib l See Also os scache FSCCtl OS 9 for 68K Technical Manual
539. ta mod headis a pointer to the location where os datmod stores the pointer to the module header Be careful not to alter the data module s header or name string to prevent the module from becoming unknown to the system Note The created module contains at least size usable data bytes but may be somewhat larger The module itself is larger by at least the size of the module header CRC and name string and it is rounded up to the nearest system memory allocation boundary Attributes Operating System State Threads Re entrant Library os lib l See Also _os_setcrc _os_move DatMod FS E DATMOI D OS 9 and OS 9 for 68K User and System Safe Yes OS 9 Technical Manual OS 9 Technical Manual WX MICROWARE os ddlk Check for Deadlock Situation Syntax finclude lt process h gt finclude lt types h gt error code os ddlk process id proc id Description os ddlk checks for a deadlock situation between processes A search for the current process calling process in the linked list of potential conflictors is begun from the process specified by proc id proc id specifies the process with which to begin the search If the calling process is already in the linked list of processes an EOS DEADLK error is returned to the caller If the process is not in the linked list the current process is added to the list associated with proc ia os ddlk
540. ta area for subsequent calls to the subroutine The calling program must store and maintain the subroutine s entry point and data pointer The calling program must also set the subroutine library s data pointer and dispatch to the correct subroutine sub numis the subroutine number Only the lower 16 bits of sub num are used mod name is a pointer to the name of the subroutine module lib exec is a pointer to the location where os slink stores the pointer to the subroutine entry point mem ptr is a pointer to the location where os slink stores the pointer to the subroutine static memory mod head is a pointer to the location where os slink stores the pointer to the module header You can remove a subroutine by passing a null pointer for the name of the module and specifying the subroutine number A process can link to a maximum of 16 subroutine libraries numbered from 0 to 15 Attributes Operating System State Threads Re entrant Library os lib l See Also 8 o tlinkt OS 9 User and System Safe Yes WX MICROWARE os slinkm Install User Subroutine Library Module by Module Pointer Syntax include lt module h gt finclude lt types h gt error code _os_slinkm u int32 sub num mh com mod head void ib exec void mem ptr Description os slinkm is passed a pointer to the subroutine library module to install It returns a pointer to the execution entry point and a pointe
541. tate User and System Threads Safe Re entrant No Library sys_clib 1 See Also fprintr i _prgname ev creat Create Event Syntax include lt events h gt int _ev_creat int ev_value int wait_inc int signal_inc char ev name Description ev creat creates an event ev value is the initial value for the event wait inc is the wait increment It is added to the value of the event when a successful ev wait ev waitr os ev wait Or os ev waitr is performed signal incis the signal increment It is added to the value of the event when an ev signal Or os ev signal is performed ev name is a pointer to the name for the event An event ID number is returned if the event is successfully created If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno For More Information Refer to your operating system technical manual for more information about events Attributes Operating System State Threads Re entrant Library Sys clib 1l1 See Also ev signal ev wait ev waitr os ev creat OoS ev signal Oos9 ev wait OS ev waitr FSEvent F EVENT EV CREAT EV SIGNL EV WAIT EV WAITR WX MICROWARE OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual
542. te 859 _os9 gs free 667 _os9 irq 688 Ss enrts 978 Ss rel 985 Ss rest 986 add to IRQ table 686 688 attach to system 143 521 close path 535 create alias 513 detach 560 detach 191 disable RTS line 977 enable RTS line 978 getname 344 get size of SCSI device 660 open 713 read datafrom 726 read path options 659 release 814 985 remove 191 560 from IRQ table 686 688 ABCDEFGHIJKLMNOPQRSTUVWXYZ restore 986 return amount of free space 667 name 656 773 type 657 set path options 801 status 765 write data 859 device controller ioctl 367 difftime 87 192 dirh 16 direct h 16 directory _os_altmdir 518 os chdir 530 os chmdir 534 os cmdperm 537 os delmdir 558 os fmod 627 os get mdp 644 os get moddir 645 os makdir 704 os makmdir 706 change current data 160 current execution 166 current module directory 534 permissions on module directory 537 working directory 530 chdir 160 chxdir 166 close named stream 174 closedir 174 create 438 459 704 create module directory 706 delete module directory 558 establish alternate module directory 518 find module directory entry 627 get ABCDEFGHIJKLMNOPQRSTUVWXYZ alternate module directory pathlist 644 copy of module directory 645 current module directory pathlist 644 get current working 340 initialize 704 makdir 438 make 704 mknod 459 open 501 opendir 501 readdir 893 reset position of directory stream 906 return curre
543. te or update access modes os writeln writes data until it encounters a carriage return character or count bytes Line editing is also activated for character oriented devices such as terminals and printers path is the path number of the file or device buffer is a pointer to the location where the bytes to be written are placed The number of bytes to write is passed at the location pointed to by count os writeln also stores the number of bytes written at the location pointed to by count Note On RBF devices any record that was locked is released Attributes Operating System State Threads Re entrant Library os lib l See Also os open os9 create os create os write WX MICROWARE OS 9 and OS 9 for 68K User and System Safe Yes os yield Yield the Processor Syntax finclude process h error code os yield void Description os yield causes the calling process or thread to be placed back into the active queue The active queue contents are aged and the highest aged process is given control of the processor In other words os yield causes the operating system to advance to the next executable process or thread It is possible that the next executable process or thread will be the one that called os vield The status of the process or thread s signal mask remains unchanged during this system call os yield ismuchlike os sleep with a tick count of 1
544. ted array of pointers to characters Each string is in the form lt name gt lt value gt lt name gt is the name of the environment variable lt value gt is the current value of the environment variable To modify the list you must either find the existing entry or enlarge the array and add an entry The base of the array is stored in the external variable environ Attributes Operating System State Threads Re entrant Standards Library clib l See Also os chain os chainm os dforkli 089 dfork s dqrtorkmi os exec os Tork osS9forkit osSrorkceu os forkm WX MICROWARE OS 9 and OS 9 for 68K User and System Safe No ANSI getgid Return Group ID Syntax include lt UNI unsigned int Description X os9def h getgid getgid returns the group identification of the current process Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l WX MIC ROWARE get_excpt_base Return Exception Table Base Address Syntax include lt types h gt finclude lt regs h gt u_int32 get_excpt_base void Description get excpt base returns the exception table base address Note get excpt base is only supported on the 80x86 family of processors version of the compiler Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Libra
545. tem Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE readv Read Input Syntax include UNIX os9def h int readv unsigned int fd struct iovec iov unsigned int iovcnt Description readv reads input the same action as read The difference is that readv scatters the input data into the iovcnt buffers specified by the members of the iov array iov 0 iov 1 iov iovont 1l If iovcnt is zero the value of the iov_len member in an iovec structure is less than zero or all the iov_len members of the iovec structures are zero readv returns 1 and sets the global variable errno For readv the iovec structure is defined as struct iovec caddr t iov base int iov len h Each iovec entry specifies the base address and length of an area in memory where data should be placed readv always fills an area completely before proceeding to the next Upon successful completion readv returns the number of bytes actually read and placed in the buffers Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix 1 WX MICROWARE realloc Resize Block of Memory Syntax include lt stdlib h gt void realloc void PEE size_t size Description realloc changes the size of a memory block The contents of the object are unchanged up to the lesser of the new and old sizes If th
546. th id path u in32 fd addr int32 link adj Description This 1I SETSTAT call sets the link count of a file The link count of a file indicates the number of hard links in the file system that point to a particular file This call can be used to correct the link count of files under corrupt file system conditions File link counts can only be adjusted by super user processes Attributes Operating System OS 9 State User System I O IRQ Threads Safe Re entrant Yes Library oslib 1 See Also be ss hdlinki _os_setstat WX MICROWARE os ss lock Lock Out Record Syntax include lt rbf h gt finclude lt types h gt error code os ss lock path id path u int32 size Description os ss lock locks out a section of the file from the current file pointer position up to the specified number of bytes path is the file s path number sizeis the size of the section to lockout e fsizeiszero all locks are removed record lock EOF lock and file lock e fsizeis Sffffffff the entire file is locked out regardless of the file pointer s location This is a special type of file lock that remains in effect until released by an os ss lock with size set to Zero a read or write of zero bytes or the file is closed Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 os ss luopt Write Logical Unit Options
547. that the module is in memory or in your current execution directory see modlink modload and modloadp Provide a full pathlist to the module os9kexec returns the value of func It returns 0 if successful otherwise it returns an error number Note Any program that executes a C program should do so using the os9kexec interface The cstart module can handle parameter strings passed by os9 fork and chain but no environment is available and the argv pointer list is separated by white space Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library Sys clib l Ultra C Library Reference For More Information The primary purpose of the sys clib 1 library is to provide a library for compatibility with the Microware K amp R C compiler For additional information refer to Appendix A Prototyping sys clib Functions See Also os exec os fork os forkm os chain os chainm os dforki os Grtorkmi Ultra C Library Reference 695 WX MICROWARE Example include lt module h gt include lt types h gt include lt const h gt extern int os fork extern char environ char argblk rename oldname newname yx 0 main u intl6 type lang mktypelang MT PROGRAM ML OBJECT process id pid If errno os9kexec os fork 0 no change in priority
548. the chained program The list of variable arguments is terminated by a NULL entry The NULL entry is followed by an environment pointer to use for the call to os chain envpis a pointer to an array of strings that constitute the environment of the process execle returns 1 and sets the global variable errno to indicate an error execle only returns an error if setting up for the os chain call fails Once an attempt to chain occurs the process exits if any error occurs Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix l WX MICROWARE See Also execl execv execvp 228 Ultra C Library Reference execv Calls a File With an Argument Vector Syntax include UNIX os9def h int execv char path char argv Description execv is a UNIX like interface to the os chain system call The argument to execv is an argument vector to pass to the chained process and the path to the program to chain to The last argument should be a NULL entry argv 0 is conventionally the name of the program being chained to Note To use execv link with unix 1 Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l See Also execl execle execvp WX MICROWARE execve Calls a File With an Argument Vector Syntax include
549. the access mode If data is to be written to the file mode must have the write bit set Only the lower 16 bits of mode are used path is a pointer to the location where _os9_create stores the path number perm specifies the attributes to use for the new file Only the lower 16 bits of perm are used If either the FAM SIZE bit or the S_ISIZE initial file size bit is set you can also pass an initial file size estimate as a variable argument For More Information Refer to the OS 9 for 68K Technical Manual for the available mode and attribute bits WX MICROWARE By default if the pathlist specifies an existing file name _os9_create returns an error Attributes Operating System State Threads Re entrant Library os lib l See Also 08 attach os close os makdir os open ISCreate OS 9 for 68K User and System Safe Yes OS 9 Technical Manual os crik Create New Resource Lock Descriptor Synta fincl fincl X lude lt lock h gt lude types h error code os crlk lk desc lock Description _os_crlk creates a new resource lock descriptor A resource lock descri ptor is allocated and initialized to a free state that is not currently owned lock to the is a pointer to the location where os crlk stores the pointer lock descriptor Lock is used as a handle to perform further operations on the lock Attributes Operati
550. the area is returned Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also FSGSPUMp OS 9 for 68K Technical Manual os gs ready Test for Data Ready Syntax include sg codes h finclude lt types h gt error code os gs ready path id path u_int32 incount Description os gs ready checks for data available to be read on the specified path RBF devices do not return the EOS NOTRDY error because there is always information available to be read on RBF devices os gs ready returns the number of bytes left in incount path specifies the driver s path number incount is a pointer to the location where os gs ready stores the number of characters available to be read Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE OS gs size Return Current File Size Syntax include sg codes h finclude lt types h gt error code os gs size path id path u int32 Slze Description _os_gs_size returns the current size of the file associated with the specified path path specifies the driver s path number size is a pointer to the location where os gs size stores the file size Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1
551. the compiler Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library cpu l WX MIC ROWARE set gdtr Set Global Descriptor Pointer Syntax finclude lt regs h gt void set gdtr u int32 base Description set gdtr sets the global descriptor pointer It is a system state only system call base is a pointer to the global descriptor Note set gdtr is supported only on the 80x86 family of processors version of the compiler Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library Cpu setgid Set Global Descriptor Pointer Syntax finclude UNIX os9def h int setgid unsigned int gid Description setgid sets the user s group identification of the current process as specified by gid setgid returns 1 on error and sets the global variable errno to indicate the error Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l WX MICROWARE setime Set System Time Syntax include lt time h gt int setime struct sgtbuf timebuf Description setime sets the system time from a time buffer The time units are defined in the time h header file This function uses the year 1900 as a base and the year passed to the function must be an offset of 1900 For example to use the set ime function and set to the year 2011 you need to p
552. the lock is not owned by another process the calling process is granted ownership and the call returns without error If the lock is already owned the calling process is suspended and inserted into a waiting queue for the resource based on relative scheduling priority When ownership of the lock is released the next process in the queue is granted ownership and is activated The activated process returns from the _os_acq1k call without error If a process received a signal while waiting on a lock the process is activated without gaining ownership of the lock The process returns from the _os_acq1k call with an EOS SIGNAL error code and the signal code returned in the signal pointer Note If a waiting process receives an S WAKEUP signal the signal code does not register and is zero Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library lock l See Also F_ACQLK OS 9 Technical Manual F_CAQLK OS 9 Technical Manual F_CRLK OS 9 Technical Manual F_DDLK OS 9 Technical Manual F_DELLK OS 9 Technical Manual F_RELLK OS 9 Technical Manual F WAITLK OS 9 Technical Manual WX MICROWARE os9 alarm atdate Send Signal at Gregorian Date Time Syntax include lt alarm h gt finclude lt types h gt error_code _os9_alarm_atdate alarm_id alrm id signal code signal u int32 time u int32 date OS 9 Attributes Compatibility
553. the lower 16 bits of mode are used mem ptr is a pointer to the beginning of the memory to check proc desc is a pointer to the process descriptor of the target process Note os chkmem only performs a useful function on MMU systems On non MMU systems os chkmem simply returns without checking the memory block s accessibility Attributes Operating System OS 9 and OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l See Also FSChkMem F CHKMEM OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE os chmdir Change Process Current Module Directory Syntax include lt moddir h gt finclude lt types h gt error code _os_chmdir char name Description _os_chmdir changes a process current module directory to the directory specified by name name is a pointer to a full pathlist or a pathlist relative to the current module directory To change to the system s root module directory specify aslash for name Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os_lib l os close Close Path to File Device Syntax finclude lt modes h gt finclude lt types h gt error code os close path id path Description os close terminates the I O path specified by path path is the path ID returned from a previous call to os open os create 0r
554. the multibyte character representation in str if str is not a null pointer At most MB CUR MAX characters are stored str is a pointer to the string in which to store the multibyte character representation wchar is the multibyte character to be represented If wchar is zero wctomb is left in the initial shift state If str is a null pointer wctomb returns the following Anon zero value if multibyte character encodings have state dependent encodings e Zero if multibyte character encodings do not have state dependent encodings If str is not a null pointer wctomb returns the following e 1 if the value of wchar does not correspond to a valid multibyte character The number of bytes contained in the multibyte character corresponding to the value of wchar The returned value is never greater than MB CUR MAX wctomb is supported for both the C and JAPAN locales Attributes Operating System State Threads Re entrant Standards Library clib l WX MICROWARE OS 9 and OS 9 for 68K User and System Safe Yes ANSI write Write Bytes to Path Syntax include modes h int write int path char buffer unsigned count Description write writes bytes to a path path is the path number The path number is an integer which specifies one of the standard path numbers 0 1 or 2 or a path number returned from a successful call to open creat create Or dup
555. the trap handler is unlinked lib exec is a pointer to the location where os tlink stores the pointer to the trap execution entry point mod head is a pointer to the location where os tlink stores the pointer to the trap module params is a pointer to any additional parameters Currently this is not implemented mem size specifies the additional memory size Note OS 9 only allows trap handlers to run in system state OS 9 for 68K allows trap handlers to run in either system state or user state Attributes Operating System OS 9 and OS 9 for 68K State User Threads Safe Re entrant Yes Library os lib l1 Ultra C Library Reference WX MICROWARE os tlinkm Install User Trap Handling Module by Module Pointer Syntax include lt module h gt finclude lt types h gt error code _os_tlinkm u_int32 trap_num mh_com mod_head void ib exec void params u int32 mem size Description os tlinkm is passed a pointer to the module to install If a trap module already exists for the specified trap number an error is returned If static storage is required for the trap handler it is allocated and initialized trap num Specifies the user trap number 1 through 15 mod headis a pointer to the module header lib exec is a pointer to the location where os tlinkm stores the pointer to the trap execution entry point params is a pointer to the additional parameters if necessar
556. til the conflict is removed This feature exists only on RBF devices _ss_tiks may be used to return the error EOS_LOCK to the program if the conflict still exists after a specified number of ticks have elapsed path specifies the file s path number tickcnt specifies the number of ticks to wait if a record lock conflict occurs while the file is open on path e Atickcnt of zero RBF s default causes a sleep until the record is released Atickcnt of one returns an error if the record is not released immediately If an error occurs 1 is returned and the appropriate error value is placed in the global variable errno For More Information Refer to your operating system technical manual for information on RBF record locking Attributes Operating System State Threads Re entrant Library Sys clib l See Also 08 5s ticks I SetsStt I_SETSTAT SS_TICKS OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual WX MICROWARE _ss_wirk Write Track Syntax include lt rbf h gt int _ss_wtrk int path int trkno int siden int ilvf char trkbuf char ilvptr Description _ss_wtrk performs a write track operation on a disk drive It is essentially a direct hook into the driver s write track entry point path is the path on which the device is open trkno is the track number on which to write siden is the side of the tra
557. tine s static global data This enables drivers and file managers to call the cache routine directly rather than making a possibly time consuming os scache request The prototype for this cache control routine is as follows error code cache cctl u int32 control void addr u int32 size The control addr and size parameters are as defined earlier The only exception is the C GETCCTL bit in the control parameter This obviously has no meaning in this context Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library os lib l1 See Also I SETSTAT SS CACHE OS 9 Technical Manual F CCTL System State OS 9 Technical Manual _os9_schbit Search Bit Map for Free Area Syntax include lt memory h gt finclude lt types h gt error_code _os9_schbit u_intl6 bit_number u intl6 count void address void bitmap end Description _os9_schbit searches the specified buffer which represents a bit map for a free block cleared bits of the required length starting at the beginning bit number os9 schbit returns the offset of the first block found of the specified length The beginning bit number to search is passed at the location pointed to bybit number os9 schbit also stores the beginning bit number found at the location pointed to by bit number The number of bits needed is passed at the location pointed to by count os9 schbit also stores t
558. ting System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 Example include lt string h gt static char str a b c char t t strtok str t points to the token a t strtok NULL t points to the token b t strtok NULL t points to the token c t strtok NULL t is a null pointer strtol String to Long Conversion Syntax include lt stdlib h gt long strtol const char begin char end int base Description strtol converts the initial portion of begin to long int representation begin is a pointer to the beginning of the string end is a pointer to the pointer to the first character after the converted string base is the base of the number string strtol separates the input string into three parts 1 An initial possibly empty sequence of white space characters as specified by isspace 2 A subject sequence resembling an integer represented in some radix determined by base The subject sequence is the longest initial subsequence of the input string starting with the first non white space character of the expected form The subject sequence contains no characters if the input string is empty or consists entirely of white space or if the first non white space character is other than a sign or a permissible letter or digit 3 A final stri
559. tion regerror is called with a character string for the error and NULL is returned When the compiled regular expression is no longer needed it can be passed to free Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix 1 See Also regerror regex regexec regerror Regular Expression Error Handler Syntax include lt UNIX regexp h gt void regerror char msg Description regerror is called by the functions regex and regcomp when various errors occur regerror prints the string regexp and the string pointed to by msg If printing a message is inappropriate for the application using regular expressions the programmer may define a regerror function to override the unix 1 version Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library unix l See Also regcomp regex regexec WX MICROWARE regex regexec Regular Expression Handler Syntax include UNIX regexp h int regex regexp re char str Description regex compares a string st x with a compiled regular expression re regex returns one if the strings match and zero if the strings don t match If an error occurs regerror is called with the appropriate error message and zero is returned to indicate the strings did not match Attributes
560. tions continued Zone Description ACT Australia Central Time AET Australian Eastern Time SST Solomon Standard Time NST New Zealand Standard Time n is the optional number of minutes east or west of the time zone ddd is the option controlling Daylight Savings Time Recognized codes for ddd are shown in Table 1 25 Table 1 25 Valid ddd Codes Value Description no Do not use Daylight Savings Time usa Conforms to the US Uniform Time Act of 1967 and its various amendments through 1987 eur Observe European Daylight Savings Time For example the following command specifies that the compiler should use the USA Eastern Daylight Savings Time and should conform to the US Uniform Time Act of 1967 setenv TZ EDT usa The American time zones default to usa with the exception of AST which defaults to no The European time zones default to eux and GMT UTC defaults to no If the TZ environment variable is not set and if on OS 9 m tmzone is not set time uses USA Central Standard Time CST Ultra C provides time functions identified in Table 1 26 ANSI prototypes for non ANSI functions are achieved by defining the macro name OPT_PROTOS during the compile Table 1 26 Time Functions ANSI Header Function Standard Description File asctime Convert broken down time to time h string format clock Get processor time time h ctime Convert calendar time to string time h fo
561. tions are permitted Only the lower 16 bits of mode are used path is a pointer to the location where os open stores the resulting path number Note A non directory file may be opened with no mode bits set This allows you to examine characteristics such as the attributes and size by the _os_getstat system requests but does not permit any actual I O on the path Attributes Operating System State Threads Re entrant Library os lib l See Also os attach os closet os create ISOpen I OPEN WX MICROWARE OS 9 and OS 9 for 68K User and System Safe Yes OS 9 for 68K Technical Manual OS 9 Technical Manual _os9_panic System Catastrophic Occurrence Syntax finclude lt process h gt finclude lt types h gt error code _os9_panic u_int32 panic code Description 0S9 panic is called when the kernel detects a disastrous but not necessarily fatal system condition Ordinarily os9 panic is undefined and the system dies panic code specifies the panic code to output _os9_panic is called only when the kernel believes there are no processes remaining to be executed Although the system is probably dead at this point it may not be Interrupt service routines or system state alarms could cause the system to become active Attributes Operating System OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l See Also _os9_setsvc
562. to be 32767 next next 1103515245 12345 return unsigned int next 65536 32768 next contains the current internal value for calculating pseudo random numbers Because the value of next is divided by 65536 before returning the value this algorithm avoids the common problem of non random low order bits By storing the value in an int this algorithm also allows the period of the sequence to be greater than RAND MAX Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 read Read Bytes from Path Syntax finclude lt modes h gt int read int path char buffer unsigned count Description read reads bytes from a path path specifies the path number of the path from which to read The path number is an integer indicating one of the standard path numbers 0 1 or 2 or a path number returned from a successful call to open creat create Or dup buffer is a pointer to a space with at least count bytes of memory into which read puts the data read from the path count is the minimum buffer size It is guaranteed that at most count bytes are read but often less are read either because the path serves a terminal and input stops at the end of a line or the end of file has been reached read essentially performs a raw read that is the read is performed without translating characters
563. to by ticks e fticks is zero the process sleeps indefinitely e fticks is one the process gives up a time slice but does not necessarily sleep for one tick e _os9_sleep Stores the number of ticks left to sleep when awakened prematurely at the location pointed to by ticks If _os9_sleep completes without interruption ticks contains the value 0 time may be specified in system clock ticks or if the high order bit is set the low 31 bits are considered a time in 256ths of a second Note _os9_sleep cannot be used to time more accurately than 1 tick because it is not known when the _os9_sleep request was made during the current tick Note The system clock must be running to perform a timed sleep The system clock is not required to perform an indefinite sleep or to give up a time slice Attributes Operating System State Threads Re entrant Library os lib l See Also os send oS wait Ultra C Library Reference OS 9 for 68K User and System Safe Yes d co C1 WX MICROWARE os slink Install User Subroutine Module Syntax include lt module h gt finclude lt types h gt error_code _os_slink u_int32 sub num char mod name void lib exec void mem ptr mh com mod head Description os slink attempts to link or load the named module It returns a pointer to the execution entry point and a pointer to the library s static da
564. to the location where os salarm cycle stores the alarm ID time specifies the alarm s time interval t ime may be specified in system clock ticks or if the high order bit is set the low 31 bits are considered a time in 256ths of a second Usually the minimum time interval allowed is 2 system clock ticks flags specifies the alarm flags func is a pointer to a function to execute func_pb is a pointer to the function s parameter block Attributes Operating System OS 9 State System Threads Safe Re entrant Yes Library os lib l See Also oS salarm set F ALARM OS 9 Technical Manual WX MICROWARE os9 salarm cycle Execute System State Subroutine Every N Ticks Seconds Syntax finclude lt regs h gt include alarm h finclude lt types gt h error code os9 salarm cycle alarm id alrm id u int32 time REGISTERS regs Description _os9_salarm_cycle executes a system state subroutine after the specified time interval has elapsed Then the alarm is reset to provide recurring periodic execution of the system state subroutine alrm idis a pointer to the location where os9 salarm cycle stores the alarm ID time specifies the alarm s time interval time may be specified in system clock ticks or if the high order bit is set the low 31 bits are considered a time in 256ths of a second Usually the minimum time interval allowed is 2 system clock ticks regs s a pointer to the re
565. tr Co a AA MICROWARE For More Information Refer to your operating system technical manual for information on the RBF File Manager Note You must use the OS 9 for 68K direct h header file This call is provided on OS 9 solely for compatibility with OS 9 for 68K If speed is an issue on OS 9 use os ss fd Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also 08 gs fd Au ss TOI I SetStt OS 9 for 68K Technical Manual I SETSTAT OS 9 Technical Manual I Iitra C I ihrary Rafaranra Ultra C Library Reference _ss rel Release Device Syntax include sg codes h int ss rel int path Description _ss_rel cancels the signal to send from a device on data ready path is the device s path number If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Note The signal request is also cancelled when the issuing process dies or closes the path to the device This feature exists only on SCF and PIPEMAN devices Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also OS SS relea os ss sendsig I SetStt OS 9 for 68K Technical Manual I SETSTAT SS RELEASE OS 9 Technical Manual WX MICROWARE Ss rest Restore Device Syntax include
566. tr string if ptr index string process ptr else printf No found Nn WX MICROWARE See Also rindexti strohri strrchr j 362 Ultra C Library Reference inl Get Integer from I O Address Syntax finclude lt regs h gt finclude lt types h gt u int32 inl void address Description inl returns the integer indicated by the specified I O address on the 80x86 processors or the memory address on all other processors address is the specified I O address Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library cpu l See Also inc inw oute cuui outw WX MICROWARE intercept Set Up Process Signal Handler Syntax include signal h int intercept void icpthand int Description intercept instructs the operating system to pass control to a signal handler function when the process receives a signal icpthand is a pointer to the function If the signal handler function declares an int parameter the function has access to the value of the received signal On return from the signal handler function the process resumes at the point in the program where it was interrupted by the signal If icpthand is zero the signal handler is removed Note A program does not receive an abort or quit signal from the keyboard usually c and E unless the program performs output to the term
567. translate is passed at the location pointed to by blk addr os transadd also stores the block that was translated at the location pointed to by b1k_addr os transadd is used when the external bus address must be passed to hardware devices such as DMA type controllers If the specified source block is nonlinear with respect to its destination mapping os transadd returns the maximum number of bytes accessible at the translated address reserved Is a pointer reserved for future use Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE _os9_translate Translate Memory Address Syntax include lt memory h gt finclude lt types h gt error_code _os9_translate u_int32 size u_int32 mode void kb1lk_addr Description _os9 translate translates an address to or from its external bus address The size of the block to translate is passed at the location pointed to by size os9 translate also stores the size of the block translated at the location pointed to by size mode specifies the type of translation f mode is zero the local CPU address is translated to the external bus address e f mode is one the external bus address is translated to the local CPU address The address of the block to translate is passed at the location pointed to by blk addr os9 translate also stores the block that was translated at the
568. trap handler 827 829 event variable 213 589 591 593 597 exception table base address 929 file attributes 795 971 size 820 status 765 940 global descriptor pointer 930 I O for new process 684 IRQ level 370 memory reclamation bound 274 minimum allocation size 445 path options 981 position of next readdir 913 process priority 764 938 signal handler 364 relative event variable 215 595 seed for random number generator 965 system date 760 762 ABCDEFGHIJKLMNOPQRSTUVWXYZ global variable 770 942 time 760 762 932 userID 771 944 value of registers _set_ lt name gt 916 set up signal intercept trap 679 set user identification 931 set_excpt_base 89 929 set_gdtr 89 930 setbuf 50 926 setgid 931 setime 88 108 932 setjmp 67 933 setimp h 27 setlocale 67 935 937 setpr 78 108 938 setpwent 939 SetStat OS setstat 41 765 OS setsys 41 770 OS ss attr 41 795 OS ss break 41 796 OS ss cache 42 797 Os ss close 42 798 Os ss dcoff 42 799 _os_ ss dcon 42 800 Os ss dopt 42 801 OS ss dsrts 42 802 OS ss enrts 42 803 OS ss erase 42 804 os ss fd 42 805 Os ss fillbuf 806 os ss fillbuff 42 os ss flushmap 42 807 Os ss hdlink 42 808 os ss lock 42 810 os ss luopt 43 811 OS ss popt 43 813 Os ss relea 43 814 OS ss rename 43 815 OS ss reset 43 816 ABCDEFGH _os_ss_reten 817 _os_ss_rfm 43 818 os ss sendsig 43 819 OS Ss size 43 820 os
569. tring h sbreniaq String comparison string h strepy String copy string h strcspn Get string length string h strerror Map error message string string h strftime Place formatted time in buffer time h strhcpy Copy old OS 9 for 68K strings strings h AA MICROWARE Table 1 22 String Handling Functions continued ANSI Function Standard Description Header File strlen Determine string length string h strncat String catenation string h strncmp String comparison string h strneopy t String copy string h strpbrk Locate first occurrence of string string h strrchr Locate last occurrence of string string h strspn Compute string length string h strstr Locate first occurrence of string string h strtod String to double conversion stdlib h strtok Break string into tokens string h strtol String to long conversion stdlib h strtoul String to unsigned long stdlib h conversion strxfrm Transform string string h Terminal Manipulation Functions Termcap Table 1 23 Termcap Functions ANSI Header Function Standard Description File tgetent Get termcap entries termcap tgetflag Check terminal capability termcap presence tgetnum Get terminal capability ID termcap tgetstr Get terminal capability termcap tgoto Get cursor movement capability termcap tputs Output capability string termcap Time Functions WX MIC ROWARE The TZ en
570. turns src Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 strtod String to Double Conversion Syntax include lt stdlib h gt double strtod const char begin char end Description strtod converts the initial portion of begin to double representation st rtod separates the input string attempts to convert the subject sequence to a floating point number and then returns the result begin is a pointer to the beginning of a string end is a pointer to the pointer to the first character after the converted string The input string is separated into three parts 1 Aninitial possibly empty sequence of white space characters as specified by isspace 2 A subject sequence resembling a floating point constant The subject sequence is the longest initial subsequence of the input string starting with the first non white space character having the expected form The subject sequence contains no characters if the input string is empty or consists entirely of white space or if the first non white space character is other than a sign a digit or a decimal point character 3 A final string of one or more unrecognized characters including the terminating null character of the input string strtod expects the subject sequence to have the following form e An optional plus or minus sign e Anon empty sequenc
571. type h toupper Convert character to uppercase ctype h File Positioning Functions The functions in Table 1 6 are provided for file positioning Table 1 6 File Positioning Functions Function Sed Description Header File Fgetpos Get current position in file stdio h Fseek Reposition file pointer stdio h Fsetpos Reposition file pointer stdio h telifi Get current position in file stdio h Table 1 6 File Positioning Functions continued ANSI Function Standard Description Header File _os_seek Reposition file pointer modes h rewind Return file pointer to zero stdio h GetStat SetStat Functions The standard library provides the Get Stat and Set Stat functions for determining and setting individual device parameters that are not uniform on all devices or that are highly hardware dependent Table 1 7 GetStat SetStat Functions ANSI Function iae Description Header File getstat Get file status sg_codes h _gs_devn Get device name sg_codes h gs eof Check for end of file sg_codes h _gs_gfd Get file descriptor sector none _gs_opt Get path options sg_codes h _gs_pos Get current file position sg_codes h gs rdyi Test for data available sg codes h _gs_size Get current file size sg_codes h AN MICROWARE Table 1 7 GetStat SetStat Functions continued ANSI Function Standard Description Header File _os_getstat Get file device status sg_codes h _o
572. uffer large enough to hold the event information Attributes Operating System OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library os lib l See Also FSEvent OS 9 for 68K Technical Manual os ev link Link to Existing Event by Name Syntax include lt events h gt finclude lt types h gt error code os ev link char name event id ev Id Description os ev link determines the ID number of an existing event To keep the use count synchronized properly you must perform an _os_ev_unlink call when the event is longer be used name is a pointer to the event name string ev idis a pointer to the location where os ev link stores the event identifier Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also os ev unlink FSEvent OS 9 for 68K Technical Manual F_EVENT OS 9 Technical Manual F_EVENT EV_LNK OS 9 Technical Manual F_EVENT EV_UNLNK OS 9 Technical Manual WX MICROWARE os ev pulse Signal Event Occurrence Syntax include lt events h gt finclude lt types h gt error code os ev pulse event id ev id int32 value u int32 actv flag Description oS ev pulse signals an event occurrence The event value is set to what is passed at the location value and the signal auto increment is not applied Then the os ev signal search ro
573. ufficient free memory is not available or a pointer to the allocated space Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also cealloect free os srqmem os9 srqmem realloc FSSRqMem OS 9 for 68K Technical Manual F SROMEM OS 9 Technical Manual mallocmin Set Minimum Allocation Size Syntax include lt stdlib h gt void _mallocmin unsigned size Description mallocmin sets the minimum amount of memory that allocation functions may request from the system size is the minimum allocation size in bytes size cannot be less than the system memory block size Size must be greater than or equal to the larger of the system memory block size or 4K If a smaller size is requested size is automatically set to the system memory block size Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library elabaL See Also calloct Lied Leet Lined Lee J lrealloc malloc realloc WX MICROWARE mblen Determine Number of Bytes in Multibyte Character Syntax include lt stdlib h gt int mblen const char Str size t num Description mblen determines the number of bytes contained in the multibyte character pointed to by str if str is a not a null pointer molen is similar to the following however
574. ument conforms to the construction rules for a pathname If name begins with the slash character then processes calling mq open with the same value of name shall refer to the same message queue object as long as that name has not been removed If name does not begin with the slash character the effect is implementation defined The interpretation of slash characters other than the leading slash character in name is implementation defined If the name argument is not the name of an existing message queue and creation is not requested mq open fails and returns an error The o 1ag argument requests the desired receive and or send access to the message queue The requested access permission to receive messages or send messages is granted if the calling process would be granted read or write access respectively to an equivalently protected file The value of o 1ag is the bitwise inclusive OR of values from the following list Applications shall specify exactly one of the first three values access modes below in the value of o 1ag O RDONLY Open the message queue for receiving messages The process can use the returned message queue descriptor with mq receive butnotmq send A O WRONLY O RDWR WX MICROWARE message queue may be open multiple times in the same or different processes for receiving messages Open the queue for sending messages The process can use the returned message queue descriptor with mq sen
575. unction call not the shell that executes the program Use the built in shell command chd to change the shell s data directory Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also bo amp echdit i I ChgDir OS 9 for 68K Technical Manual CHDIR OS 9Technical Manual chd Using OS 9 for 68K and Using OS 9 WX MIC ROWARE chmod Change File Access Permissions Syntax include lt modes h gt int chmod char name int perm Description chmod changes the access permission bits associated with a file name must be a pointer to a string containing a file name perm should contain the desired bit pattern for the file permissions Only the lower 16 bits of perm are used chmod returns zero after a successful call If the caller is not entitled to change the access permissions or if the file cannot be found 1 is returned and the appropriate error code is placed in the global variable errno Note Only the super user or the owner of the file may change the access permissions Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l See Also os ss attr I SetStt OS 9 for 68K Technical Manual I SETSTAT SS ATTR OS 9 Technical Manual attr Using OS 9 for 68K and Using OS 9 WX MICROWARE chown Change Ow
576. unction called as a result of a signal raised during the handling of another signal the behavior is undefined After Long jmp is completed program execution continues as if the corresponding call to set jmp had just returned the value specified by val long jmp cannot cause set jmp to return the value zero If val is zero set jmp returns the value 1 RE Ultra C Lib WARNING Do not call 1ongjmp before env is initialized by set jmp or if the function calling set jmp has already returned Attributes Operating System State Threads Re entrant Standards Library clib l See Also set jmp rary Reference OS 9 and OS 9 for 68K User and System Safe Yes ANSI WX MICROWARE _lrealloc Resize Block of Memory Low Overhead Syntax include lt stdlib h gt void _lrealloc void oldptr unsigned long newsize unsigned long oldsize Description lrealloc resizes a block of memory oldptr is a pointer to the memory block o1dpt r should be a value returned by a previous call to 1malloc 1calloc Or lrealloc newsize specifies the size to use for the memory block oldsize is the size of the old memory block _lrealloc returns a pointer to a new memory block of size newsize The pointer is aligned to store data of any type If newsize is smaller than o1dsize the contents of the old block are truncated and placed in the new block Otherwise al
577. unction checks for invalid input values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b isdigit c Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI wo co Cc Ultra C Library Reference Library ctype h See Also isalnum isalpha lTsencrrit isgraph islower isprinti E l8p rnet isspace isupper lexdigi 0 WX MICROWARE Ultra C Library Reference iseuc kana See If Parameter Is the First Byte of a Half Width Kaka Kana Character Syntax include lt ctype h gt int iseuc kana int c Description _iseuc_kana is a C macro that returns a non zero value if c is the first byte of a half width Kata Kana character Otherwise it returns zero The first byte of a half width Kata Kana character is OX8E c is the character to test Note This routine available as a function or a macro in ctype h does not operate well with values outside the range of an unsigned char The function checks for invalid input
578. ure 2 6 julian Output Date and Time Formats Time Seconds since midnight 0 86399 Date Julian Day Number If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno WX MICROWARE Note Be certain to pass pointers for date and time values Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library sys_clib 1 Example main int date time tick short day _sysdate 0 amp time amp date amp day amp tick _julian amp time date printf The Julian date is d Cinderella needs to be home in d seconds n date 86400 time See Also _sysdate OS 9 for 68K _os_gregorian OS 9 for 68K os julian OS 9 for 68K FSTime OS 9 for 68K Technical Manual FSJulian OS 9 for 68K Technical Manual F_TIME OS 9 Technical Manual kill Send Signal to Process Syntax include signal h int kill int pid int sigcode Description kill sends a signal to a process Both the sending and receiving process must have the same user number unless the sending process user number is that of the super user 0 pidis the process ID of the process to kill sigcode is the signal code to send Only the lower 16 bits of sigcode are used The value in sigcode is sent as a signal to the process specified by pid You can pass any value in sigcode The con
579. urns a pointer to the string The program cannot modify the array but a subsequent call to strerror overwrites the array Error messages are generally in the form major minor detail ma jor is the family of error minor is the error number within the family detail is the information from the system errmsg file if available The system errmsg file dd SYS errmsg hO SYS errmsg Or d0 SYS errmsg contains the error messages generated by perror Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib 1 See Also perror strftime Place Formatted Time in Buffer Syntax include lt time h gt size_t strftime char dest size_t maxsize const char format const struct tm timeptr Description strftime places characters into an array as controlled by format The format is a multibyte character sequence beginning and ending in its initial shift state dest is a pointer to the array into which to place the characters maxsize specifies the maximum number of characters to place in the array format is a pointer to a control string format consists of zero or more conversion specifiers and ordinary multibyte characters A conversion specifier consists of a percent sign followed by a character that determines the behavior of the conversion specifier timeptr is a pointer to a time structu
580. us signals signal h contains prototypes for the following functions intercept kill os clrsigs os intercept os rte os send _os_siglngj _os_sigmask _os_Sigreset _os_sigrs _os_sleep _os9_sleep pause raise sigmask signal sleep tsleep Contains definitions for stat and fstat support Used for advancing through a list of arguments of variable length and type stdarg h contains the macros for va arg va end va starti Used for common definitions ptrdiff t size_t and wchar_t and the following macro offsetof Indicates a standard ANSI header WX MICROWARE Table 1 2 Ultra C Header Files continued File Description stdio h t Used for performing input and output stdio h contains prototypes for the following functions _cleareof cleareof clearerr errmsg fclose fdopen feof ferror Fflush fgetc fgetpos fgets _fileno fileno Fopen Eprintt tfputce t fputs fread freopen fscanf fseek setpos Ftell fwrite getc getchar gets getw mktemp perror prerr printfi pute putsenart puts putw remove rename rewind scanf setbuf setvbuf sprintf sscanf tmpfile tmpnam ungetc vfprintf vprintf vsprintf Indicates a standard ANSI header Table 1 2 Ultra C Header Files continued File Description stdlib h t Used for t
581. utes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix 1 WX MICROWARE ceil Ceiling Function Syntax include lt math h gt double ceil double x Description ceil returns the smallest integer as a double that is not less than X Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library Glrba See Also floor chainc chain Load and Execute New Module Syntax finclude process h int chainc char modname int parmsize char parmptr int type int lang int datasize int prior LNE pathent int chain char modname int parmsize char parmptr int type int lang int datasize int prior Description chainc executes a new program without the overhead of creating a new process It is functionally similar to os9forkc followed by exit but with less system overhead chainc effectively resets the calling process program and data areas and begins executing a new primary module Open paths are not closed or otherwise affected modname is a pointer to a null terminated module name parmsize is generally strlen parmptr parmptr is a pointer to a null terminated string to be passed to the new module WX MICROWARE type and lang specify the desired type and language of the module values of zero i
582. utine is executed and the original event value is restored ev ididentifies the event The value to pulse the event to is passed at the location pointed to by value os ev pulse also stores the event value prior to the pulse at the location pointed to by value actv flag specifies which process es to activate e factv flagis one all processes in range are activated e If actv_flag is zero the first process in the event queue waiting for that range is activated Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l1 See Also OoS ev signal FSEvent F EVENT F EVENT EV PULSE F EVENT EV SIGNL OS 9 for 68K Technical Manual OS 9 Technical Manual OS 9 Technical Manual OS 9 Technical Manual WX MICROWARE os ev read Read Event Value Without Waiting Syntax include lt events h gt finclude lt types h gt error_code _os_ev_read event_id ev_id int32 value Description os ev read reads the value of an event without waiting for or affecting the event variable ev ididentifies the event value is a pointer to the location where os ev read stores the current event value Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library os lib l See Also FSEvent OS 9 for 68K Technical Manual F_EVENT OS 9 Technical Manual F_EVENT EV_
583. values that are not representable as an unsigned char and not equal to the value of the macro EOF and returns 0 for such input The macro does not check for invalid input which makes it faster than the function The macro is the default To use the function you must explicitly use the undef preprocessor directive or ensure that the macro expansion does not occur by placing the function name within parentheses For example b iseuc kana c Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes N Ultra C Library Reference 38 WX MICROWARE Library ctype h See Also isalnum isalpha TBEBEEL islower isprint ispunct isspace isupper isxdigit 0 388 Ultra C Library Reference _iseuct iseuc2 See If Parameter Is EUC Character Syntax include lt ctype h gt int _iseucl Description _iseucl1 is a C macro that returns a non zero value if C is the first byte of an EUC packed format JIS x 0208 1990 character Otherwise it returns zero The valid range is between 0xa1 and Oxfe _iseuc2 is the same thing for the second byte of the character and has the same valid range c is the character to test Note This routine available as a function or a macro in ctype h does not operate well with values outside the range of an unsigned char The function checks for invalid input
584. ventional code numbers are defined in the signal h header file If an error occurs 1 is returned and the appropriate error code is placed in the global variable errno Note The super user can send a signal to all processes running on the system if the pid is zero Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1 See Also os send FSSend F_SEND kill command WX MICROWARE OS 9 for 68K Technical Manual or OS 9 Technical Manual Using OS 9 for 68K or Using OS 9 labs Compute Absolute Value Syntax include lt stdlib h gt long int labs long int num Description labs returns the absolute value of num num and the returned value each have type long int num is the value to use Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib 1 See Also abs i WX MICROWARE _Icalloc Allocate Storage for Array Low Overhead Syntax include lt stdlib h gt void _lcalloc unsigned long nel unsigned long elsize Description _lcalloc allocates space for an array The allocated memory is cleared to zeroes nel specifies the number of elements in the array elsize specifies the size of each element _lcalloc calls 1malloc to allocate memory Ifthe allocation is successful 1calloc return
585. vironment variable is used to specify the time zone for the C functions to use TZ should have the following format zzz n ddd zzz is one of the supported time zone names listed in Table 1 24 Table 1 24 Time Zones and Descriptions Zone Description GMT UTC PST PI MST MI CST CI EST E YST AST EET CET WET JST MI T HST DT DT DT DT Greenwich Mean Time or Coordinated Universal Time USA Pacific Standard Time Daylight Savings Time USA Mountain Standard Time Daylight Savings Time USA Central Standard Time Daylight Savings Time USA Eastern Standard Time Daylight Savings Time Yukon Standard Time Most of Alaska Aleutian Hawaiian Standard Time Eastern European Time Central European Time Western European Time Japan Standard Time Midway Islands Time Hawaii Standard Time Table 1 24 Time Zones and Descriptions continued Zone Description PNT Phoenix Standard Time IET Indiana Eastern Standard Time PRT Puerto Rico Standard Time CNT Canada Newfoundland Time AGT Argentina Standard Time BEZ Brazillian Standard Time CAT Central Africa ECT European Central Time ART Arabic Standard Time EAT Eastern African Time MET Middle Eastern Time NET Near East Time PLT Pakistan Lahore Time IST India Standard Time BST Bangladesh Standard Time VST Vietnam Standard Time CTT China Taiwan Standard Time AN MICROWARE Table 1 24 Time Zones and Descrip
586. void _exit int status Description _exit immediately terminates a program status is the exit status The parent process can use status to determine the program s success or failure An exit status of zero is considered normal termination Most programs especially the she11 interpret a non zero value as an error code exit cannot return to its caller and it does not flush and close standard l O buffers Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library sys clib l1 See Also os exit FSExit OS 9 for 68K Technical Manual F EXIT OS 9 Technical Manual exit Task Termination Syntax include lt stdlib h gt void exit int status Description exit is the normal means of terminating a task All functions specified by atexit are called in the reverse order of the order in which they were specified All open streams with unwritten buffered data are flushed all open streams are closed and all files created by tmpfile are removed Control is returned to the host environment status is the exit status e f status is Zero or EXIT SUCCESS zero is communicated to the parent process executing the os wait If status is EXIT FAILURE one is communicated exit cannot return to its caller Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standa
587. wc is unaffected pwcs is a pointer to the array into which to store the converted values str is a pointer to the original sequence of multibyte characters num specifies the maximum number of elements to modify No more than num elements are modified in pwcs If copying takes place between overlapping objects the behavior is undefined If an invalid multibyte character is encountered mbstowc returns size t 1 Otherwise mbstowcs returns the number of array elements modified not including a terminating zero code if any mbstowcs is supported for both the C and JAPAN locales Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Standards ANSI Library clib l See Also wcstombs WX MICROWARE mbtowc Determine Number of Bytes in Multibyte Characters Syntax include lt stdlib h gt int mbtowc wchar t pwc const char mbchar size t maxnum Description mbtowc determines the number of bytes contained in the multibyte character pointed to by mbchar if mbchar is not a null pointer It then determines the code for the value of type wchar t that corresponds to that multibyte character The value of the code corresponding to the null character is zero If the multibyte character is valid and pwc is not a null pointer mbtowc stores the code in pwc At most maxnum bytes of mbchar are examined pwc is a pointer to the array in which
588. with a matching failure execution of the following directive if any is terminated with an input failure WX MICROWARE If conversion terminates on a conflicting input character the offending input character is left unread in the input stream Trailing white space including newline characters is left unread unless matched by a directive You must use the 2n directive to determine the success of literal matches and suppressed assignments fscanf returns EOF if an input failure occurs before any conversion Otherwise fscanf returns the number of input items assigned which can be fewer than provided for or zero in the event of an early matching failure For More Information The sclib 1and sclib il libraries contain a smaller version of the fscanf function Refer to the Using Ultra C C manual for more information about the small library functions Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Standards ANSI Library clib l See Also scanf sscanf etrtogi BETCEOLI strtonul fseek Reposition File Pointer Syntax include lt stdio h gt int fseek FILE stream long int Offset int place Description fseek sets the file position indicator for a stream stream is a pointer to the C I O FILE structure offset specifies an amount to offset the file position indicator place specifies where t
589. with the specified path number path specifies the path number type is a pointer to the location where os gs devtyp stores the device type class is a pointer to the location where os gs devtyp stores the device class Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l WX MICROWARE os gs diskfree Return Information About RBF Disk Free Space path totblocks blksize Syntax error code os gs diskfree path id u int32 u int32 u int32 u int32 Description avail contig _os_gs_diskfree returns information about RBF disk free space totblocks is set to the total number of blocks on the disk blksize is set to the size of blocks used on the disk 256 512 etc avail is set to the total number of free blocks on the disk contig is set to the number of blocks in the largest contiguous area Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l1 os gs dopt Read Device Path Options Syntax include sg codes h finclude lt types h gt error code os gs dopt path id path u int32 size void dopts Description os gs dopt copies the initial default device path options into your buffer These options are used for initializing new paths to the device path specifies the path number The size of the buffer is passed at the location p
590. y lmalloc and malloc are corrupted and programs behave unpredictably The low overhead functions require that you keep track of the sizes of allocated spaces in memory Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant No Library elabeaL See Also calloec free _freemin lcallog lmalloc lrealloc malloect os srtmem realloc WX MIC ROWARE Iftocr Convert Linefeed to Carriage Return Syntax include UNIX os9def h void lftocr char buf int n Description lftocr converts all linefeed characters to carriage return characters in buf for a span of n characters Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library unix l Imalloc Allocate Memory from Arena Low Overhead Syntax include lt stdlib h gt void _lmalloc unsigned long size Description lmalloc returns a pointer to a memory block The pointer is suitably aligned for storing data of any type size specifies the size of the memory block in bytes lmalloc maintains an amount of memory called an arena from which it grants memory requests 1malloc searches its arena for a block of free memory large enough for the request and in the process joins adjacent blocks of free space returned by either lfree or free If sufficie
591. y mem size specifies the additional memory size Attributes Operating System OS 9 State User and System Threads Safe Re entrant Yes Library os lib l1 os tranpn Translate User Path to System Path Syntax finclude lt io h gt finclude lt types h gt error code os tranpn process id proc id path id user path path id sys path Description os tranpn translates a user path number to a system path number proc id specifies the process ID user path specifies the user path to translate sys pathis a pointer to the location where os tranpn stores the mapped system path Attributes Operating System OS 9 State User Threads Safe Re entrant Yes Library os lib l WX MICROWARE os transadd Translate Memory Address Syntax finclude lt virtual h gt finclude lt types h gt error code os transadd u int32 size u int32 mode void blk addr void reserved Description Jos transadd translates an address to or from its external bus address The size of the block to translate is passed at the location pointed to by size os transadd also stores the size of the block translated at the location pointed to by size mode specifies the type of translation f mode is zero the local CPU address is translated to the external bus address e f mode is one the external bus address is translated to the local CPU address The address of the block to
592. y Only the lower 16 bits of perm are used mknod returns zero if the directory was successfully created If the creation failed 1 is returned and the appropriate error code is placed in the global variable errno Note mknod does not make UNIX style special files as there are no such files on OS 9 for 68K and OS 9 This is a historical function and is likely to be removed in a future release Use makdir in all new code Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib l See Also makdir os makdir TSMakDir I MAKDI R WX MIC ROWARE OS 9 for 68K Technical Manual OS 9 Technical Manual mktemp Create Unique File Name Syntax include lt stdio h gt char mktemp char name Description mktemp ensures that the name of a temporary file is unique in the system and does not clash with any other file name name is a pointer to the template string A pointer to a template string is passed to mktemp The template string should look like a filename with six trailing X s mkt emp replaces the x s with a letter and the current process ID The letter is chosen so that the resulting name does not conflict with an existing file mktemp returns a pointer to the file name or NULL if more than 26 mktemp files exist Attributes Operating System OS 9 and OS 9 for 68K State User and System
593. y available memory OS 9 There is a set limit Attributes Operating System OS 9 and OS 9 for 68K State User and System Threads Safe Re entrant Yes Library Sys clib 1l1 See Also os intercept os send _os_sigmask FSSigMask OS 9 for 68K Technical Manual F_SIGMASK OS 9 Technical Manual WX MICROWARE signal Specify Signal Handling Syntax include signal h void signal int sig void func int int Description signal chooses one of three ways in which receipt of the signal number sig is handled f func is SIG DFL default handling for that signal occurs f func is SIG IGN the signal is ignored Otherwise func is a pointer to a function to call when that signal occurs Such a function is called a signal handler When a signal occurs signals are masked and signal sig SIG_DFL is executed Then the specified type of handling is executed Signals are blocked for the duration of the signal handler unless the program takes some action that unmasks the signal Note A program will not receive an abort or quit signal from the keyboard usually c and E unless the program performs output to the terminal This is because the operating system sends the abort quit signals to the last process to perform I O to the terminal If you run the program from the shell and type E before the program performs I O to the terminal the shell receives the
594. y entry 313 module name 879 next character from file stdin 303 ownership of resource lock 502 parameter in variable parameter list 1070 path options 350 pointer to I O process descriptor 541 643 process descriptor copy 320 651 process ID 675 677 process table entry 322 processor time 171 size of SCSI devices 660 stack used 994 status 648 string from file 248 length 1003 system date 638 640 global variables 336 ABCDEFGHIJKLMNOPQRSTUVWXYZ I O device list head pointer 637 time 312 638 640 Termcap entry 1043 terminal capability 1047 terminal capability ID 1046 user ID 338 675 677 value for environment name 307 value of registers 292 word from I O address 369 get file status fstat 288 stat 995 get_const 305 get_current_tss 89 306 get_excpt_base 89 310 get gdtr 89 311 get static 65 335 getc 47 303 getchar 303 getenv 35 101 307 getgid 309 getime 87 105 312 getnextpwnam 314 getopt 315 getpid 76 105 318 getppid 319 getpw 323 getpwent 324 getpwnam 327 getpwuid 329 gets 48 331 GetStat gs devn 39 344 39 346 gs gfd 39 348 39 350 gs rdy 39 353 gs size 39 355 OS getstat 40 648 OS getsys 40 649 ABCDEFGHIJKLMNOPQRSTUVWXYZ os gs cpypd 40 654 OS gs cstats 40 655 os gs devnm 40 656 os gs devtyp 40 657 os gs dopt 40 659 OS gs dsize 40 660 os gs edt 40 661 os gs eof 40 662 os gs fd 40 663 os gs fdaddr
595. yte count to copy Attributes Operating System OS 9 and OS 9 for 68K State System Threads Safe Re entrant Yes Library os_lib l WX MICROWARE os nproc Start Next Process Syntax finclude lt process h gt include lt types h gt error code _os_nproc void Description _os_nproc removes the next process from the active process queue and initiates its execution os nproc does not return to the caller Note The process calling os nproc should already be in one of the system s process queues If not the process becomes unknown to the system This occurs even though the process descriptor still exists and is printed out by a procs command Attributes Operating System OS 9 and OS 9 for 68K State System Threads Safe Re entrant Yes Library os lib l See Also Ds Aaproci Mies CY ihran Baferanea Ultra UG Library neterence os open Open Path to File or Device Syntax include lt modes h gt finclude lt types h gt error_code _os_open const char name u_int32 mode path_id path Description _os_open opens a path to an existing file or device as specified by the pathlist _os_open returns a path number which is used in subsequent service requests to identify the path If the file does not exist an error is returned name is a pointer to the path name of the existing file or device mode specifies which subsequent read and or write opera

Ultra C Library Reference

Contents

Download Pdf Manuals

Related Search

Related Contents