# To unbundle, run this file echo access.2 sed 's/.//' >access.2 <<'//GO.SYSIN DD access.2' -.TH ACCESS 2 -.SH NAME -access \- determine accessibility of file -.SH SYNOPSIS -.B access(name, mode) -.br -.B char *name; -.SH DESCRIPTION -.I Access -checks the given -file -.I name -for accessibility according to -.I mode, -which is 4 (read), 2 (write) or 1 (execute) or a combination thereof. -Specifying mode 0 -tests whether the directories leading to the file can be -searched and the file exists. -.PP -An appropriate error indication is returned if -.I name -cannot be found or if any -of the desired access modes would not be granted. -On disallowed accesses -\-1 is returned and the error code is in -.IR errno . -0 is returned from successful tests. -.PP -The user and group IDs with respect to which permission is checked -are the real UID and GID of the process, so this call is -useful to set-UID programs. -.PP -Notice that it is only access bits that are checked. -A directory may be announced as writable by -.I access, -but an attempt to open it for writing will fail -(although files may be created there); -a file may look executable, but -.I exec -will fail unless it is in proper format. -.PP -.SH SEE ALSO -stat(2) -.SH ASSEMBLER -(access = 33.) -.br -.B sys access; name; mode //GO.SYSIN DD access.2 echo acct.2 sed 's/.//' >acct.2 <<'//GO.SYSIN DD acct.2' -.TH ACCT 2 -.SH NAME -acct \- turn accounting on or off -.SH SYNOPSIS -.B acct(file) -.br -.B char *file; -.SH DESCRIPTION -The system is prepared to write a record -in an accounting -.I file -for each process as it terminates. -This -call, with a null-terminated string naming an existing file -as argument, turns on accounting; -records for each terminating process are appended to -.IR file . -An argument of 0 causes accounting to be turned off. -.PP -The accounting file format is given in -.IR acct (5). -.SH "SEE ALSO" -acct(5), sa(1) -.SH DIAGNOSTICS -On error \-1 is returned. -The file must exist and the call may be exercised only by the super-user. -It is erroneous to try to turn on accounting when it is already on. -.SH BUGS -No accounting is produced for programs running -when a crash occurs. -In particular nonterminating programs are never -accounted for. -.SH ASSEMBLER -(acct = 51.) -.br -.B sys acct; file //GO.SYSIN DD acct.2 echo alarm.2 sed 's/.//' >alarm.2 <<'//GO.SYSIN DD alarm.2' -.TH ALARM 2 -.SH NAME -alarm \- schedule signal after specified time -.SH SYNOPSIS -.B alarm(seconds) -.br -.B unsigned seconds; -.SH DESCRIPTION -.I Alarm -causes signal SIGALRM, see -.IR signal (2), -to be sent to the invoking process -in a number of seconds given by the argument. -Unless caught or ignored, the signal terminates the process. -.PP -Alarm requests are not stacked; -successive calls reset the alarm clock. -If the argument is 0, any alarm request is cancelled. -Because the clock has a 1-second resolution, -the signal may occur up to one second early; -because of scheduling delays, -resumption of execution of when the signal is -caught may be delayed an arbitrary amount. -The longest specifiable delay time is 65535 seconds. -.PP -The return value is the amount of time -previously remaining in the alarm clock. -.SH "SEE ALSO" -pause(2), signal(2), sleep(3) -.SH ASSEMBLER -(alarm = 27.) -.br -(seconds in r0) -.br -.B sys alarm -.br -(previous amount in r0) //GO.SYSIN DD alarm.2 echo brk.2 sed 's/.//' >brk.2 <<'//GO.SYSIN DD brk.2' -.TH BRK 2 -.SH NAME -brk, sbrk, break \- change core allocation -.SH SYNOPSIS -.B char *brk(addr) -.PP -.B char *sbrk(incr) -.SH DESCRIPTION -.I Brk -sets the system's idea of the lowest location not used by the program -(called the break) -to -.I addr -(rounded up to the next multiple of 64 bytes -on the PDP11, 256 bytes on the Interdata 8/32, 512 bytes on the VAX-11/780). -Locations not less than -.I addr -and below the stack pointer -are not in the address space and will thus -cause a memory violation if accessed. -.PP -In the alternate function -.I sbrk, -.I incr -more bytes are added to the -program's data space and a pointer to the -start of the new area is returned. -.PP -When a program begins execution via -.I exec -the break is set at the -highest location defined by the program -and data storage areas. -Ordinarily, therefore, only programs with growing -data areas need to use -.IR break . -.SH "SEE ALSO" -exec(2), -malloc(3), -end(3) -.SH DIAGNOSTICS -Zero is returned if the break could be set; -\-1 if the program requests more -memory than the system limit -or if too many segmentation -registers would be required to implement the break. -.SH BUGS -Setting the break in the range -0177701 to 0177777 (on the PDP11) is the same as setting it to zero. -.SH ASSEMBLER -(break = 17.) -.br -.B sys break; addr -.PP -.I Break -performs the function of -.IR brk . -The name of the routine differs from that in C -for historical reasons. //GO.SYSIN DD brk.2 echo chdir.2 sed 's/.//' >chdir.2 <<'//GO.SYSIN DD chdir.2' -.TH "CHDIR" 2 -.SH NAME -chdir, chroot \- change default directory -.SH SYNOPSIS -.B chdir(dirname) -.br -.B char *dirname; -.PP -.B chroot(dirname) -.br -.B char *dirname; -.SH DESCRIPTION -.I Dirname -is the address of the pathname of a directory, terminated by a null byte. -.I Chdir -causes this directory -to become the current working directory, -the starting point for path names not beginning with `/'. -.PP -.I Chroot -sets the root directory, the -starting point for path names beginning with `/'. -The call is restricted to the super-user. -.SH "SEE ALSO" -cd(1) -.SH DIAGNOSTICS -Zero is returned if the directory is changed; \-1 -is returned -if the given name is not that of a directory -or is not searchable. -.SH ASSEMBLER -(chdir = 12.) -.br -.B sys chdir; dirname -.PP -(chroot = 61.) -.br -.B sys chroot; dirname //GO.SYSIN DD chdir.2 echo chmod.2 sed 's/.//' >chmod.2 <<'//GO.SYSIN DD chmod.2' -.TH CHMOD 2 -.SH NAME -chmod \- change mode of file -.SH SYNOPSIS -.B chmod(name, mode) -.br -.B char *name; -.SH DESCRIPTION -The file whose name -is given as the null-terminated string pointed to by -.I name -has its mode changed to -.IR mode . -Modes are constructed by ORing together some -combination of the following: -.PP -.RS - 04000 set user ID on execution - 02000 set group ID on execution - 01000 save text image after execution - 00400 read by owner - 00200 write by owner - 00100 execute (search on directory) by owner - 00070 read, write, execute (search) by group - 00007 read, write, execute (search) by others -.RE -.PP -If an executable file is set up for sharing -(\fB\-n\fR or \fB\-i\fR option of -.IR ld (1)) -then mode 1000 prevents the system from -abandoning the swap-space image of the program-text portion -of the file when its last user -terminates. -Thus when the next user of the file executes it, -the text need not be read from the file -system but can simply be swapped in, -saving time. -Ability to set this bit is restricted to the super-user -since swap space is consumed -by the images; it is only worth while for heavily used commands. -.PP -Only the owner of a file (or the super-user) may change the mode. -Only the super-user can set the 1000 mode. -.SH "SEE ALSO" -chmod(1) -.SH DIAGNOSTIC -Zero is returned if the mode is changed; -\-1 is returned if -.I name -cannot be found or if current user -is neither the owner of the file nor the super-user. -.SH ASSEMBLER -(chmod = 15.) -.br -.B sys chmod; name; mode //GO.SYSIN DD chmod.2 echo chown.2 sed 's/.//' >chown.2 <<'//GO.SYSIN DD chown.2' -.TH CHOWN 2 -.SH NAME -chown \- change owner and group of a file -.SH SYNOPSIS -.B chown(name, owner, group) -.br -.B char *name; -.SH DESCRIPTION -The file -whose name is given by the null-terminated string pointed -to by -.I name -has its -.I owner -and -.I group -changed as specified. -Only the super-user may -execute this call, -because if users were able to give files away, -they could defeat the (nonexistent) -file-space accounting procedures. -.SH "SEE ALSO" -chown(1), passwd(5) -.SH DIAGNOSTICS -Zero is returned if the owner is changed; -\-1 is returned -on illegal owner changes. -.SH ASSEMBLER -(chown = 16.) -.br -.B sys chown; name; owner; group //GO.SYSIN DD chown.2 echo close.2 sed 's/.//' >close.2 <<'//GO.SYSIN DD close.2' -.TH CLOSE 2 -.SH NAME -close \- close a file -.SH SYNOPSIS -.B close(fildes) -.PP -.SH DESCRIPTION -Given -a file descriptor such as returned from an -.I open, -.I creat, -.I dup -or -.IR pipe (2) -call, -.I close -closes the associated file. -A close of all files is automatic on -.I exit, -but since -there is a limit on the number of open files per process, -.I close -is necessary for programs which deal with many files. -.PP -Files are closed upon termination of a process, and -certain file descriptors may be closed by -.IR exec (2) -(see -.IR ioctl (2)). -.SH "SEE ALSO" -creat(2), open(2), pipe(2), exec(2), ioctl(2) -.SH DIAGNOSTICS -Zero is returned if a file is closed; -\-1 is returned for an unknown file descriptor. -.SH ASSEMBLER -(close = 6.) -.br -(file descriptor in r0) -.br -.B sys close -.PP //GO.SYSIN DD close.2 echo creat.2 sed 's/.//' >creat.2 <<'//GO.SYSIN DD creat.2' -.TH CREAT 2 -.SH NAME -creat \- create a new file -.SH SYNOPSIS -.B creat(name, mode) -.br -.B char *name; -.SH DESCRIPTION -.I Creat -creates a new file or prepares to rewrite an existing -file called -.I name, -given as the address of a null-terminated string. -If the file did not exist, it is given -mode -.IR mode , -as modified by the process's mode mask (see -.IR umask (2)). -Also see -.IR chmod (2) -for the -construction of the -.I mode -argument. -.PP -If the file did exist, its mode and owner remain unchanged -but it is truncated to 0 length. -.PP -The file is also opened for writing, and its file descriptor -is returned. -.PP -The -.I mode -given is arbitrary; it need not allow -writing. -This feature is used by programs which deal with temporary -files of fixed names. -The creation is done with -a mode that forbids writing. -Then if a second -instance of the program attempts a -.I creat, -an error is -returned and the program knows that the name is unusable -for the moment. -.SH "SEE ALSO" -write(2), close(2), chmod(2), umask (2) -.SH DIAGNOSTICS -The value \-1 is returned if: -a needed directory is not searchable; -the file does not exist and the directory -in which it is to be created is not writable; the file -does exist and is unwritable; -the file is a directory; -there are already too many files open. -.SH ASSEMBLER -(creat = 8.) -.br -.B sys creat; name; mode -.br -(file descriptor in r0) //GO.SYSIN DD creat.2 echo dup.2 sed 's/.//' >dup.2 <<'//GO.SYSIN DD dup.2' -.TH DUP 2 -.SH NAME -dup, dup2 \- duplicate an open file descriptor -.SH SYNOPSIS -.B dup(fildes) -.br -.B int fildes; -.PP -.B dup2(fildes, fildes2) -.br -.B int fildes, fildes2; -.SH DESCRIPTION -Given -a file descriptor returned from -an -.I open, -.I pipe, -or -.I creat -call, -.I dup -allocates another file descriptor -synonymous -with -the original. -The new file descriptor is returned. -.PP -In the second form of the call, -.I fildes -is a file descriptor referring to an open file, and -.I fildes2 -is a non-negative integer less than the maximum value -allowed for file descriptors (approximately 19). -.I Dup2 -causes -.I fildes2 -to refer to the same file as -.I fildes. -If -.I fildes2 -already referred to an open file, it is closed first. -.SH "SEE ALSO" -creat(2), open(2), close(2), pipe(2) -.SH DIAGNOSTICS -The value \-1 is returned if: -the given file descriptor is invalid; -there are already too many open files. -.SH ASSEMBLER -(dup = 41.) -.br -(file descriptor in r0) -.br -(new file descriptor in r1) -.br -.B sys dup -.br -(file descriptor in r0) -.PP -The -.I dup2 -entry is implemented by adding 0100 to -.I fildes. //GO.SYSIN DD dup.2 echo exec.2 sed 's/.//' >exec.2 <<'//GO.SYSIN DD exec.2' -.TH EXEC 2 -.SH NAME -execl, execv, execle, execve, execlp, execvp, exec, exece, environ \- execute a file -.SH SYNOPSIS -.B execl(name, arg0, arg1, ..., argn, 0) -.br -.B char *name, *arg0, *arg1, ..., *argn; -.PP -.B execv(name, argv) -.br -.B char *name, *argv[ ]; -.PP -.B "execle(name, arg0, arg1, ..., argn, 0, envp) -.br -.B "char *name, *arg0, *arg1, ..., *argn, *envp[ ]; -.PP -.B execve(name, argv, envp); -.br -.B char *name, *argv[ ], *envp[ ]; -.PP -.B extern char **environ; -.SH DESCRIPTION -.I Exec -in all its forms -overlays the calling process with the named file, then -transfers to the -entry point of the core image of the file. -There can be no return from a successful exec; the calling -core image is lost. -.PP -Files remain open across -.I exec -unless explicit arrangement has been made; -see -.IR ioctl (2). -Ignored signals remain ignored across -these calls, but -signals that are caught (see -.IR signal (2)) -are reset -to their default values. -.PP -Each user has a -.I real -user ID and group ID and an -.I effective -user ID and group ID. -The -real -ID -identifies the person using the system; -the -effective -ID -determines his access privileges. -.I Exec -changes the effective user and group ID to -the owner of the executed file if the file has the `set-user-ID' -or `set-group-ID' -modes. -The -real -user ID is not affected. -.PP -The -.I name -argument -is a pointer to the name of the file -to be executed. -The pointers -.IR arg [ 0 ], -.IR arg [ 1 "] ..." -address null-terminated strings. -Conventionally -.IR arg [ 0 ] -is the name of the -file. -.PP -From C, two interfaces are available. -.I Execl -is useful when a known file with known arguments is -being called; -the arguments to -.I execl -are the character strings -constituting the file and the arguments; -the first argument is conventionally -the same as the file name (or its last component). -A 0 argument must end the argument list. -.PP -The -.I execv -version is useful when the number of arguments is unknown -in advance; -the arguments to -.I execv -are the name of the file to be -executed and a vector of strings containing -the arguments. -The last argument string must be followed -by a 0 pointer. -.PP -When a C program is executed, -it is called as follows: -.PP - main(argc, argv, envp) -.br - int argc; -.br - char **argv, **envp; -.PP -where -.IR argc "" -is the argument count -and -.IR argv "" -is an array of character pointers -to the arguments themselves. -As indicated, -.IR argc "" -is conventionally at least one -and the first member of the array points to a -string containing the name of the file. -.PP -.I Argv -is directly usable in another -.I execv -because -.IR argv [ argc ] -is 0. -.PP -.I Envp -is a pointer to an array of strings that constitute -the -.I environment -of the process. -Each string consists of a name, an ``='', and a null-terminated value. -The array of pointers is terminated by a null pointer. -The shell -.IR sh (1) -passes an environment entry for each global shell variable -defined when the program is called. -See -.IR environ (5) -for some conventionally -used names. -The C run-time start-off routine places a copy of -.I envp -in the global cell -.I environ, -which is used -by -.IR execv \ and \ execl -to pass the environment to any subprograms executed by the -current program. -The -.I exec -routines use lower-level routines as follows -to pass an environment explicitly: -.RS -.nf -execle(file, arg0, arg1, . . . , argn, 0, environ); -execve(file, argv, environ); -.fi -.RE -.PP -.I Execlp -and -.I execvp -are called with the same arguments as -.I execl -and -.I execv, -but duplicate the shell's actions in searching for an executable -file in a list of directories. -The directory list is obtained from the environment. -.SH FILES -.ta \w'/bin/sh 'u -/bin/sh shell, invoked if command file found -by -.I execlp -or -.I execvp -.SH "SEE ALSO" -fork(2), environ(5) -.SH DIAGNOSTICS -If the file cannot be found, -if it is not executable, -if it does not start with a valid magic number (see -.IR a.out (5)), -if maximum memory is exceeded, -or if the arguments require too much space, -a return -constitutes the diagnostic; -the return value is \-1. -Even for the super-user, -at least one of the execute-permission bits must be set for -a file to be executed. -.SH BUGS -If -.I execvp -is called to execute a file that turns out to be a shell -command file, -and if it is impossible to execute the shell, -the values of -.I argv[0] -and -.I argv[\-1] -will be modified before return. -.SH ASSEMBLER -.DT -(exec = 11.) -.br -.B sys exec; name; argv -.PP -(exece = 59.) -.br -.B sys exece; name; argv; envp -.PP -Plain -.I exec -is obsoleted by -.I exece, -but remains for historical reasons. -.PP -When the called file starts execution on the PDP11, -the stack pointer points to a word containing the number of arguments. -Just above -this number is a list of pointers to the argument strings, -followed by a null pointer, followed by the pointers to -the environment strings and then another null pointer. -The strings themselves follow; -a 0 word is left at the very top of memory. -.PP - sp\(-> nargs -.br - arg0 -.br - ... -.br - argn -.br - 0 -.br - env0 -.br - ... -.br - envm -.br - 0 -.PP - arg0: -.br - ... -.br - env0: -.br - 0 -.PP -On the Interdata 8/32, -the stack begins at a conventional place -(currently 0xD0000) -and grows upwards. -After -.I exec, -the layout of data on the stack is as follows. -.PP -.nf - int 0 - arg0: byte ... - ... -argp0: int arg0 - ... - int 0 -envp0: int env0 - ... - int 0 - %2\(-> space 40 - int nargs - int argp0 - int envp0 - %3\(-> -.fi -.PP -This arrangement happens to conform well to C calling conventions. //GO.SYSIN DD exec.2 echo exit.2 sed 's/.//' >exit.2 <<'//GO.SYSIN DD exit.2' -.TH EXIT 2 -.SH NAME -exit \- terminate process -.SH SYNOPSIS -.B exit(status) -.br -.B int status; -.PP -.B _exit(status) -.br -.B int status; -.SH DESCRIPTION -.I Exit -is the normal means of terminating a process. -.I Exit -closes all the process's files and notifies the parent process -if it is executing a -.IR wait . -The low-order 8 bits of -.I status -are available to the parent process. -.PP -This call can never return. -.PP -The C function -.I exit -may cause cleanup actions before the -final `sys exit'. -The function -.I _exit -circumvents all cleanup. -.SH "SEE ALSO" -wait(2) -.SH ASSEMBLER -(exit = 1.) -.br -(status in r0) -.br -.B sys exit //GO.SYSIN DD exit.2 echo fork.2 sed 's/.//' >fork.2 <<'//GO.SYSIN DD fork.2' -.TH FORK 2 -.SH NAME -fork \- spawn new process -.SH SYNOPSIS -.B fork( ) -.SH DESCRIPTION -.I Fork -is the only way new processes are created. -The new process's core image is a copy of -that of the caller of -.IR fork . -The only distinction -is the fact -that the value returned in the old (parent) process -contains the process ID -of the new (child) process, -while the value returned in the child is 0. -Process ID's range from 1 to 30,000. -This process ID is used by -.IR wait (2). -.PP -Files open before the fork -are shared, and have a common read-write pointer. -In particular, -this is the way that standard input and output -files are passed and also how -pipes are set up. -.SH "SEE ALSO" -wait(2), exec(2) -.SH DIAGNOSTICS -Returns \-1 and fails to create a process if: -there is inadequate swap space, -the user is not super-user and has too many processes, -or the system's process table is full. -Only the super-user can take the last process-table slot. -.SH ASSEMBLER -(fork = 2.) -.br -.B sys fork -.br -(new process return) -.br -(old process return, new process ID in r0) -.PP -The return locations in the old and new process -differ by one word. -The C-bit is set in the old process if a new -process could not be created. //GO.SYSIN DD fork.2 echo getpid.2 sed 's/.//' >getpid.2 <<'//GO.SYSIN DD getpid.2' -.TH GETPID 2 -.SH NAME -getpid \- get process identification -.SH SYNOPSIS -.B getpid( ) -.SH DESCRIPTION -.I Getpid -returns -the process ID of -the current process. -Most often it is used to generate -uniquely-named -temporary files. -.SH "SEE ALSO" -mktemp(3) -.SH ASSEMBLER -(getpid = 20.) -.br -.B sys getpid -.br -(pid in r0) //GO.SYSIN DD getpid.2 echo getuid.2 sed 's/.//' >getuid.2 <<'//GO.SYSIN DD getuid.2' -.TH GETUID 2 -.SH NAME -getuid, getgid, geteuid, getegid \- get user and group identity -.SH SYNOPSIS -.B getuid( ) -.PP -.B geteuid( ) -.PP -.B getgid( ) -.PP -.B getegid( ) -.SH DESCRIPTION -.I Getuid -returns the real user ID of the current process, -.I geteuid -the effective user ID. -The real user ID identifies the person who is logged in, -in contradistinction to the effective user ID, which -determines his access permission at the moment. -It is thus useful to programs which operate using -the `set user ID' mode, to find out who invoked them. -.PP -.I Getgid -returns the real group ID, -.I getegid -the effective group ID. -.SH "SEE ALSO" -setuid(2) -.SH ASSEMBLER -(getuid = 24.) -.br -.B sys getuid -.br -(real user ID in r0, effective user ID in r1) -.PP -(getgid = 47.) -.br -.B sys getgid -.br -(real group ID in r0, effective group ID in r1) //GO.SYSIN DD getuid.2 echo indir.2 sed 's/.//' >indir.2 <<'//GO.SYSIN DD indir.2' -.TH INDIR 2 -.SH NAME -indir \- indirect system call -.SH ASSEMBLER -(indir = 0.) -.br -.B sys indir; call -.PP -The system call at the location -.I call -is executed. -Execution resumes after the -.I indir -call. -.PP -The main purpose of -.I indir -is to allow a program to -store arguments in system calls and execute them -out of line in the data segment. -This preserves the purity of the text segment. -.PP -If -.I indir -is executed indirectly, -it is a no-op. -If the instruction at the indirect -location is not a system call, -.I indir -returns error code EINVAL; -see -.IR intro (2). //GO.SYSIN DD indir.2 echo intro.2 sed 's/.//' >intro.2 <<'//GO.SYSIN DD intro.2' -.TH INTRO 2 -.de en -.HP -\\$1 \\$2 \\$3 -.br -.. -.SH NAME -intro, errno \- introduction to system calls and error numbers -.SH SYNOPSIS -.B #include -.SH DESCRIPTION -Section 2 of this manual -lists all the entries into the system. -Most of these calls have an error return. -.pg -An error condition is indicated by an otherwise -impossible returned value. -Almost always this is \(mi1; -the individual sections specify the details. -An error number is also made available -in the external variable -.IR errno . -.I Errno -is not cleared on successful calls, so it should be tested only -after an error has occurred. -.PP -There is a table of messages -associated with each error, and a routine for printing the -message; -See -.IR perror (3). -The possible error numbers -are not recited with each writeup in section 2, since many -errors are possible for most of the calls. -Here is a list of the error numbers, -their names as defined in , -and the messages available using -.IR perror . -.en 0 \h'\w'EIO'u' "Error 0 -Unused. -.en 1 EPERM "Not owner -Typically this error indicates -an attempt to modify a file in some way forbidden -except to its owner or super-user. -It is also returned for attempts -by ordinary users to do things -allowed only to the super-user. -.en 2 ENOENT "No such file or directory -This error occurs when a file name is specified -and the file should exist but doesn't, or when one -of the directories in a path name does not exist. -.en 3 ESRCH "No such process -The process whose number was given to -.I signal -and -.I ptrace -does not exist, or is already dead. -.en 4 EINTR "Interrupted system call -An asynchronous signal (such as interrupt or quit), -which the user has elected to catch, -occurred during a system call. -If execution is resumed -after processing the signal, -it will appear as if the interrupted system call -returned this error condition. -.en 5 EIO "I/O error -Some physical I/O error occurred during a -.I read -or -.IR write . -This error may in some cases occur -on a call following the one to which it actually applies. -.en 6 ENXIO "No such device or address -I/O on a special file refers to a subdevice that does not -exist, -or beyond the limits of the device. -It may also occur when, for example, a tape drive -is not dialled in or no disk pack is loaded on a drive. -.en 7 E2BIG "Arg list too long -An argument list longer than 5120 bytes -is presented to -.IR exec . -.en 8 ENOEXEC "Exec format error -A request is made to execute a file -which, although it has the appropriate permissions, -does not start with a valid magic number, see -.IR a.out (5). -.en 9 EBADF "Bad file number -Either a file descriptor refers to no -open file, -or a read (resp. write) request is made to -a file that is open only for writing (resp. reading). -.en 10 ECHILD "No children -.I Wait -and the process has no -living or unwaited-for children. -.en 11 EAGAIN "No more processes -In a -.I fork, -the system's process table is full -or the user is not allowed to create any more -processes. -.en 12 ENOMEM "Not enough core -During an -.I exec -or -.I break, -a program asks for more core than the system is able to supply. -This is not a temporary condition; the maximum core size -is a system parameter. -The error may also occur if the arrangement -of text, data, and stack segments -requires too many segmentation registers. -.en 13 EACCES "Permission denied -An attempt was made to access a file in a way forbidden -by the protection system. -.en 14 EFAULT "Bad address -The system encountered a hardware fault in attempting to -access the arguments of a system call. -.en 15 ENOTBLK "Block device required -A plain file was mentioned where a block device was required, -e.g. in -.IR mount . -.en 16 EBUSY "Mount device busy -An attempt to mount a device that was already mounted or -an attempt was made to dismount a device -on which there is an active file -(open file, current directory, mounted-on file, active text segment). -.en 17 EEXIST "File exists -An existing file was mentioned in an inappropriate context, -e.g. -.IR link . -.en 18 EXDEV "Cross-device link -A link to a file on another device -was attempted. -.en 19 ENODEV "No such device -An attempt was made to apply an inappropriate -system call to a device; -e.g. read a write-only device. -.en 20 ENOTDIR "Not a directory -A non-directory was specified where a directory -is required, -for example in a path name or -as an argument to -.IR chdir . -.en 21 EISDIR "Is a directory -An attempt to write on a directory. -.en 22 EINVAL "Invalid argument -Some invalid argument: -dismounting a non-mounted -device, -mentioning an unknown signal in -.I signal, -reading or writing a file for which -.I seek -has generated a negative pointer. -Also set by math functions, see -.IR intro (3). -.en 23 ENFILE "File table overflow -The system's table of open files is full, -and temporarily no more -.I opens -can be accepted. -.en 24 EMFILE "Too many open files -Customary configuration limit is 20 per process. -.en 25 ENOTTY "Not a typewriter -The file mentioned in -.I stty -or -.I gtty -is not a terminal or one of the other -devices to which these calls apply. -.en 26 ETXTBSY "Text file busy -An attempt to execute a pure-procedure -program that is currently open for writing -(or reading!). -Also an attempt to open for writing a pure-procedure -program that is being executed. -.en 27 EFBIG "File too large -The size of a file exceeded the maximum (about -.if t 10\u\s-29\s+2\d -.if n 1.0E9 -bytes). -.en 28 ENOSPC "No space left on device -During a -.I write -to an ordinary file, -there is no free space left on the device. -.en 29 ESPIPE "Illegal seek -An -.I lseek -was issued to a pipe. -This error should also be issued for -other non-seekable devices. -.en 30 EROFS "Read-only file system -An attempt to modify a file or directory -was made -on a device mounted read-only. -.en 31 EMLINK "Too many links -An attempt to make more than 32767 links to a file. -.en 32 EPIPE "Broken pipe -A write on a pipe for which there is no process -to read the data. -This condition normally generates a signal; -the error is returned if the signal is ignored. -.en 33 EDOM "Math argument -The argument of a function in the math package (3M) -is out of the domain of the function. -.en 34 ERANGE "Result too large -The value of a function in the math package (3M) -is unrepresentable within machine precision. -.SH SEE ALSO -intro(3) -.SH ASSEMBLER -.B as /usr/include/sys.s file ... -.PP -The PDP11 assembly language interface is given for each -system call. -The assembler symbols are defined in `/usr/include/sys.s'. -.PP -Return values appear in registers r0 and r1; -it is unwise to count on these registers being preserved -when no value is expected. -An erroneous call is always -indicated by turning on the c-bit of the condition codes. -The error number is returned in r0. -The presence of an error is most easily tested -by the instructions -.I bes -and -.I bec -(`branch on error set (or clear)'). -These are synonyms for -the -.I bcs -and -.I bcc -instructions. -.PP -On the Interdata 8/32, the system call arguments -correspond well to the arguments of the C routines. -The sequence is: -.IP -.nf -la %2,errno -l %0,&callno -svc 0,args -.fi -.PP -Thus register 2 points to a word into which the error number will be -stored as needed; it is cleared if no error occurs. -Register 0 contains the system call number; the nomenclature -is identical to that on the PDP11. -The argument of the -.I svc -is the address of the arguments, laid out in storage -as in the C calling sequence. -The return value is in register 2 (possibly 3 also, as in -.IR pipe ) -and is \-1 in case of error. -The overflow bit in the program status word is also -set when errors occur. //GO.SYSIN DD intro.2 echo ioctl.2 sed 's/.//' >ioctl.2 <<'//GO.SYSIN DD ioctl.2' -.TH IOCTL 2 -.SH NAME -ioctl, stty, gtty \- control device -.SH SYNOPSIS -.B #include -.PP -.B ioctl(fildes, request, argp) -.br -.B struct sgttyb *argp; -.PP -.B stty(fildes, argp) -.br -.B struct sgttyb *argp; -.PP -.B gtty(fildes, argp) -.br -.B struct sgttyb *argp; -.SH DESCRIPTION -.I Ioctl -performs a variety of functions -on character special files (devices). -The writeups of various devices -in section 4 discuss how -.I ioctl -applies to them. -.PP -For certain status setting and status inquiries -about terminal devices, the functions -.I stty -and -.I gtty -are equivalent to -.RS -.B ioctl(fildes, TIOCSETP, argp) -.br -.B ioctl(fildes, TIOCGETP, argp) -.RE -.LP -respectively; see -.IR tty (4). -.PP -The following two calls, however, apply to any open file: -.PP -.RS -.B ioctl(fildes, FIOCLEX, NULL); -.br -.B ioctl(fildes, FIONCLEX, NULL); -.RE -.LP -The first causes the file to be closed automatically during -a successful -.I exec -operation; -the second reverses the effect of the first. -.SH "SEE ALSO" -stty(1), tty(4), exec(2) -.SH DIAGNOSTICS -Zero is returned if the call was successful; -\-1 if the file descriptor does not refer to -the kind of file for which it was intended. -.SH BUGS -Strictly speaking, -since -.I ioctl -may be extended in different ways to devices with -different properties, -.I argp -should have an open-ended declaration like -.IP -.B union { struct sgttyb -.RB ... ; -\&... -.B } *argp; -.PP -The important thing is that the size is fixed by `struct sgttyb'. -.SH ASSEMBLER -(ioctl = 54.) -.br -.B sys ioctl; fildes; request; argp -.PP -(stty = 31.) -.br -(file descriptor in r0) -.br -.B stty; argp -.PP -(gtty = 32.) -.br -(file descriptor in r0) -.br -.B sys gtty; argp //GO.SYSIN DD ioctl.2 echo kill.2 sed 's/.//' >kill.2 <<'//GO.SYSIN DD kill.2' -.TH KILL 2 -.SH NAME -kill \- send signal to a process -.SH SYNOPSIS -.B kill(pid, sig); -.SH DESCRIPTION -.I Kill -sends the signal -.I sig -to the process specified by the -process number in r0. -See -.IR signal (2) -for a list of signals. -.PP -The sending and receiving processes must -have the same effective user ID, otherwise -this call is restricted to the super-user. -.PP -If the process number is 0, -the signal is sent to all other processes in the -sender's process group; -see -.IR tty (4). -.PP -If the process number is \-1, and the user is the super-user, -the signal is broadcast universally -except to processes 0 and 1, the scheduler -and initialization processes, -see -.IR init (8). -.PP -Processes may send signals to themselves. -.SH "SEE ALSO" -signal(2), kill(1) -.SH DIAGNOSTICS -Zero is returned if the process is killed; -\-1 is returned if the process does not -have the same effective user ID and the -user is not super-user, or if the process -does not exist. -.SH ASSEMBLER -(kill = 37.) -.br -(process number in r0) -.br -.B sys kill; sig //GO.SYSIN DD kill.2 echo link.2 sed 's/.//' >link.2 <<'//GO.SYSIN DD link.2' -.TH LINK 2 -.SH NAME -link \- link to a file -.SH SYNOPSIS -.B link(name1, name2) -.br -.B char *name1, *name2; -.SH DESCRIPTION -A link -to -.I name1 -is created; -the link has the name -.IR name2 . -Either name may be an arbitrary path name. -.SH "SEE ALSO" -ln(1), unlink(2) -.SH DIAGNOSTICS -Zero is returned when a link is made; -\-1 is returned when -.I name1 -cannot be found; when -.I name2 -already exists; when the directory of -.I name2 -cannot be written; when -an attempt is made to link to a directory by a user -other than the super-user; -when an attempt is made to link -to a file on another file system; -when a file has too many links. -.SH ASSEMBLER -(link = 9.) -.br -.B sys link; name1; name2 //GO.SYSIN DD link.2 echo lock.2 sed 's/.//' >lock.2 <<'//GO.SYSIN DD lock.2' -.TH LOCK 2 local -.SH NAME -lock \- lock a process in primary memory -.SH SYNOPSIS -.B lock(flag) -.SH DESCRIPTION -If the -.I flag -argument is non-zero, -the process executing this call -will not be swapped except if it is required -to grow. -If the argument is zero, -the process is -.RI un lock ed. -This call may only be executed by -the super-user. -.SH BUGS -.IR Lock ed -processes interfere with the compaction of primary memory -and can cause deadlock. -This system call is not considered -a permanent part of the system. -.SH ASSEMBLER -(lock = 53.) -.br -.B sys lock; flag //GO.SYSIN DD lock.2 echo lseek.2 sed 's/.//' >lseek.2 <<'//GO.SYSIN DD lseek.2' -.TH LSEEK 2 -.SH NAME -lseek, tell \- move read/write pointer -.SH SYNOPSIS -.B long lseek(fildes, offset, whence) -.br -.B long offset; -.PP -.B long tell(fildes) -.SH DESCRIPTION -The file -descriptor refers to a file open for reading or writing. -The read (resp. write) pointer for the file is set as follows: -.IP -If -.I whence -is 0, the pointer is set to -.I offset -bytes. -.IP -If -.I whence -is 1, the pointer is set to its current location plus -.IR offset . -.IP -If -.I whence -is 2, the pointer is set to the size of the -file plus -.IR offset . -.PP -The returned value is the resulting pointer location. -.PP -The obsolete function -.IR tell ( fildes ) -is identical to -.IR lseek ( "fildes, 0L, 1" ). -.PP -Seeking far beyond the end of a file, then writing, -creates a gap or `hole', which occupies no -physical space and reads as zeros. -.SH "SEE ALSO" -open(2), creat(2), fseek(3) -.SH DIAGNOSTICS -\-1 -is returned for -an undefined file descriptor, -seek on a pipe, -or seek to a position before the beginning of file. -.SH BUGS -.I Lseek -is a no-op on character special files. -.SH ASSEMBLER -(lseek = 19.) -.br -(file descriptor in r0) -.br -.B sys lseek; offset1; offset2; whence -.PP -.I Offset1 -and -.I offset2 -are the high and low words of -.IR offset ; -r0 and r1 contain -the pointer upon return. //GO.SYSIN DD lseek.2 echo mknod.2 sed 's/.//' >mknod.2 <<'//GO.SYSIN DD mknod.2' -.TH MKNOD 2 -.SH NAME -mknod \- make a directory or a special file -.SH SYNOPSIS -.B mknod(name, mode, addr) -.br -.B char *name; -.SH DESCRIPTION -.I Mknod -creates a new file -whose name is the null-terminated string pointed -to by -.IR name . -The mode of the new file -(including directory and special file bits) -is initialized from -.IR mode . -(The protection part of the mode -is modified by the process's mode mask; see -.IR umask (2)). -The first block pointer of the i-node -is initialized from -.IR addr . -For ordinary files and directories -.I addr -is normally zero. -In the case of a special file, -.I addr -specifies which special file. -.PP -.I Mknod -may be invoked only by the super-user. -.SH "SEE ALSO" -mkdir(1), mknod(1), filsys(5) -.SH DIAGNOSTICS -Zero is returned if the file has been made; \-1 -if the file already exists -or if the user is not the super-user. -.SH ASSEMBLER -(mknod = 14.) -.br -.B sys mknod; name; mode; addr //GO.SYSIN DD mknod.2 echo mount.2 sed 's/.//' >mount.2 <<'//GO.SYSIN DD mount.2' -.TH MOUNT 2 -.SH NAME -mount, umount \- mount or remove file system -.SH SYNOPSIS -.B mount(special, name, rwflag) -.br -.B char *special, *name; -.PP -.B umount(special) -.br -.B char *special; -.SH DESCRIPTION -.I Mount -announces to the system that a removable file system has -been mounted on -the block-structured special file -.I special; -from now on, references to file -.I name -will refer to -the root file on the newly mounted file system. -.I Special -and -.I name -are pointers to null-terminated strings -containing the appropriate path names. -.PP -.I Name -must exist already. -.I Name -must be a directory (unless the root of the mounted file system -is not a directory). -Its old contents -are inaccessible while the file system -is mounted. -.PP -The -.I rwflag -argument determines whether -the file system can be written on; if it is 0 writing -is allowed, if non-zero no writing is done. -Physically write-protected and magnetic -tape file systems must be mounted read-only or -errors will occur when access times are updated, -whether or not any -explicit write is attempted. -.PP -.I Umount -announces to the system that the -.I special -file is no longer to contain a removable file system. -The associated file reverts to its ordinary interpretation. -.SH "SEE ALSO" -mount(1) -.SH DIAGNOSTICS -.I Mount -returns 0 if the action occurred; \-1 if -.I special -is inaccessible or not an appropriate file; if -.I name -does not exist; if -.I special -is already mounted; if -.I name -is in use; or if -there are already too many -file systems mounted. -.PP -.I Umount -returns 0 if the action occurred; \-1 if -if the special file is inaccessible or -does not have a mounted file system, -or if there are active files in the mounted -file system. -.SH ASSEMBLER -(mount = 21.) -.br -.B sys mount; special; name; rwflag -.PP -(umount = 22.) -.br -.B sys umount; special //GO.SYSIN DD mount.2 echo mpx.2 sed 's/.//' >mpx.2 <<'//GO.SYSIN DD mpx.2' -.TH MPX 2 -.SH NAME -mpx \- create and manipulate multiplexed files -.SH SYNOPSIS -.B mpx(name, access) -.B char *name; -.PP -.B join(fd, xd) -.PP -.B chan(xd) -.PP -.B extract(i, xd) -.PP -.B attach(i, xd) -.PP -.B detach(i, xd) -.PP -.B connect(fd, cd, end) -.PP -.B npgrp(i, xd, pgrp) -.PP -.B ckill(i, xd, signal) -.PP -.B #include -.br -.B mpxcall(cmd, vec) -.br -.B int *vec; -.SH DESCRIPTION -.PP -.B mpxcall(cmd, vec) -is the system call shared by the -library routines described below. -.I Cmd -selects a command using values -defined in -.IR . -.I Vec -is the address of a -structure containing the arguments -for the command. -.PP -.B mpx(name, access) -.PP -.I Mpx -creates and opens the file -.I name -with access permission -.I access -(see -.IR creat (2)) -and returns a file descriptor available for -reading and writing. -A \-1 is returned if the file cannot be created, -if -.I name -already exists, or -if the file table or other operating system -data structures are full. -The file descriptor is required for use -with other routines. -.PP -If -.I name -designates a null string, -a file descriptor is returned as described -but no entry is created in the file system. -.PP -Once created an mpx file may be opened -(see -.IR open (2)) -by any process. -This provides a form of interprocess communication -whereby a process B can `call' process A -by opening an mpx file -created by A. -To B, the file is ordinary with one exception: -the -.I connect -primitive could be applied to it. -Otherwise the functions -described below are used only in process A -and descendants that inherit the open mpx file. -.PP -When a process opens an mpx file, the owner of the -file receives a control message when the file is next read. -The method for `answering' -this kind of call involves -using -.I attach -and -.I detach -as described in more detail below. -.PP -Once B has opened A's mpx file -it is said to have a -.I channel -to A. -A channel is a pair of data streams: -in this case, one from B to A and the -other from A to B. -Several processes may open the same mpx file -yielding multiple channels within the one mpx file. -By accessing the appropriate channel, -A can communicate with B and any others. -When A reads (see -.IR read (2)) -from the mpx file -data written to A by the other processes appears -in A's buffer using a record format -described in -.IR mpxio (5). -When A writes (see -.IR write (2)) -on its mpx file the data must be formatted in a similar way. -.PP -The following commands -are used to manipulate mpx files and channels. -.IP -.IR join \- -adds a new channel on an mpx file to an open file F. -I/O on the new channel is I/O on F. -.br -.IR chan \- -creates a new channel. -.br -.IR extract \- -file descriptor maintenance. -.br -.IR connect \- -similar to join except that the open file F is connected -to an existing channel. -.br -.I attach -and -.IR detach \- -used with call protocol. -.br -.IR npgrp \- -manipulates process group numbers so that a channel -can act as a control terminal (see -.IR tty (4)). -.br -.IR ckill \- -send signal (see -.IR signal (2)) -to process group through channel. -.PP -A maximum of 15 channels may be connected to an -mpx file. -They are numbered 0 through 14. -.I Join -may be used to make one mpx file appear as a channel -on another mpx file. -A hierarchy or tree of mpx files may be set up in this way. -In this case -one of the mpx files must be the root of a tree -where the other mpx files are interior nodes. -The maximum depth of such a tree -is 4. -.PP -An -.I index -is a 16-bit value -that denotes a location -in an mpx tree other than the root: -the path through mpx `nodes' from the root -to the location is expressed as a sequence of -4-bit nibbles. -The branch taken at the root is represented by -the low-order 4-bits of an index. -Each succeeding branch is specified by the next -higher-order nibble. -If the length of a path to be expressed -is less than 4, -then the illegal channel number, 15, -must be used to terminate the sequence. -This is not strictly necessary for the -simple case of a tree consisting of -only a root node: its channels -can be expressed by the numbers -0 through 14. -An index -.I i -and file descriptor -.I xd -for the root of an mpx tree are -required as arguments to most -of the commands described below. -Indices also serve as channel identifiers -in the record formats given in -.IR mpxio (5). -Since -1 is not a valid index, -it can be returned as a error indication -by subroutines that normally return -indices. -.PP -The operating system informs the process managing an mpx file -of changes in the status of channels attached to the file -by generating messages that -are read along with data from the channels. -The form and content of these messages is described -in -.IR mpxio (5). -.PP -.B join(fd, xd) -establishes a connection (channel) between an mpx file -and another object. -.I Fd -is an open file descriptor for a character device -or an mpx file and -.I xd -is the file descriptor of an -mpx file. -.I Join -returns the index for the new channel -if the operation succeeds and \-1 -if it does not. -.PP -Following join, -.I fd -may still be used in any system call that would -have been meaningful before the join operation. -Thus -a process can read and write directly to -.I fd -as well as access it via -.I xd. -If the number of channels -required for a tree of mpx files -exceeds the number of open files -permitted a process by the operating system, -some of the file descriptors can be released using -the standard -.IR close (2) -call. -Following a close on an active file descriptor for a channel -or internal mpx node, -that object may still be accessed through the root of the -tree. -.PP -.B chan(xd) -allocates a channel and connects -one end of it to the mpx file -represented by file descriptor -.I xd. -.I Chan -returns the index of the new channel or -a \-1 indicating failure. -The -.I extract -primitive can be used to get a non-multiplexed -file descriptor for the free end of a channel -created by -.I chan. -.PP -Both -.I chan -and -.I join -operate on the mpx file specified by -.IR xd . -File descriptors for interior nodes of an -mpx tree must be preserved or reconstructed with -.I extract -for use with -.I join -or -.IR chan . -For the remaining commands described here, -.I xd -denotes the file descriptor for the -root of an mpx tree. -.PP -.B Extract(i, xd) -returns a file descriptor for the object with -index -.I i -on the mpx tree with root file descriptor -.I xd. -A \-1 is returned by extract if a file descriptor is not available -or if the arguments do not refer to an existing -channel and mpx file. -.PP -.B attach(i, xd) -.br -.BR "detach(i, xd)" . -If a process A has created an mpx file represented -by file descriptor -.I xd, -then a process B -can open (see -.IR open (2)) -the mpx file. -The purpose is to establish a channel between -A and B through the mpx file. -.I Attach -and -.I Detach -are used by A to respond to -such opens. -.PP -An open request by B fails immediately if a -new channel cannot be allocated on the mpx file, -if the mpx file does not exist, -or if it does exist -but there is no process (A) -with a multiplexed file descriptor -for the mpx file -(i.e. -.I xd -as returned by -.IR mpx (2)). -Otherwise a channel -with index number -.I i -is allocated. -The next time A reads on file descriptor -.IR xd , -the WATCH control message -(see -.IR mpxio (5)) -will be delivered on channel -.I i. -A responds to this message with -.I attach -or -.I detach. -The former causes the open to complete and -return a file descriptor to B. -The latter deallocates channel -.I i -and causes the open to fail. -.PP -One mpx file may be placed in `listener' mode. -This is done by writing -.I "ioctl(xd, MXLSTN, 0)" -where -.I xd -is an mpx file descriptor -and MXLSTN is defined in -.IR /usr/include/sgtty.h . -The semantics of listener mode are that -all file names discovered by -.IR open (2) -to have -the syntax -.I "system!pathname" -(see -.IR uucp (1)) -are treated as opens on the mpx file. -The operating system sends the listener process -an OPEN message (see -.IR mpxio (5)) -which includes the file name being opened. -.I Attach -and -.I detach -then apply as described above. -.PP -.I Detach -has two other uses: -it closes and releases the resources -of any active channel it is applied to, -and should be used to respond to -a CLOSE message (see -.IR mpxio (5)) -on a channel so the channel may be reused. -.PP -.BR "connect(fd, cd, end)" . -.I Fd -is a character file descriptor and -.I cd -is a file descriptor for a channel, -such as might be obtained via -.I "extract( chan(xd), xd)" -or by -.IR open (2) -followed by -.I attach. -.I Connect -splices the two streams together. -If -.I end -is negative, only -the output of -.I fd -is spliced to the input of -.I cd. -If -.I end -is positive, the output of -.I cd -is spliced to the input of -.I fd. -If -.I end -is zero, then both splices are made. -.PP -.BR "npgrp(i, xd, pgrp)" . -If -.I xd -is negative -.I npgrp -applies to the process executing it, -otherwise -.I i -and -.I xd -are interpreted as a channel index and -mpx file descriptor -and -.I npgrp -is applied to the process on the -non-multiplexed end of the channel. -If -.I pgrp -is zero, the process group number of the indicated process -is set to the process number of that process, -otherwise the value of -.I pgrp -is used as the process group number. -.PP -.I Npgrp -normally returns the new process group number. -If -.I i -and -.I xd -specify a nonexistant channel, -.I npgrp -returns \-1. -.PP -.B ckill(i, xd, signal) -sends the specified signal (see -.IR signal (2)) -through the channel specified by -.I i -and -.I xd. -If the channel is connected to anything other -than a process, -.I ckill -is a null operation. -If there is a process at the other end of the channel, -the process group will be interrupted (see -.IR signal (2), -.IR kill (2)). -.I Ckill -normally returns -.I signal. -If -.I ch -and -.I xd -specify a nonexistent channel, -.I ckill -returns \-1. -.SH FILES -/usr/include/sys/mx.h -.br -/usr/include/sgtty.h -.SH "SEE ALSO" -mpxio(5) -.SH BUGS -.PP -Mpx files are an experimental part of the operating -system more subject to change and prone to bugs -than other parts. -Maintenance programs, e.g. -.IR icheck (1), -diagnose mpx files as an illegal mode. -Channels may only be connected to objects in the operating -system that are accessible through the line discipline -mechanism. -Higher performace line disciplines are needed. -The maximum tree depth restriction is not really checked. -A non-destructive -.I disconnect -primitive (inverse of -.IR connect ) -is not provided. -A non-blocking flow control strategy -based on messages defined in -.IR mpxio (5) -should not be attempted by novices; -the enabling -.I ioctl -command should be protected. -The -.I join -operation could be subsumed by -.I connect. -A mechanism is needed for moving a channel from one -location in an mpx tree to another. //GO.SYSIN DD mpx.2 echo mpxcall.2 sed 's/.//' >mpxcall.2 <<'//GO.SYSIN DD mpxcall.2' -.TH MPXCALL 2 -.SH NAME -mpxcall \- multiplexor and channel interface -.SH SYNOPSIS -.B mpxcall(arg1, arg2, arg3, cmd) -.SH DESCRIPTION -.I Mpxcall -supplies a primitive interface to the kernel -used by the routines listed below. -Each routine that uses -.I mpxcall -passes an integer -.I cmd -as the fourth argument. -These are defined in -.I /usr/include/mx.h. -.I Mpxcall -always returns an integer which is to be interpreted -in accordance with the definition of -.I cmd. -.SH "SEE ALSO" -group(2), join(2), extract(2), connect(2), chan(2), attach(2), detach(2) -.SH DIAGNOSTICS -The value \-1 is returned on error. //GO.SYSIN DD mpxcall.2 echo nice.2 sed 's/.//' >nice.2 <<'//GO.SYSIN DD nice.2' -.TH NICE 2 -.SH NAME -nice \- set program priority -.SH SYNOPSIS -.B nice(incr) -.SH DESCRIPTION -The scheduling -priority of the process is augmented by -.IR incr . -Positive priorities get less -service than normal. -Priority 10 is recommended to users -who wish to execute long-running programs -without flak from the administration. -.PP -Negative increments are ignored except on behalf of -the super-user. -The priority is limited to the range -\-20 (most urgent) to 20 (least). -.PP -The priority of a process is -passed to a child process by -.IR fork (2). -For a privileged process to return to normal priority -from an unknown state, -.I nice -should be called successively with arguments -\-40 (goes to priority \-20 because of truncation), -20 (to get to 0), -then 0 (to maintain compatibility with previous versions -of this call). -.SH "SEE ALSO" -nice(1) -.SH ASSEMBLER -(nice = 34.) -.br -(priority in r0) -.br -.B sys nice //GO.SYSIN DD nice.2 echo open.2 sed 's/.//' >open.2 <<'//GO.SYSIN DD open.2' -.TH OPEN 2 -.SH NAME -open \- open for reading or writing -.SH SYNOPSIS -.B open(name, mode) -.br -.B char *name; -.SH DESCRIPTION -.I Open -opens the file -.I name -for reading -(if -.I mode -is 0), -writing (if -.I mode -is 1) or for both reading and writing -(if -.I mode -is 2). -.I Name -is the address of a string of ASCII characters representing -a path name, terminated by a null character. -.PP -The file is positioned at the beginning (byte 0). -The returned file descriptor must be used for subsequent calls -for other input-output functions on the file. -.SH "SEE ALSO" -creat(2), read(2), write(2), dup(2), close(2) -.SH DIAGNOSTICS -The value \-1 is returned -if the file does not exist, -if one of the necessary directories -does not exist or is unreadable, if the file is not -readable (resp. writable), or if too many files are open. -.SH ASSEMBLER -(open = 5.) -.br -.B sys open; name; mode -.br -(file descriptor in r0) //GO.SYSIN DD open.2 echo pause.2 sed 's/.//' >pause.2 <<'//GO.SYSIN DD pause.2' -.TH PAUSE 2 -.SH NAME -pause \- stop until signal -.SH SYNOPSIS -.B pause( ) -.SH DESCRIPTION -.I Pause -never returns normally. -It is used to give up control while waiting for -a signal from -.IR kill (2) -or -.IR alarm (2). -.SH SEE ALSO -kill(1), kill(2), alarm(2), signal(2), setjmp(3) -.SH ASSEMBLER -(pause = 29.) -.br -.B sys pause //GO.SYSIN DD pause.2 echo phys.2 sed 's/.//' >phys.2 <<'//GO.SYSIN DD phys.2' -.TH PHYS 2 PDP11 -.SH NAME -phys \- allow a process to access physical addresses -.SH SYNOPSIS -.B phys(segreg, size, physadr) -.SH DESCRIPTION -The argument -.I segreg -specifies a process virtual (data-space) address -range of 8K bytes starting -at virtual address -.IR segreg \(mu8K -bytes. -This address range is mapped into -physical address -.IR physadr \(mu64 -bytes. -Only the first -.IR size \(mu64 -bytes of this mapping is addressable. -If -.I size -is zero, -any previous mapping of this -virtual address range is nullified. -For example, -the call -.PP - phys(6, 1, 0177775); -.PP -will map virtual addresses 0160000-0160077 into -physical addresses 017777500-017777577. -In particular, -virtual address 0160060 is the PDP-11 console -located at physical address 017777560. -.PP -This call may only be executed by the super-user. -.SH "SEE ALSO" -PDP-11 segmentation hardware -.SH DIAGNOSTICS -The function value zero is returned if -the physical mapping is in effect. -The value \-1 is returned -if not super-user, -if -.I segreg -is not in the range 0-7, -if -.I size -is not in the range 0-127, -or if -the specified -.I segreg -is already used for other than -a previous call to -.IR phys . -.SH BUGS -This system call is obviously very machine -dependent and very dangerous. -This system call is not considered -a permanent part of the system. -.SH ASSEMBLER -(phys = 52.) -.br -.B sys phys; segreg; size; physadr //GO.SYSIN DD phys.2 echo pipe.2 sed 's/.//' >pipe.2 <<'//GO.SYSIN DD pipe.2' -.TH PIPE 2 -.SH NAME -pipe \- create an interprocess channel -.SH SYNOPSIS -.B pipe(fildes) -.br -.B int fildes[2]; -.SH DESCRIPTION -The -.I pipe -system call -creates an I/O mechanism called a pipe. -The file descriptors returned can -be used in read and write operations. -When the pipe is written using the descriptor -.IR fildes [1] -up to 4096 bytes of data are buffered -before the writing process is suspended. -A read using the descriptor -.IR fildes [0] -will pick up the data. -Writes with a count of 4096 bytes or less are atomic; -no other process can intersperse data. -.PP -It is assumed that after the -pipe has been set up, -two (or more) -cooperating processes -(created by subsequent -.I fork -calls) -will pass data through the -pipe with -.I read -and -.I write -calls. -.PP -The Shell has a syntax -to set up a linear array of processes -connected by pipes. -.PP -Read calls on an empty -pipe (no buffered data) with only one end -(all write file descriptors closed) -returns an end-of-file. -.SH "SEE ALSO" -sh(1), read(2), write(2), fork(2) -.SH DIAGNOSTICS -The function value zero is returned if the -pipe was created; \-1 if -too many files are already open. -A signal is generated if a write on a pipe with only one end is attempted. -.SH BUGS -Should more than 4096 bytes be necessary in any -pipe among a loop of processes, deadlock will occur. -.SH ASSEMBLER -(pipe = 42.) -.br -.B sys pipe -.br -(read file descriptor in r0) -.br -(write file descriptor in r1) //GO.SYSIN DD pipe.2 echo pkon.2 sed 's/.//' >pkon.2 <<'//GO.SYSIN DD pkon.2' -.TH PKON 2 -.SH NAME -pkon, pkoff \- establish packet protocol -.SH SYNOPSIS -.B pkon(fd, size) -.PP -.B pkoff(fd) -.SH DESCRIPTION -.I Pkon -establishes packet protocol (see -.IR pk (4)) -on the open character special file whose file -descriptor is -.I fd. -.I Size -is a desired packet size, a power of 2 in the range -.RI 32\(<= size \(<=4096. -The size is negotiated with a remote packet driver, -and a possibly smaller actual packet size is returned. -.PP -An asynchronous line used for packet -communication should be in raw mode; -see -.IR tty (4). -.PP -.I Pkoff -turns off the packet driver on the channel whose -file descriptor is -.I fd. -.SH SEE ALSO -pk(4), pkopen(3), tty(4), signal(2) -.SH DIAGNOSTICS -.I Pkon -returns \-1 if -.I fd -does not describe an open file, or if -packet communication cannot -be established. -.PP -.I Pkoff -returns \-1 for an unknown file descriptor. -.PP -Writing on a packet driver link that has been shut down -by -.I close -or -.I pkoff -at the other end raises signal SIGPIPE -in the writing process. //GO.SYSIN DD pkon.2 echo profil.2 sed 's/.//' >profil.2 <<'//GO.SYSIN DD profil.2' -.TH PROFIL 2 -.SH NAME -profil \- execution time profile -.SH SYNOPSIS -.B profil(buff, bufsiz, offset, scale) -.br -.B char *buff; -.br -.B int bufsiz, offset, scale; -.SH DESCRIPTION -.I Buff -points to an area of core whose length (in bytes) is given by -.IR bufsiz . -After this call, the user's program counter (pc) -is examined each clock tick (60th second); -.I offset -is subtracted from it, and the result multiplied by -.IR scale . -If the resulting number corresponds to a word -inside -.I buff, -that word is incremented. -.PP -The scale is interpreted as an unsigned, -fixed-point fraction with binary point at the -left: 0177777(8) gives a 1-1 mapping of pc's to words -in -.I buff; -077777(8) maps each pair of instruction words -together. -02(8) maps all instructions onto the beginning of -.I buff -(producing a non-interrupting core clock). -.PP -Profiling is turned off by giving a -.I scale -of 0 or 1. -It is rendered -ineffective by giving a -.I bufsiz -of 0. -Profiling is turned off when an -.I exec -is executed, but remains on in child and parent both -after a -.IR fork . -Profiling may be turned off if an update in -.I buff -would cause a memory fault. -.SH "SEE ALSO" -monitor(3), prof(1) -.SH ASSEMBLER -(profil = 44.) -.br -.B sys profil; buff; bufsiz; offset; scale //GO.SYSIN DD profil.2 echo ptrace.2 sed 's/.//' >ptrace.2 <<'//GO.SYSIN DD ptrace.2' -.TH PTRACE 2 -.SH NAME -ptrace \- process trace -.SH SYNOPSIS -#include -.PP -.B ptrace(request, pid, addr, data) -.br -.B int *addr; -.SH DESCRIPTION -.I Ptrace -provides a means by which a parent process -may control the execution of a child process, -and examine and change its core image. -Its primary use is for the implementation of breakpoint debugging. -There are four arguments whose interpretation -depends on a -.I request -argument. -Generally, -.I pid -is the process ID of the traced process, -which must be a child (no more distant descendant) -of the tracing process. -A process being traced -behaves normally until it encounters some signal whether internally generated -like `illegal instruction' or externally generated like `interrupt.' -See -.IR signal (2) -for the list. -Then the traced process enters a stopped state -and its parent is notified via -.IR wait (2). -When the child is in the stopped state, -its core image can be examined and modified -using -.IR ptrace . -If desired, another -.I ptrace -request can then cause the child either to terminate -or to continue, possibly ignoring the signal. -.PP -The value of the -.I request -argument determines the precise -action of the call: -.TP 4 -0 -This request is the only one used by the child process; -it declares that the process is to be traced by its parent. -All the other arguments are ignored. -Peculiar results will ensue -if the parent does not expect to trace the child. -.TP 4 -1,2 -The -word in the child process's address space -at -.I addr -is returned. -If I and D space are separated, request 1 indicates I space, -2 D space. -.I Addr -must be even. -The child must be stopped. -The input -.I data -is ignored. -.TP 4 -3 -The word -of the system's per-process data area corresponding to -.I addr -is returned. -.I Addr -must be even and less than 512. -This space contains the registers and other information about -the process; -its layout corresponds to the -.I user -structure in the system. -.TP 4 -4,5 -The -given -.I data -is written at the word in the process's address space corresponding to -.I addr, -which must be even. -No useful value is returned. -If I and D space are separated, request 4 indicates I space, -5 D space. -Attempts to write in pure procedure -fail if another process is executing the same file. -.TP 4 -6 -The process's system data is written, -as it is read with request 3. -Only a few locations can be written in this way: -the general registers, -the floating point status and registers, -and certain bits of the processor status word. -.TP 4 -7 -The -.I data -argument is taken as a signal number -and the child's execution continues -at location -.I addr -as if it had incurred that signal. -Normally the signal number will be -either 0 to indicate that the signal that caused the stop -should be ignored, -or that value fetched out of the -process's image indicating which signal caused -the stop. -If -.I addr -is (int *)1 then execution continues from where it stopped. -.TP 4 -8 -The traced process terminates. -.TP 4 -9 -Execution continues as in request 7; -however, as soon as possible after execution of at least one instruction, -execution stops again. -The signal number from the stop is -SIGTRAP. -(On the PDP-11 the T-bit is used and just one instruction -is executed; -on the Interdata the stop does not take place -until a store instruction is executed.) -This is part of the mechanism for implementing breakpoints. -.PP -As indicated, -these calls -(except for request 0) -can be used only when the subject process has stopped. -The -.I wait -call is used to determine -when a process stops; -in such a case the `termination' status -returned by -.I wait -has the value 0177 to indicate stoppage rather -than genuine termination. -.PP -To forestall possible fraud, -.I ptrace -inhibits the set-user-id facility -on subsequent -.IR exec (2) -calls. -If a traced process calls -.I exec, -it will stop before executing the first instruction of the new image -showing signal SIGTRAP. -.PP -On the Interdata 8/32, -`word' means a 32-bit word and `even' means 0 mod 4. -.SH "SEE ALSO" -wait(2), signal(2), adb(1) -.SH DIAGNOSTICS -The value \-1 is returned if -.I request -is invalid, -.I pid -is not a traceable process, -.I addr -is out of bounds, -or -.I data -specifies an illegal signal number. -.SH BUGS -On the Interdata 8/32, -`as soon as possible' (request 7) -means `as soon as a store instruction has been executed.' -.PP -The request 0 call should be able to specify -signals which are to be treated normally and not cause a stop. -In this way, for example, -programs with simulated floating point (which -use `illegal instruction' signals at a very high rate) -could be efficiently debugged. -.br -The error indication, \-1, is a legitimate function value; -.I errno, -see -.IR intro (2), -can be used to disambiguate. -.PP -It should be possible to stop a process on occurrence of a system -call; -in this way a completely controlled environment could -be provided. -.SH ASSEMBLER -(ptrace = 26.) -.br -(data in r0) -.br -.B sys ptrace; pid; addr; request -.br -(value in r0) //GO.SYSIN DD ptrace.2 echo read.2 sed 's/.//' >read.2 <<'//GO.SYSIN DD read.2' -.TH READ 2 -.SH NAME -read \- read from file -.SH SYNOPSIS -.B read(fildes, buffer, nbytes) -.br -.B char *buffer; -.SH DESCRIPTION -A file descriptor is a word -returned from a successful -.I "open, creat, dup," -or -.I pipe -call. -.I Buffer -is the location of -.I nbytes -contiguous -bytes into which the input will be placed. -It is not guaranteed -that all -.I nbytes -bytes will be read; for example -if the file refers to a typewriter at most one line -will be returned. -In any event the number of characters read is returned. -.PP -If the returned value is 0, then -end-of-file has been reached. -.SH "SEE ALSO" -open(2), creat(2), dup(2), pipe(2) -.SH DIAGNOSTICS -As mentioned, -0 is returned when the end of the file has been reached. -If the read was otherwise unsuccessful -the return value is \-1. -Many conditions -can generate an error: -physical I/O errors, bad buffer address, -preposterous -.I nbytes, -file descriptor not that of -an input file. -.SH ASSEMBLER -(read = 3.) -.br -(file descriptor in r0) -.br -.B sys read; buffer; nbytes -.br -(byte count in r0) //GO.SYSIN DD read.2 echo setuid.2 sed 's/.//' >setuid.2 <<'//GO.SYSIN DD setuid.2' -.TH SETUID 2 -.SH NAME -setuid, setgid \- set user and group ID -.SH SYNOPSIS -.B setuid(uid) -.PP -.B setgid(gid) -.SH DESCRIPTION -The user ID (group ID) of the current process is set to -the argument. -Both the effective and the real ID are set. -These calls are only permitted to the super-user -or if the argument is the real ID. -.SH "SEE ALSO" -getuid(2) -.SH DIAGNOSTICS -Zero is returned if the user (group) ID is set; -\-1 is returned otherwise. -.SH ASSEMBLER -(setuid = 23.) -.br -(user ID in r0) -.br -.B sys setuid -.PP -(setgid = 46.) -.br -(group ID in r0) -.br -.B sys setgid //GO.SYSIN DD setuid.2 echo signal.2 sed 's/.//' >signal.2 <<'//GO.SYSIN DD signal.2' -.TH SIGNAL 2 -.SH NAME -signal \- catch or ignore signals -.SH SYNOPSIS -.B #include -.PP -.B (*signal(sig, func))() -.br -.B (*func)(); -.SH DESCRIPTION -A signal -is generated by some abnormal event, -initiated either by user at a typewriter (quit, interrupt), -by a program error (bus error, etc.), -or by request of another program (kill). -Normally all signals -cause termination of the receiving process, -but a -.I signal -call allows them either to be ignored -or to cause an interrupt to a specified location. -Here is the list of signals with names as in -the include file. -.LP -.nf -.ta \w'SIGMMMM 'u +\w'15* 'u -SIGHUP 1 hangup -SIGINT 2 interrupt -SIGQUIT 3* quit -SIGILL 4* illegal instruction (not reset when caught) -SIGTRAP 5* trace trap (not reset when caught) -SIGIOT 6* IOT instruction -SIGEMT 7* EMT instruction -SIGFPE 8* floating point exception -SIGKILL 9 kill (cannot be caught or ignored) -SIGBUS 10* bus error -SIGSEGV 11* segmentation violation -SIGSYS 12* bad argument to system call -SIGPIPE 13 write on a pipe or link with no one to read it -SIGALRM 14 alarm clock -SIGTERM 15 software termination signal - 16 unassigned -.fi -.PP -The starred signals in the list above cause a core image -if not caught or ignored. -.PP -If -.I func -is SIG_DFL, the default action -for signal -.I sig -is reinstated; this default is termination, -sometimes with a core image. -If -.I func -is SIG_IGN the signal is ignored. -Otherwise -when the signal occurs -.I func -will be called with the -signal number as argument. -A return from the function will -continue the process at the point it was interrupted. -Except as indicated, -a signal is reset to SIG_DFL after being caught. -Thus if it is desired to -catch every such signal, -the catching routine must -issue another -.I signal -call. -.PP -When a caught signal occurs -during certain system calls, the call terminates prematurely. -In particular this can occur -during a -.I read -or -.IR write (2) -on a slow device (like a typewriter; but not a file); -and during -.I pause -or -.IR wait (2). -When such a signal occurs, the saved user status -is arranged in such a way that when return from the -signal-catching takes place, it will appear that the -system call returned an error status. -The user's program may then, if it wishes, -re-execute the call. -.PP -The value of -.I signal -is the previous (or initial) -value of -.I func -for the particular signal. -.PP -After a -.IR fork (2) -the child inherits -all signals. -.IR Exec (2) -resets all -caught signals to default action. -.SH "SEE ALSO" -kill(1), kill(2), -ptrace(2), -setjmp(3) -.SH DIAGNOSTICS -The value (int)\-1 is returned if the -given signal is out of range. -.SH BUGS -If a repeated signal arrives before the last one can be -reset, there is no chance to catch it. -.PP -The type specification of the routine and its -.I func -argument are problematical. -.SH ASSEMBLER -(signal = 48.) -.br -.B sys signal; sig; label -.br -(old label in r0) -.PP -If -.I label -is 0, -default action is reinstated. -If -.I label -is odd, the signal is ignored. -Any other even -.I label -specifies an address in the process -where an interrupt is simulated. -An RTI or RTT instruction will return from the -interrupt. //GO.SYSIN DD signal.2 echo stat.2 sed 's/.//' >stat.2 <<'//GO.SYSIN DD stat.2' -.TH STAT 2 -.SH NAME -stat, fstat \- get file status -.SH SYNOPSIS -.B #include -.br -.B #include -.PP -.B stat(name, buf) -.br -.B char *name; -.br -.B struct stat *buf; -.PP -.B fstat(fildes, buf) -.br -.B struct stat *buf; -.SH DESCRIPTION -.I Stat -obtains detailed information about a named file. -.I Fstat -obtains the same information about an open file -known by the file descriptor from a successful -.I open, creat, dup -or -.IR pipe (2) -call. -.PP -.I Name -points to a null-terminated string naming -a file; -.I buf -is the address of a buffer -into which information is placed concerning the file. -It is unnecessary to have any -permissions at all with respect to the file, but all directories -leading to the file must be searchable. -The layout of the structure pointed to by buf -as defined in -.I -is given below. -.I St_mode -is encoded according to the `#define' statements. -.PP -.nf -.so /usr/include/sys/stat.h -.fi -.PP -The mode bits 0000070 and 0000007 encode group and -others permissions (see -.IR chmod (2)). -The defined types, -.I -ino_t, off_t, time_t, -name various width integer values; -.I dev_t -encodes -major and minor device numbers; -their exact definitions are in -the include file -(see -.IR types (5). -.PP -When -.I fildes -is associated with a pipe, -.I fstat -reports an ordinary file -with restricted permissions. -The size is the number of bytes queued in the pipe. -.PP -.I st_atime -is the file was last read. -For reasons of efficiency, it is not set when a directory -is searched, although this would be more logical. -.I st_mtime -is the time the file was last written or created. -It is not set by changes of owner, group, link count, or mode. -.I st_ctime -is set both both by writing and changing the i-node. -.SH "SEE ALSO" -ls(1), filsys(5) -.SH DIAGNOSTICS -Zero is returned if a status is available; -\-1 if the file cannot be found. -.SH ASSEMBLER -(stat = 18.) -.br -.B sys stat; name; buf -.PP -(fstat = 28.) -.br -(file descriptor in r0) -.br -.B sys fstat; buf //GO.SYSIN DD stat.2 echo stime.2 sed 's/.//' >stime.2 <<'//GO.SYSIN DD stime.2' -.TH STIME 2 -.SH NAME -stime \- set time -.SH SYNOPSIS -.B stime(tp) -.br -.B long *tp; -.SH DESCRIPTION -.I Stime -sets the system's idea of the time and date. -Time, pointed to by -.I tp, -is measured in seconds from 0000 GMT Jan 1, 1970. -Only the super-user may use this call. -.SH "SEE ALSO" -date(1), time(2), ctime(3) -.SH DIAGNOSTICS -Zero is returned if the time was set; -\-1 if user is not the super-user. -.SH ASSEMBLER -(stime = 25.) -.br -(time in r0-r1) -.br -.B sys stime -.PP //GO.SYSIN DD stime.2 echo sync.2 sed 's/.//' >sync.2 <<'//GO.SYSIN DD sync.2' -.TH SYNC 2 -.SH NAME -sync \- update super-block -.SH SYNOPSIS -.B sync( ) -.SH DESCRIPTION -.I Sync -causes all information in core -memory that should be on disk to be written out. -This includes modified super blocks, -modified i-nodes, and delayed block I/O. -.PP -It should be used by programs which examine a file system, -for example -.I "icheck, df," -etc. -It is mandatory before a boot. -.SH "SEE ALSO" -sync(1), update(8) -.SH BUGS -The writing, although scheduled, is not necessarily -complete upon return from -.IR sync . -.SH ASSEMBLER -(sync = 36.) -.br -.B sys sync //GO.SYSIN DD sync.2 echo time.2 sed 's/.//' >time.2 <<'//GO.SYSIN DD time.2' -.TH TIME 2 -.SH NAME -time, ftime \- get date and time -.SH SYNOPSIS -.B long time(0) -.PP -.B long time(tloc) -.br -.B long *tloc; -.sp -.B #include -.br -.B #include -.br -.B ftime(tp) -.br -.B struct timeb *tp; -.SH DESCRIPTION -.I Time -returns the time since 00:00:00 GMT, Jan. 1, 1970, measured -in seconds. -.PP -If -.I tloc -is nonnull, -the return value is also stored in the -place to which -.I tloc -points. -.PP -The -.I ftime -entry fills in a structure pointed to by its argument, -as defined by -.IR : -.PP -.nf -.ta .5i +\w'unsigned 'u -.so /usr/include/sys/timeb.h -.fi -.PP -The structure contains the time since the epoch in seconds, -up to 1000 milliseconds of more-precise interval, -the local timezone (measured in minutes of time westward from Greenwich), -and a flag that, if nonzero, indicates that -Daylight Saving time applies locally during the appropriate part of the year. -.SH "SEE ALSO" -date(1), stime(2), ctime(3) -.SH ASSEMBLER -(ftime = 35.) -.br -.B sys ftime; bufptr -.PP -(time = 13.; obsolete call) -.br -.B sys time -.br -(time since 1970 in r0-r1) //GO.SYSIN DD time.2 echo times.2 sed 's/.//' >times.2 <<'//GO.SYSIN DD times.2' -.TH TIMES 2 -.SH NAME -times \- get process times -.SH SYNOPSIS -.B times(buffer) -.br -.B struct tbuffer *buffer; -.SH DESCRIPTION -.I Times -returns time-accounting information -for the current process -and for the terminated child processes -of the current process. -All times are in 1/HZ seconds, -where HZ=60 in North America. -.PP -After the call, the buffer will appear as follows: -.PP -.nf -struct tbuffer { - long proc_user_time; - long proc_system_time; - long child_user_time; - long child_system_time; -}; -.PP -.fi -The children times are the sum -of the children's process times and -their children's times. -.SH "SEE ALSO" -time(1), time(2) -.SH ASSEMBLER -(times = 43.) -.br -.B sys times; buffer //GO.SYSIN DD times.2 echo umask.2 sed 's/.//' >umask.2 <<'//GO.SYSIN DD umask.2' -.TH UMASK 2 -.SH NAME -umask \- set file creation mode mask -.SH SYNOPSIS -.B umask(complmode) -.SH DESCRIPTION -.I Umask -sets a mask used whenever a file is created by -.IR creat (2) -or -.IR mknod (2): -the actual mode (see -.IR chmod (2)) -of the newly-created file is the logical -.B and -of the given mode and the complement of the argument. -Only the low-order 9 bits of the mask (the protection bits) -participate. -In other words, the mask shows the bits to be turned off -when files are created. -.PP -The previous value of the mask is returned by the call. -The value is initially 0 (no restrictions). -The mask is inherited by child processes. -.SH SEE ALSO -creat(2), mknod(2), chmod(2) -.SH ASSEMBLER -(umask = 60.) -.br -.B sys umask; complmode //GO.SYSIN DD umask.2 echo unlink.2 sed 's/.//' >unlink.2 <<'//GO.SYSIN DD unlink.2' -.TH UNLINK 2 -.SH NAME -unlink \- remove directory entry -.SH SYNOPSIS -.B unlink(name) -.br -.B char *name; -.SH DESCRIPTION -.I Name -points to a null-terminated string. -.I Unlink -removes the entry for the file pointed to by -.I name -from its directory. -If this entry was the last link to the file, -the contents of the file are freed and the file is destroyed. -If, however, the file was open in any process, the actual -destruction is delayed until it is closed, even though -the directory entry has disappeared. -.SH "SEE ALSO" -rm(1), link(2) -.SH DIAGNOSTICS -Zero is normally returned; -\-1 indicates that the file does not -exist, that its directory cannot be written, -or that the file contains pure procedure text -that is currently in use. -Write permission is not required on the file itself. -It is also illegal to unlink a directory -(except for the super-user). -.SH ASSEMBLER -(unlink = 10.) -.br -.B sys unlink; name //GO.SYSIN DD unlink.2 echo utime.2 sed 's/.//' >utime.2 <<'//GO.SYSIN DD utime.2' -.TH UTIME 2 -.SH NAME -utime \- set file times -.SH SYNOPSIS -.B #include -.br -.B utime(file, timep) -.br -.B char *file; -.br -.B time_t timep[2]; -.SH DESCRIPTION -The -.I utime -call -uses the -`accessed' and `updated' times in that order -from the -.I timep -vector -to set the corresponding recorded times for -.I file. -.PP -The caller must be the owner of the file or the super-user. -The `inode-changed' time of the file is set to the current time. -.SH SEE ALSO -stat (2) -.SH ASSEMBLER -(utime = 30.) -.br -.B sys utime; file; timep //GO.SYSIN DD utime.2 echo wait.2 sed 's/.//' >wait.2 <<'//GO.SYSIN DD wait.2' -.TH WAIT 2 -.SH NAME -wait \- wait for process to terminate -.SH SYNOPSIS -.B wait(status) -.br -.B int *status; -.PP -.B wait(0) -.SH DESCRIPTION -.I Wait -causes its caller to delay until a signal is received or -one of its child -processes terminates. -If any child has died since the last -.I wait, -return is immediate; -if there are no children, return is immediate with -the error bit set -(resp. with a value of \-1 returned). -The normal return yields the process ID of the terminated child. -In the case of several children several -.I wait -calls are needed -to learn of all the deaths. -.PP -If -.RI (int) status -is nonzero, the high byte of the word pointed to -receives the low byte of the -argument of -.I exit -when the child terminated. -The low byte -receives the termination status -of the process. -See -.IR signal (2) -for a list of termination statuses (signals); -0 status indicates normal termination. -A special status (0177) is returned for a stopped process -which has not terminated and can be restarted. -See -.IR ptrace (2). -If the 0200 bit of the termination status -is set, -a core image of the process was produced -by the system. -.PP -If the parent process terminates without -waiting on its children, -the initialization process -(process ID = 1) -inherits the children. -.SH "SEE ALSO" -exit(2), fork(2), signal(2) -.SH DIAGNOSTICS -Returns -\-1 if there are no children not previously waited for. -.SH ASSEMBLER -(wait = 7.) -.br -.B sys wait -.br -(process ID in r0) -.br -(status in r1) -.PP -The high byte of the status is -the low byte of r0 in the child at termination. //GO.SYSIN DD wait.2 echo write.2 sed 's/.//' >write.2 <<'//GO.SYSIN DD write.2' -.TH WRITE 2 -.SH NAME -write \- write on a file -.SH SYNOPSIS -.B write(fildes, buffer, nbytes) -.br -.B char *buffer; -.SH DESCRIPTION -A file descriptor is a word returned from a -successful -.I open, -.I creat, -.I dup, -or -.IR pipe (2) -call. -.PP -.I Buffer -is the address of -.I nbytes -contiguous -bytes which are written on the output file. -The number of characters actually written is returned. -It should be regarded as an error -if this is not the same as requested. -.PP -Writes which are multiples -of 512 characters long and begin on a 512-byte boundary -in the file -are more efficient than any others. -.SH "SEE ALSO" -creat(2), open(2), pipe(2) -.SH DIAGNOSTICS -Returns -\-1 on error: bad descriptor, buffer address, or -count; physical I/O errors. -.SH ASSEMBLER -(write = 4.) -.br -(file descriptor in r0) -.br -.B sys write; buffer; nbytes -.br -(byte count in r0) //GO.SYSIN DD write.2