Rexx Open Ed
Rexx Open Ed
Rexx Open Ed
SC28-1905-02
OS/390 IBM
Using REXX and OS/390 OpenEdition
SC28-1905-02
Note
Before using this information and the product it supports, be sure to read the general information under “Notices” on page xi.
| This edition applies to Version 2 Release 5 of OS/390 (5647-A01) and to all subsequent releases and modifications until otherwise
| indicated in new editions or technical newsletters.
Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the
address below.
IBM welcomes your comments. A form for readers' comments may be provided at the back of this publication, or you may address
your comments to the following address:
International Business Machines Corporation
Department 55JA, Mail Station P384
522 South Road
Poughkeepsie, NY 12601-5400
United States of America
If you would like a reply, be sure to include your name, address, telephone number, or FAX number.
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes
appropriate without incurring any obligation to you.
Copyright International Business Machines Corporation 1996, 1998. All rights reserved.
Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to
restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Programming Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Contents v
spawn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
spawnp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
statfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
statvfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
symlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
sysconf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
trunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
ttyname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
umask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
uname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
unlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
unmount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
unquiesce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
utime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
waitpid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
writefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Contents vii
viii OS/390 V2R5.0 OpenEdition Using Rexx and OS/390 OpenEdition
Tables
1. REXX Statements for Defining Signal Sets . . . . . . . . . . . . . . . . . . . 8
2. Three-Digit Permissions Specified in Octal . . . . . . . . . . . . . . . . . 236
IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
500 Columbus Avenue
Thornwood, NY 10594
USA
Licensees of this program who wish to have information about it for the purpose of
enabling: (i) the exchange of information between independently created programs
and other programs (including this one) and (ii) the mutual use of the information
which has been exchanged, should contact:
IBM Corporation
Mail Station P300
522 South Road
Poughkeepsie, NY 12601-5400
USA
Attention: Information Request
Any pointers in this publication to non-IBM Web sites are provided for convenience
and do not in any manner serve as an endorsement of these Web sites.
Programming Interface
This publication documents intended Programming Interfaces that allow the
customer to write programs to obtain services of OS/390 OpenEdition.
Trademarks
The following terms, denoted by an asterisk (*), used in this book, are trademarks
of the IBM Corporation in the United States or other countries or both:
ACF/VTAM
BookManager
C/370
IBM
UNIX is a registered trademark in the United States and other countries licensed
exclusively through X/Open Company Limited.
Other company, product, and service names, which may be denoted by a double
asterisk (**), may be trademarks or service marks of others.
The information contained in the glossary section and tagged by the word [POSIX]
is copyrighted information of the Institute of Electrical and Electronics Engineers,
Inc., extracted from IEEE** Std 1003.1-1990, IEEE P1003.0, and IEEE P1003.2.
This information was written within the context of these documents in their entirety.
The IEEE takes no responsibility or liability for and will assume no liability for any
damages resulting from the reader's misinterpretation of said information resulting
from the placement and context in this publication. Information is reproduced with
the permission of the IEEE.
This book describes the features and usage requirements for the OS/390
OpenEdition REXX extensions, or syscall commands, which are interfaces between
the OS/390 operating system and the functions specified in the POSIX.1 standard
(ISO/IEC 9945-1:1990[E] IEEE Std 1003.1-1990: First edition 1990-12-07;
Information technology—Portable Operating System Interface [POSIX] Part 1;
System Application Program Interface [API] [C Language]). These functions are
used by OS/390 OpenEdition. This book also describes syscall commands that are
not related to the standards.
Direct your request for copies of any IBM publication to your IBM representative or
to the IBM branch office serving your locality.
Softcopy Publications
The OpenEdition library is available on the OS/390 Collection Kit, SK2T-6700. This
softcopy collection contains a set of OS/390 and related unlicensed product books.
The CD-ROM collection includes the IBM Library Reader, a program that enables
customers to read the softcopy books.
Softcopy OS/390 publications are also available for web-browsing at this URL:
http://www.s39ð.ibm.com/os39ð/license.html
These books have not been subjected to any formal review nor have they been
checked for technical accuracy, but they represent current product understanding
(at the time of their publication) and provide valuable information on a wide range
of OpenEdition topics. You must order them separately. A selected list of these
books follows:
Selecting a Server — The Value of S/390, SG24-4812
OS/390 TCP/IP OpenEdition Implementation Guide, SG24-2141. Written for
OS/390 TCP/IP OpenEdition, a replacement for TCP/IP for MVS Version 3
Release 2 Application Feature.
Accessing OS/390 OpenEdition MVS from the Internet, SG24-4721. Written for
TCP/IP for MVS Version 3 Release 2 Application Feature.
MVS/ESA SP 5.2.2 OpenEdition MVS Installation and Customization Starter
Kit, SG24-4529
Porting Applications to the OpenEdition MVS Platform, GG24–4473. This book
was written for the OpenEdition MVS feature of MVS/ESA SP 5.1.
OpenEdition Courses
The following classroom course is available:
UNIX System Services for OS/390 Implementation, ESP25
or
http://www.s39ð.ibm.com/oe/
Some of the tools available from the web site are ported tools, and some are
home-grown tools designed for OpenEdition. All this code works in our environment
at the time we make it available, but is not officially supported. Each tool has a
README file that describes the tool and any restrictions on its use.
The simplest way to reach these tools is through the OpenEdition home page.
From the home page, click on the Tools and Toys icon.
Restrictions
To preview or sign up for TalkLink, access this URL using a secure web browser:
http://www.ibmlink.ibm.com/talklink
Web Access:
1. Go to http://www.ibmlink.ibm.com/talklink.
2. Click on Logon.
3. After logon, select Martlink.
4. Choose S390 from the menu.
5. Choose MVS from the menu.
6. Choose MVSSYSTEM from the menu.
7. Choose MVSFORUMS from the menu.
8. Choose OPENMVS from the menu.
Discussion List
Customers and IBM participants also discuss OpenEdition on the mvs-oe
discussion list. This list is not operated or sponsored by IBM; it is run by
Georgetown University.
To subscribe to the mvs-oe discussion so you can receive postings, send a note to:
listserv@listserv.georgetown.edu
Include the following line in the body of the note, substituting your first name and
last name as indicated:
After you are subscribed, you will receive further instructions on how to use the
mailing list.
You can run a REXX program with syscall commands only on a system with
OS/390 OpenEdition installed.
A REXX program is recognized by the word REXX (not case-sensitive) as the first
word on the first line and within a REXX comment. For example, the following is a
simple REXX program:
/\ rexx \/
say 'hello world'
You can run an interpreted or compiled REXX program with syscall commands
from TSO/E, from MVS batch, from the shell, or from a program.
When a REXX program is run from the shell or from a program, both the SH and
SYSCALL host command environments are available to it. When a REXX program
is run from TSO/E or MVS batch, only the SYSCALL environment is available.
For REXX programs run from TSO/E or MVS batch, you use the syscalls() function
to control the SYSCALL host command environment. You control the SYSCALL
environment by using:
syscalls('ON') to establish the SYSCALL environment
syscalls('OFF') to end the SYSCALL environment
syscalls('SIGON') to establish the signal interface routine
syscalls('SIGOFF') to delete the signal interface routine
Note: The words ON, OFF, SIGON, and SIGOFF must be in uppercase letters.
The following example shows how you can use the syscalls('ON') function at the
beginning of a REXX program:
if syscalls('ON')>3 then
do
say 'Unable to establish the SYSCALL environment'
return
end
If you are writing a REXX program that runs a program that requires a signal
interface routine (for example, a program that uses the C runtime library), you must
delete the SIR. The syscalls('SIGOFF') function deletes the SIR and uses
sigprocmask() to reset the signal process mask so that it blocks all signals that
can be blocked.
The SH Environment
The SH environment is the default host command environment when a REXX
program is run from the shell or from a program using exec(). In this environment, a
syscall command runs as a shell command that has been issued this way:
/bin/sh -c shell_command
If you are running the REXX program from the shell or a program, the SYSCALL
environment is automatically initialized.
See Chapter 4 for some sample REXX programs that show how REXX and shell
commands can work together—for example, a REXX program that can read output
A REXX program invoked from the shell or from a program must be a text file or
compiled REXX program that resides in the hierarchical file system (HFS); it must
have read and execute access permissions. Each line in the text file must be
terminated by a newline character and should not exceed 2048 characters. Lines
are passed to the REXX interpreter as is. Sequence numbers are not supported, so
if you are using the ISPF editor to create the REXX program, be sure to set
NUMBER OFF.
If you are working in the shell environment and use only a filename to invoke the
REXX program, the PATH environment variable is used to locate it. For example,
myrexx uses PATH to locate the program, but ./myrexx searches only the working
directory.
For a REXX program run from the shell or from a program, the SIR is established
by default. If the REXX program calls a C program that is running POSIX(ON) or a
program that requires an SIR, use the syscalls('SIGOFF') function to delete the
SIR before calling that program.
CEXEC output from the REXX compiler is supported in the shell environment. To
compile and put CEXEC output into the HFS, you can use the REXXOEC
cataloged procedure; it compiles under TSO/E and then uses the TSO/E OCOPY
command to copy the compiled program from a data set to a file in the file
hierarchy.
The search order for modules and execs invoked as functions or subroutines is
controlled by the FUNCSOFL flag in the REXX parameter module. For a description
of that flag, see OS/390 TSO/E REXX Reference.
Variable Scope
When the REXX program is initialized and the SYSCALL environment is
established, the predefined variables are set up. If you call an internal subroutine
that uses the PROCEDURE instruction to protect existing variables by making them
unknown to that subroutine (or function), the predefined variables also become
unknown. If some of the predefined variables are needed, you can either list them
on the PROCEDURE EXPOSE instruction or issue another syscalls('ON') to
reestablish the predefined variables. The predefined variables are automatically set
up for external functions and subroutines. For example:
subroutine: procedure
junk = syscalls('ON')
parse arg dir
'readdir (dir) dir. stem.'
Just like any other setuid or setgid program, a REXX program should not let the
user of the program get control in your environment. Some examples of instructions
that can let a user obtain control are:
Interactive trace.
Calling external functions or subroutines: Using a relative pathname can let the
user get control if the user sets the PATH variable. External functions and
subroutines run under the UID and GID of the main program, regardless of
their setuid and setgid mode bits.
If the REXX program issues a SAY instruction, the text is directed to standard
output, and a newline character is appended to the end of the text. Messages
issued by REXX, including error and trace messages, are similarly directed to
standard output.
If PARSE EXTERNAL is used after standard input has reached the end of the file,
null lines are returned. The end-of-file condition can be detected by EXECIO. For
more information, see “Using EXECIO.”
Using EXECIO
EXECIO differs from readfile and writefile in that it operates on open files. To read
or write a file in segments (for example, a line at a time), use this TSO/E REXX
command:
address MVS "EXECIO"
The data can come from and go to the stack or a stem. You can also use it to read
or write an entire file. As shown in the following diagram, OS/390 OpenEdition
supports all the TSO/E REXX operands except OPEN, DISKRU, and linenum.
For the ddname operand, you can use the following pseudo-ddnames for OS/390
OpenEdition processing, when run from the shell or a program:
File descriptors 0 to 7
STDIN, STDOUT, STDERR
REXX does not include a service that allows you to attach your own signal catcher.
Instead, you have the following options:
To use the REXX signal catcher as the action for a signal, you can specify the
SIG_CAT variable as the signal handler on sigaction.
SIG_CAT can terminate various wait conditions without causing the process to
end. If a signal arrives when the process is not currently waiting and the signal
is not blocked, it may be lost.
There are two primary uses for SIG_CAT: when you are using the alarm
command, and when you want to avoid unexpected process termination for
other unblocked signals.
SIG_CAT causes a signal to interrupt conditions such as waits and blocks, but
the application cannot determine which signal was delivered. It is not a
traditional signal catcher, as implemented in the C language.
To set the action to the default action, you can specify SIG_DFL as the signal
handler on sigaction.
To set the action to ignore the signal, you can specify SIG_IGN as the signal
handler on sigaction.
POSIX.1 defines several C functions to manipulate signal sets. REXX does not
define these functions; however, you can define each function using a single REXX
statement, as shown in Table 1.
PGM2:
/\ rexx \/
say 'This is pgm2'
say 'Using _ _argv stem, there are' _ _argv.ð 'arguments. They are:'
do i = 1 to _ _argv.ð
say ' Argument' i': "'_ _argv.i'"'
end
Sample Execution
$ pgm1 'arguments to' 'pgm1'
this is the main pgm
it was passed 3 arguments:
Argument 1: "pgm1"
Argument 2: "arguments to"
Argument 3: "pgm1"
This is pgm2
Using _ _argv stem, there are 3 arguments. They are:
Argument 1: "pgm1"
Argument 2: "arguments to"
Argument 3: "pgm1"
Using arg(), there are 2 arguments:
Argument 1: "arguments"
Argument 2: "to pgm2"
This environment is inherited from the default MVS REXX environment. However,
the default handling of error messages from the REXX processor is overridden so
that the messages are written to STDOUT. This is the same place to which output
from the SAY instruction and trace information is sent.
You can further customize the sample member to alter the REXX environment for
REXX programs running under OS/390 OpenEdition without affecting REXX
programs running in the OS/390 environment. For detailed information on how to
change the default values for initializing an environment, see OS/390 TSO/E REXX
Reference.
Performance characteristics for dynamically added host commands are not as good
as for host commands that are included in the initial environment: Every time a
command is directed to the SYSCALL host command environment, the TSO/E
REXX support loads the module for the SYSCALL host command.
To avoid this, include the SYSCALL host command in the three default TSO/E
environments:
Make the following changes to the SYS1.SAMPLIB members to add the SYSCALL
host command to that default environment:
1. Find the label SUBCOMTB_TOTAL and add 1 to its value. For example:
2. Find the label SUBCOMTB_USED and add 1 to its value. For example:
3. Find the end of the subcommand table, just before the label PACKTB or
PACKTB_HEADER, and add the following lines:
SUBCOMTB_NAME_REXXIX DC CL8'SYSCALL '
SUBCOMTB_ROUTINE_REXXIX DC CL8'BPXWREXX'
SUBCOMTB_TOKEN_REXXIX DC CL16' '
4. Assemble and link-edit the module and replace the default TSO/E module.
These are normally installed in SYS1.LPALIB.
See OS/390 TSO/E REXX Reference for additional information on customizing the
default environments.
Authorization
Users authorized to perform special functions are defined as having appropriate
privileges, and they are called superusers. Appropriate privileges also belong to
users with:
A user ID of zero
RACF-supported user privileges trusted and privileged, regardless of their user
ID
Security
This book assumes that your operating system contains Resource Access
Control Facility (RACF). You could use an equivalent security product updated
to handle OS/390 OpenEdition security.
The parameter list is a standard MVS variable-length parameter list. On entry, the
following registers must be set:
Register 1 Address of the parameter list
Register 13 Address of a register save area
Register 14 Return address
Register 15 Entry point address
Register 1 contains the address of the parameter list:
R1 --> --------+
| --+----> 16K area
--------+
| --+----> arg count
--------+
| --+----> arg pointer array
--------+
| --+----> env count
--------+
| --+----> env length pointer array
--------+
| --+----> env pointer array
--------+
|1 --+----> Rexx env addr
--------+
When constructing arguments to the REXX program that are also passed to
BPXWRBLD, keep in mind that:
The only use of the the argument count and argument array is to populate the
_ _argv. REXX variables. You can set the argument count to ð if the REXX
programs will always get their arguments using PARSE ARG or the arg(1)
REXX function call. In this case, _ _argv.0 is set to ð when the REXX program
is run.
After the call to BPXWRBLD, do not alter the data that is pointed to by the
environment pointer arrays or the arg pointer array.
After the OS/390 OpenEdition REXX environment is established, the program can
call either the IRXJCL or the IRXEXEC TSO/E REXX service to run the REXX
program.
If the IRXJCL service is used, the name of the REXX program is the first word
of the IRXJCL parameter string. It is limited to 8 characters.
When the REXX program is being loaded, the IRXEXEC or the IRXJCL service
uses one file descriptor to open the file, read it, and close it. If no file descriptor is
available because the maximum number of file descriptors are already open, the
program cannot be loaded.
/\ if stdin or stdout are not open you might want to open file \/
/\ descriptors ð and 1 here \/
/\ load routines \/
irxjcl=(EXTF \)fetch("IRXJCL ");
bpxwrbld=(EXTF \)fetch("BPXWRBLD ");
/\ run exec \/
rxparm=(struct s_rxparm \)malloc(strlen(execname)+
strlen(execparm)+
sizeof(struct s_rxparm));
memset(rxparm->name,' ',sizeof(rxparm->name));
memcpy(rxparm->name,execname,strlen(execname));
rxparm->space=' ';
memcpy(rxparm->text,execparm,i=strlen(execparm));
rxparm->len=sizeof(rxparm->name)+sizeof(rxparm->space)+i;
return irxjcl(rxparm);
}
Parameters
You can specify several types of parameters, but most fall into the following
categories:
Specifying Numerics
All numbers are numeric REXX strings. Negative numbers can be preceded by a
minus sign (−); others must be unsigned.
Specifying Strings
You can specify a string in any of these ways:
String Example
Any series of characters not containing a "creat /u/wjs/file 7ðð"
space. This example shows a pathname
with no space in it.
Any series of characters delimited by ' and "creat 'u/wjs/my file' 7ðð"
not containing '. This example shows a
pathname with a space in it.
Any series of characters delimited by " and 'creat "u/wjs/my file" 7ðð'
not containing ". This example shows a
pathname with a space in it.
A variable name enclosed in parentheses. file='/u/wjs/my file'
Strings containing both the single and "creat (file) 7ðð"
double quote characters must be stored in a
variable, and you must use the variable
name.
Appendix A lists all the predefined variables alphabetically and shows their numeric
value and data type. If a variable is a stem variable, this shows the data type for
the stem variable.
You can also use the index of this book as a reference: under the name of each
syscall command are grouped the names of the predefined variables associated
with it.
Return Values
A command can be issued to the SYSCALL environment or the SH environment,
and the return values are different in the two environments.
access
55──access──pathname──flags────────────────────────────────────────5%
Function
access invokes the access callable service to determine if the caller can access a
file.
Parameters
pathname
The pathname of the file to be checked for accessibility.
flags
One or more numeric values that indicate the accessibility to be tested. You
can specify a numeric value (see Appendix A) or the predefined variable used
to derive the appropriate numeric value. The predefined variables you can
specify are:
Variable Description
F_OK Test for file existence
R_OK Test for permission to read
W_OK Test for permission to write
X_OK Test for permission to execute
Usage Notes
1. Testing for file permissions is based on the real user ID (UID) and real group ID
(GID), not the effective UID or effective GID of the calling process.
2. The caller can test for the existence of a file or for access to the file, but not
both.
3. In testing for permission, the caller can test for any combination of read, write,
and execute permission. If the caller is testing a combination of permissions, a
−1 is returned if any one of the accesses is not permitted.
4. If the caller has appropriate privileges, the access test is successful even if the
permission bits are off, except when testing for execute permission. When the
caller tests for execute permission, at least one of the execute permission bits
must be on for the test to be successful.
Example
To test for permission to execute grep:
"access '/bin/grep'" x_ok
alarm
55──alarm──seconds─────────────────────────────────────────────────5%
Function
alarm invokes the alarm callable service to generate a SIGALRM signal after the
number of seconds specified have elapsed.
Parameters
seconds
The number of seconds to pass between receipt of this request and generation
of the SIGALRM signal.
Usage Notes
1. The default action for an alarm signal is to end a process.
2. The alarm callable service is always successful, and no return value is reserved
to indicate an error.
3. An abend is generated when failures are encountered that prevent the alarm
callable service from completing successfully.
4. Alarm requests are not stacked; only one SIGALRM can be scheduled to be
generated at a time. If the previous alarm time did not expire and a new alarm
is scheduled, the most recent alarm reschedules the time that SIGALRM is
generated.
5. See “Using the REXX Signal Services” on page 8 for additional information on
using signals.
Example
To generate a SIGALRM after 10 seconds:
"alarm 1ð"
catclose
55──catclose──catalog_descriptor───────────────────────────────────5%
Function
catclose closes a message catalog that was opened by catopen.
Parameters
catalog_descriptor
The catalog descriptor (a number) returned by catopen when the message
catalog was opened.
Usage Notes
If unsuccessful, catclose returns −1 and sets ERRNO to indicate the error.
Example
See the example for “catgets” on page 24.
catgets
55──catgets──catalog_descriptor──set_number─────────────────────────5
5──message_number──variable────────────────────────────────────────5%
Function
catgets locates and returns a message in a message catalog.
Parameters
catalog_descriptor
The catalog descriptor (a number) returned by catopen when a message
catalog was opened earlier.
set_number
A number that identifies a message set in the message catalog.
message_number
A number that identifies a message in a message set in the message catalog.
variable
The name of the buffer in which the message string is returned.
Usage Notes
1. Set variable to a default message text prior to invoking the catgets command.
If the message identified by message_number is not found, variable is not
altered and can be used after the command has been invoked.
2. If the command is unsuccessful, variable is returned and ERRNO may be set to
indicate the error.
Example
"catopen mymsgs.cat"
cd=retval
..
.
msg='error processing request'
"catgets (cd) 1 3 msg"
say msg
..
.
"catclose" cd
catopen
55──catopen──catalog_name──────────────────────────────────────────5%
Function
catopen opens a message catalog that has been built by the gencat utility. (For
more information about gencat, see OS/390 OpenEdition Command Reference.)
The catalog descriptor is returned in RETVAL.
Parameters
catalog name
The pathname for the message catalog. If the pathname contains a slash (/),
the environment variables NLSPATH and LANG do not affect the resolution of
the pathname.
Usage Notes
1. The catalog descriptor returned in RETVAL can be used with the catgets and
catclose commands. Do not use the catalog descriptor with any other
commands.
2. If unsuccessful, catopen returns a −1 and sets ERRNO to indicate the error.
Example
See the example for “catgets” on page 24.
chattr
55──chattr──pathname──attribute_list───────────────────────────────5%
Function
chattr invokes the chattr callable service to set the attributes associated with a file.
You can change the file mode, owner, access time, modification time, change time,
reference time, audit flags, general attribute flags, and file size.
Parameters
pathname
The pathname of the file.
attribute_list
A list of attributes to be set and their values. The attributes are expressed
either as numeric values (see Appendix A), or as the predefined variables
beginning with ST_, followed by arguments for that attribute. The attributes that
may be changed and their parameters are:
Variable Description
ST_MODE 1 argument: permission bits as 3 octal digits.
ST_UID 2 arguments: UID and GID numbers.
ST_SIZE 1 argument: new file size.
ST_ATIME 1 argument for access time: new time or −1 for TOD.
ST_MTIME 1 argument for modification time: new time or −1 for TOD.
ST_CTIME 1 argument for change time: new time or −1 for TOD.
ST_SETUID No arguments.
ST_SETGID No arguments.
ST_AAUDIT 1 argument: new auditor audit value.
ST_UAUDIT 1 argument: new user audit value.
ST_STICKY No arguments.
ST_GENVALUE 2 arguments: names of two variables. The first variable
contains the general attribute mask and the second
contains the general attribute value.
ST_RTIME 1 argument for reference time: new time or −1 for TOD.
| ST_FILEFMT Format of the file. To specify the format, you can specify a
numeric value (see Appendix A) or one of the following
predefined variables used to derive the appropriate numeric
value:
| S_FFBINARY Binary data
S_FFCR Text data delimited by a carriage return
character
S_FFCRLF Text data delimited by carriage return and
line feed characters
S_FFLF Text data delimited by a line feed
character
S_FFLFCR Text data delimited by a line feed and
carriage return characters
S_FFNA Text data with the file format not specified
S_FFNL Text data delimited by a newline character
Usage Notes
1. Some of the attributes changed by the chattr service can also be changed by
other services.
2. When changing the mode:
The effective UID of the calling process must match the file's owner UID, or
the caller must have appropriate privileges.
Setting the set-group-ID-on-execution permission (in mode) means that
when this file is run (through the exec service), the effective GID of the
caller is set to the file's owner GID, so that the caller seems to be running
under the GID of the file, rather than that of the actual invoker.
The set-group-ID-on-execution permission is set to zero if both of the
following are true:
– The caller does not have appropriate privileges.
– The GID of the file's owner does not match the effective GID, or one of
the supplementary GIDs, of the caller.
Setting the set-user-ID-on-execution permission (in mode) means that when
this file is run, the process's effective UID is set to the file's owner UID, so
that the process seems to be running under the UID of the file's owner,
rather than that of the actual invoker.
3. When changing the owner:
For changing the owner UID of a file, the caller must have appropriate
privileges.
For changing the owner GID of a file, the caller must have appropriate
privileges, or meet all of these conditions:
– The effective UID of the caller matches the file's owner UID.
– The owner UID value specified in the change request matches the file's
owner UID.
– The GID value specified in the change request is the effective GID, or
one of the supplementary GIDs, of the caller.
When changing the owner, the set-user-ID-on-execution and
set-group-ID-on-execution permissions of the file mode are automatically
turned off.
When the owner is changed, both UID and GID must be specified as they
are to be set. If you want to change only one of these values, you need to
set the other to its present value for it to remain unchanged.
4. For general attribute bits to be changed, the calling process must have write
permission for the file.
5. When changing the file size:
The change is made beginning from the first byte of the file. If the file was
previously larger than the new size, the data from file_size to the original
end of the file is removed. If the file was previously shorter than file_size,
bytes between the old and new lengths are read as zeros. The file offset is
not changed.
If file_size is greater than the current file size limit for the process, the
request fails with EFBIG, and the SIGXFSZ signal is generated for the
process.
Successful change clears the set-user-ID, the set-group-ID, and the
save-text (sticky bit) attributes of the file, unless the caller is a superuser.
6. When changing times:
For the access time or the modification time to be set explicitly (using either
st_atime or st_mtime with the new time), the effective ID must match that of
the file's owner, or the process must have appropriate privileges.
For the access time or modification time to be set to the current time (using
either st_atime or st_mtime with −1), the effective ID must match that of the
file's owner, the calling process must have write permission for the file, or
the process must have appropriate privileges.
For the change time or the reference time to be set explicitly (using either
st_ctime or st_rtime with the new time), the effective ID must match that of
the file's owner, or the process must have appropriate privileges.
For the change time or reference time to be set to the current time (using
either st_ctime or st_rtime with −1), the calling process must have write
permission for the file.
When any attribute field is changed successfully, the file's change time is
updated as well.
7. For auditor audit flags to be changed, the user must have auditor authority. The
user with auditor authority can set the auditor options for any file, even those to
which they do not have path access or authority to use for other purposes.
Auditor authority is established by issuing the TSO/E command ALTUSER
AUDITOR.
8. For the user audit flags to be changed, the user must have appropriate
privileges or be the owner of the file.
Example
To set permissions for /u/project to 775:
"chattr /u/project" st_mode 775
chaudit
55──chaudit──pathname──audit_flags──option─────────────────────────5%
Function
chaudit invokes the chaudit callable service to change audit flags for a file.
Parameters
pathname
The pathname of the file.
audit_flags
One or more numeric values that indicate the type of access to be tested. You
can specify a numeric value (see Appendix A) or the predefined variable used
to derive the appropriate numeric value. The predefined variables you can
specify are:
Variable Description
AUD_FREAD Audit failed read requests
AUD_SREAD Audit successful read requests
AUD_FWRITE Audit failed write requests
AUD_SWRITE Audit successful write requests
AUD_FEXEC Audit failed execute or search requests
AUD_SEXEC Audit successful execute or search requests
option
A number indicating whether user-requested or auditor-requested auditing is
being changed:
Usage Notes
1. If option indicates that the auditor audit flags are to be changed, you must have
auditor authority for the request to be successful. If you have auditor authority,
you can set the auditor options for any file, even those to which you do not
have path access or authority to use for other purposes.
You can get auditor authority by entering the TSO/E command ALTUSER
AUDITOR.
2. If option indicates that the user audit flags are to be changed, you must have
appropriate privileges or be the owner of the file.
Example
In the following example, assume that pathname was assigned a value earlier in
the exec. To change user-requested auditing so that failed read, write, and execute
attempts for pathname are audited:
"chaudit (pathname)" aud_fread+aud_fwrite+aud_fexec ð
chdir
55──chdir──pathname────────────────────────────────────────────────5%
Function
chdir invokes the chdir callable service to change the working directory.
Parameters
pathname
The pathname of the directory.
Usage Notes
If you use chdir to change a directory in a REXX program that is running in a
TSO/E session, the directory is typically reset to your home directory when the
REXX program ends. When a REXX program changes directories and then exits,
the thread is undubbed. If this was the only thread dubbed in your TSO/E session,
the working directory is reset to the home directory the next time a syscall
command is issued. However, if there is more than one dubbed thread in the
address space, the remaining threads keep the working directory even when the
REXX program exits.
Example
To change the working directory to /u/lou/dirb:
"chdir /u/lou/dirb"
chmod
55──chmod──pathname──mode──┬────────────────────────────┬──────────5%
└─setuid──setgid──┬────────┬─┘
└─sticky─┘
Function
chmod invokes the chmod callable service to change the mode of a file or
directory.
Parameters
pathname
The pathname of the file or directory.
mode
A three- or four-digit number, corresponding to the access permission bits.
Each digit must be in the range ð–7, and at least three digits must be specified.
For more information on permissions, see Appendix B.
setuid
Sets the set-user-ID-on-execution permission. Specify 1 to set this permission
on, or ð to set it off. The default is ð.
setgid
Sets the set-group-ID-on-execution permission. Specify 1 to set this permission
on, or ð to set it off. The default is ð.
sticky
The sticky bit for a file indicates where the file should be fetched from. If the
file resides in the link pack area (LPA), link list, or STEPLIB, specify 1. The
default is ð.
Setting the sticky bit for a directory to 1 indicates that to delete or rename a file,
the effective user ID of the process must be the same as that of the directory
owner or file owner, or that of a superuser. Setting the sticky bit for a directory
to ð indicates that anyone who has write permission to the directory can delete
or rename a file.
Usage Notes
1. One bit sets permission for set-user-ID on access, set-group-ID on access, or
the sticky bit. You can set this bit in either of two ways:
Specifying four digits on the mode parameter; the first digit sets the bit.
Specifying the setuid, setgid, or sticky parameters.
2. When a chmod or fchmod has occurred for an open file, fstat reflects the
change in mode. However, no change in access authorization is apparent when
the file is accessed through a previously opened file descriptor.
3. For mode bits to be changed, the effective UID of the caller must match the
file's owner UID, or the caller must be a superuser.
4. When the mode is changed successfully, the file's change time is updated as
well.
5. Setting the set-group-ID-on-execution permission means that when this file is
run (through the exec service), the effective GID of the caller is set to the file's
owner GID, so that the caller seems to be running under the GID of the file,
rather than that of the actual invoker.
The set-group-ID-on-execution permission is set to zero if both of the following
are true:
The caller does not have appropriate privileges.
The GID of the file's owner does not match the effective GID or one of the
supplementary GIDs of the caller.
6. Setting the set-user-ID-on-execution permission means that when this file is
run, the process's effective UID is set to the file's owner UID, so that the
process seems to be running under the UID of the file's owner, rather than that
of the actual invoker.
Example
In the following example, assume that pathname was assigned a value earlier in
the exec. This example changes the mode of the file to read-write-execute for the
owner, and read-execute for all others:
"chmod (pathname) 755"
chown
55──chown──pathname──uid──gid──────────────────────────────────────5%
Function
chown invokes the chown callable service to change the owner or group for a file
or directory.
Parameters
pathname
The pathname of a file or directory.
uid
The numeric UID for the new owner of the file or the present UID, or −1 if there
is no change.
gid
The numeric GID for the group for the file or the present GID, or −1 if there is
no change.
Usage Notes
1. The chown service changes the owner UID and owner GID of a file. Only a
superuser can change the owner UID of a file.
2. The owner GID of a file can be changed by a superuser, or if a caller meets all
of these conditions:
The effective UID of the caller matches the file's owner UID.
The uid value specified in the change request matches the file's owner UID.
The gid value specified in the change request is the effective GID, or one
of the supplementary GIDs, of the caller.
3. The set-user-ID-on-execution and set-group-ID-on-execution permissions of the
file mode are automatically turned off.
4. If the change request is successful, the change time for the file is updated.
5. Values for both uid and gid must be specified as they are to be set. If you want
to change only one of these values, the other must be set to its present value
to remain unchanged.
Example
In the following example, assume that pathname, uid, and gid were assigned a
value earlier in the exec:
"chown (pathname) (uid) (gid)"
close
55──close──fd──────────────────────────────────────────────────────5%
Function
close invokes the close callable service to close a file.
Parameters
fd The file descriptor (a number) for the file to be closed.
Usage Notes
1. Closing a file closes, or frees, the file descriptor by which the file was known to
the process. The system can then reassign the file descriptor to the same file
or to another file when it is opened.
2. Closing a file descriptor also unlocks all outstanding byte range locks that a
process has on the associated file.
3. If a file has been opened by more than one process, each process has a file
descriptor. When the last open file descriptor is closed, the file itself is closed. If
the file's link count is zero at that time, the file's space is freed and the file
becomes inaccessible. When the last open file descriptor for a pipe or FIFO
special file is closed, any data remaining in the file is discarded.
Example
In the following example, assume that fd was assigned a value earlier in the exec:
"close" fd
closedir
55──closedir──fd───────────────────────────────────────────────────5%
Function
closedir invokes the closedir callable service to close a directory.
Parameters
fd The file descriptor (a number) for the directory to be closed.
Usage Notes
closedir closes a directory file descriptor opened by the opendir syscall command.
The rddir command reads a directory in the readdir callable service format. You
can use opendir, rewinddir, and closedir together with the rddir syscall
command, but not with the readdir syscall command. Alternatively, you can simply
use the readdir syscall command to read an entire directory and format it in a
stem.
Example
In the following example, assume that fd was assigned a value earlier in the exec:
"closedir" fd
creat
55──creat──pathname──mode──────────────────────────────────────────5%
Function
creat invokes the open callable service to open a new file. The file descriptor is
returned in RETVAL.
Parameters
pathname
The pathname of a file.
mode
A three- or four-digit number, corresponding to the access permission bits.
Each digit must be in the range ð–7, and at least three digits must be specified.
For more information on permissions, see Appendix B.
Usage Notes
Using creat is the equivalent of using the open callable service with the create,
truncate, and write-only options:
When a file is created with the create option, the file permission bits as
specified in mode are modified by the process's file creation mask (see “umask”
on page 165) and then used to set the file permission bits of the file being
created.
The truncate option opens the file as though it had been created earlier, but
never written into. The mode and owner of the file do not change (although the
change time and modification time do), but the file's contents are discarded.
The file offset, which indicates where the next write is to occur, points to the
first byte of the file.
Example
To open a new file, /u/lou/test.exec, with read-write-execute permission for the
owner only:
"creat /u/lou/test.exec 7ðð"
dup
55──dup──fd────────────────────────────────────────────────────────5%
Function
dup invokes the fcntl callable service to duplicate an open file descriptor. The file
descriptor is returned in RETVAL.
Parameters
fd An opened file descriptor (a number) to be duplicated.
Usage Notes
dup fd is equivalent to F_DUPFD fd ð.
Example
In the following example, assume that fd was assigned a value earlier in the exec:
"dup (fd)"
dup2
55──dup2──fd──fd2──────────────────────────────────────────────────5%
Function
dup2 invokes the fcntl callable service to duplicate an open file descriptor to the file
descriptor of choice. The file descriptor returned is equal to fd2. If fd2 is already in
use, it is closed and fd is duplicated. If fd is equal to fd2, fd2 is returned without
closing it. The file descriptor is returned in RETVAL.
Parameters
fd An opened file descriptor (a number) to be duplicated.
fd2
The file descriptor (a number) to be changed.
Usage Notes
dup fd fd2 is equivalent to F_DUPFD fd fd2.
Example
In the following example, assume that fd1 and fd2 were assigned values earlier in
the exec:
"dup2" fd1 fd2
exec
There is no exec syscall command. Instead of using exec, see “spawn” on
page 151.
extlink
55──extlink──extname──linkname─────────────────────────────────────5%
Function
extlink invokes the extlink callable service to create a symbolic link to an external
name. This creates a symbolic link file.
Parameters
extname
The external name of the file for which you are creating a symbolic link.
linkname
The pathname for the symbolic link.
Usage Notes
1. The object identified by extname need not exist when the symbolic link is
created, and refers to an object outside a hierarchical file system.
2. The external name contained in an external symbolic link is not resolved. The
linkname cannot be used as a directory component of a pathname.
Example
To create a symbolic link named mydsn for the file WJS.MY.DSN:
"extlink WJS.MY.DSN /u/wjs/mydsn"
fchattr
55──fchattr──fd──attribute_list────────────────────────────────────5%
Function
fchattr invokes the fchattr callable service to modify the attributes that are
associated with a file represented by a file descriptor. You can change the mode,
owner, access time, modification time, change time, reference time, audit flags,
general attribute flags, and file size.
Parameters
fd The file descriptor for the file.
attribute_list
A list of attributes to be set and their values. The attributes are expressed
either as numeric values (see Appendix A), or as the predefined variables
beginning with ST_ followed by arguments for that attribute. The attributes that
may be changed and their parameters are:
Variable Description
ST_MODE 1 argument: permission bits as 3 octal digits.
ST_UID 2 arguments: UID and GID numbers.
ST_SIZE 1 argument: new file size.
ST_ATIME 1 argument for access time: new time or −1 for TOD.
ST_MTIME 1 argument for modification time: new time or −1 for TOD.
ST_CTIME 1 argument for change time: new time or −1 for TOD.
ST_SETUID No arguments.
ST_SETGID No arguments.
ST_AAUDIT 1 argument: new auditor audit value.
ST_UAUDIT 1 argument: new user audit value.
ST_STICKY No arguments.
ST_GENVALUE 2 arguments: names of two variables. The first variable
contains the general attribute mask and the second
contains the general attribute value.
ST_RTIME 1 argument for reference time: new time or −1 for TOD.
| ST_FILEFMT Format of the file. To specify the format, you can specify a
numeric value (see Appendix A) or one of the following
predefined variables used to derive the appropriate numeric
value:
| S_FFBINARY Binary data
S_FFCR Text data delimited by a carriage return
character
S_FFCRLF Text data delimited by carriage return and
line feed characters
S_FFLF Text data delimited by a line feed
character
S_FFLFCR Text data delimited by a line feed and
carriage return characters
S_FFNA Text data with the file format not specified
S_FFNL Text data delimited by a newline character
Usage Notes
1. Some of the attributes changed by the fchattr service can also be changed by
other services.
2. When changing the mode:
The effective UID of the calling process must match the file's owner UID, or
the caller must have appropriate privileges.
Setting the set-group-ID-on-execution permission (in mode) means that
when this file is run (through the exec service), the effective GID of the
caller is set to the file's owner GID, so that the caller seems to be running
under the GID of the file, rather than that of the actual invoker.
The set-group-ID-on-execution permission is set to zero if both of the
following are true:
– The caller does not have appropriate privileges.
– The GID of the file's owner does not match the effective GID, or one of
the supplementary GIDs, of the caller.
Setting the set-user-ID-on-execution permission (in mode) means that when
this file is run, the process's effective UID is set to the file's owner UID, so
that the process seems to be running under the UID of the file's owner,
rather than that of the actual invoker.
3. When changing the owner:
For changing the owner UID of a file, the caller must have appropriate
privileges.
For changing the owner GID of a file, the caller must have appropriate
privileges, or meet all of these conditions:
– The effective UID of the caller matches the file's owner UID.
– The owner UID value specified in the change request matches the file's
owner UID.
– The GID value specified in the change request is the effective GID, or
one of the supplementary GIDs, of the caller.
When the owner is changed, the set-user-ID-on-execution and
set-group-ID-on-execution permissions of the file mode are automatically
turned off.
When the owner is changed, both UID and GID must be specified as they
are to be set. If you want to change only one of these values, you need to
set the other to its present value for it to remain unchanged.
4. For general attribute bits to be changed, the calling process must have write
permission for the file.
5. When changing the file size:
The change is made beginning from the first byte of the file. If the file was
previously larger than the new size, the data from file_size to the original
end of the file is removed. If the file was previously shorter than file_size,
bytes between the old and new lengths are read as zeros. The file offset is
not changed.
If file_size is greater than the current file size limit for the process, the
request fails with EFBIG and the SIGXFSZ signal is generated for the
process.
Successful change clears the set-user-ID, set-group-ID, and sa ve-text
(sticky bit) attributes of the file unless the caller is a superuser.
6. When changing times:
For the access time or the modification time to be set explicitly (using either
st_atime or st_mtime with the new time), the effective ID must match that of
the file's owner, or the process must have appropriate privileges.
For the access time or modification time to be set to the current time (using
either st_atime or st_mtime with −1), the effective ID must match that of the
file's owner, the calling process must have write permission for the file, or
the process must have appropriate privileges.
For the change time or the reference time to be set explicitly (using either
st_ctime or st_rtime with the new time) the effective ID must match that of
the file's owner, or the process must have appropriate privileges.
For the change time or reference time to be set to the current time (using
either st_ctime or st_rtime with −1), the calling process must have write
permission for the file.
When any attribute field is changed successfully, the file's change time is
updated as well.
7. For auditor audit flags to be changed, the user must have auditor authority. The
user with auditor authority can set the auditor options for any file, even those to
which they don't have path access or authority to use for other purposes.
Auditor authority is established by issuing the TSO/E command ALTUSER
AUDITOR.
8. For the user audit flags to be changed, the user must have appropriate
privileges or be the owner of the file.
Example
In the following example, assume that fd was assigned a value earlier in the exec.
This truncates a file to ð bytes and sets the file permissions to 600:
"fchattr" fd st_size ð st_mode 6ðð
fchaudit
55──fchaudit──fd──audit_flags──option──────────────────────────────5%
Function
fchaudit invokes the fchaudit callable service to change audit flags for a file
identified by a file descriptor. The file descriptor is specified by a number.
Parameters
fd The file descriptor for the file.
audit_flags
One or more numeric values that indicate the type of access to be tested. You
can specify a numeric value (see Appendix A) or the predefined variable used
to derive the appropriate numeric value. The predefined variables you can
specify are:
Variable Description
AUD_FREAD Audit failed read requests
AUD_SREAD Audit successful read requests
AUD_FWRITE Audit failed write requests
AUD_SWRITE Audit successful write requests
AUD_FEXEC Audit failed execute or search requests
AUD_SEXEC Audit successful execute or search requests
option
A number indicating whether user-requested or auditor-requested auditing is
being changed:
Usage Notes
1. If option indicates that the auditor audit flags are to be changed, you must have
auditor authority for the request to be successful. If you have auditor authority,
you can set the auditor options for any file, even those to which you do not
have path access or authority to use for other purposes.
You can get auditor authority by entering the TSO/E command ALTUSER
AUDITOR.
2. If option indicates that the user audit flags are to be changed, you must have
appropriate privileges or be the owner of the file.
Example
To change user-requested auditing so that failed read requests for the file identified
by file descriptor ð are audited:
"fchaudit ð (aud_fread) ð"
fchmod
55──fchmod──fd──mode──┬────────────────────────────┬───────────────5%
└─setuid──setgid──┬────────┬─┘
└─sticky─┘
Function
fchmod invokes the fchmod callable service to change the mode of a file or
directory indicated by a file descriptor. The file descriptor is specified by a number.
Parameters
fd The file descriptor for the file or directory.
mode
A three- or four-digit number, corresponding to the access permission bits.
Each digit must be in the range ð–7, and at least three digits must be specified.
For more information on permissions, see Appendix B.
setuid
Sets the set-user-ID-on-execution permission. Specify 1 to set this permission
on, or ð to set it off. The default is ð.
setgid
Sets the set-group-ID-on-execution permission. Specify 1 to set this permission
on, or ð to set it off. The default is ð.
sticky
Sets the sticky bit to indicate where the file should be fetched from. If the file
resides in the link pack area (LPA), link list, or STEPLIB, specify 1. The default
is ð.
Usage Notes
1. One bit sets permission for set-user-ID on access, set-group-ID on access, or
the sticky bit. You can set this bit in either of two ways:
Specifying four digits on the mode parameter; the first digit sets the bit.
Specifying the setuid, setgid, or sticky parameters.
2. When a chmod or fchmod has occurred for an open file, fstat reflects the
change in mode. However, no change in access authorization is apparent when
the file is accessed through a previously opened file descriptor.
3. For mode bits to be changed, the effective UID of the caller must match the
file's owner UID, or the caller must be a superuser.
4. When the mode is changed successfully, the file's change time is updated as
well.
5. Setting the set-group-ID-on-execution permission means that when this file is
run, through the exec service, the effective GID of the caller is set to the file's
owner GID, so that the caller seems to be running under the GID of the file,
rather than that of the actual invoker.
The set-group-ID-on-execution permission is set to zero if both of the following
are true:
The caller does not have appropriate privileges.
The GID of the file's owner does not match the effective GID or one of the
supplementary GIDs of the caller.
6. Setting the set-user-ID-on-execution permission means that when this file is
run, the process's effective UID is set to the file's owner UID, so that the
process seems to be running under the UID of the file's owner, rather than that
of the actual invoker.
Example
In the following example, assume that fd was assigned a value earlier in the exec.
This changes the mode for the file identified by the file descriptor so that only a
superuser can access the file:
"fchmod (fd) ððð"
fchown
55──fchown──fd──uid──gid───────────────────────────────────────────5%
Function
fchown invokes the fchown callable service to change the owner and group of a
file or directory indicated by a file descriptor. The file descriptor is specified by a
number.
Parameters
fd The file descriptor for a file or directory.
uid
The numeric UID for the new owner of the file or the present UID, or −1 if there
is no change.
gid
The numeric GID for the new group for the file or the present GID, or −1 if
there is no change.
Usage Notes
1. The fchown service changes the owner UID and owner GID of a file. Only a
superuser can change the owner UID of a file.
2. The owner GID of a file can be changed by a superuser, or if a caller meets all
of these conditions:
The effective UID of the caller matches the file's owner UID.
The uid value specified in the change request matches the file's owner UID.
The gid value specified in the change request is the effective GID, or one
of the supplementary GIDs, of the caller.
3. The set-user-ID-on-execution and set-group-ID-on-execution permissions of the
file mode are automatically turned off.
4. If the change request is successful, the change time for the file is updated.
5. Values for both uid and gid must be specified as they are to be set. If you want
to change only one of these values, the other must be set to its present value
to remain unchanged.
Example
In the following example, assume that fd, uid, and gid were assigned a value earlier
in the exec:
"fchown" fd uid gid
f_closfd
55──f_closfd──fd──fd2──────────────────────────────────────────────5%
Function
f_closfd invokes the fcntl callable service to close a range of file descriptors.
Parameters
fd The file descriptor (a number) for a file. This is the first file descriptor to be
closed.
fd2
The file descriptor (a number) for a file, which must be greater than or equal to
fd. If a −1 is specified for fd2, all file descriptors greater than or equal to fd are
closed.
Usage Notes
1. A process can use f_closfd to close a range of file descriptors. fd2 must be
greater than or equal to fd, or it can also be −1, which indicates that all file
descriptors greater than or equal to fd are to be closed.
2. Use of f_closfd is meant to be consistent with the close callable service. You
cannot close file descriptors that could not also be closed using the close
service.
3. When a file descriptor cannot be closed, it is considered an error, but the
request continues with the next file descriptor in the range. File descriptors that
are not in use are ignored.
Example
In the following example, assume that fd and fd2 were assigned values earlier in
the exec:
"f_closfd" fd fd2
fcntl
Function
fcntl is supported as a set of syscall commands whose names begin with f_:
“f_closfd” on page 48
“f_dupfd” on page 50
“f_dupfd2” on page 51
“f_getfd” on page 52
“f_getfl” on page 53
“f_getlk” on page 54
“f_setfd” on page 61
“f_setfl” on page 62
“f_setlk” on page 63
“f_setlkw” on page 65
f_dupfd
55──f_dupfd──fd──fd2───────────────────────────────────────────────5%
Function
f_dupfd invokes the fcntl callable service to duplicate the lowest file descriptor that
is equal to or greater than fd2 and not already associated with an open file. The file
descriptor is returned in RETVAL.
Parameters
fd The file descriptor (a number) that you want to duplicate.
fd2
The file descriptor (a number) at which to start looking for an available file
descriptor.
Example
In the following example, assume that fd and fd2 were assigned values earlier in
the exec:
"f_dupfd" fd fd2
f_dupfd2
55──f_dupfd2──fd──fd2──────────────────────────────────────────────5%
Function
f_dupf2d invokes the fcntl callable service to duplicate a file descriptor that is equal
to fd2.
Parameters
fd An opened file descriptor (a number) to be duplicated.
fd2
The file descriptor of choice.
Usage Notes
If fd2 is already in use, f_dupfd2 closes it. If fd is equal to fd2, fd2 is returned but
not closed.
Example
In the following example, assume that fd and fd2 were assigned values earlier in
the exec:
"f_dupfd" fd fd2
f_getfd
55──f_getfd──fd────────────────────────────────────────────────────5%
Function
f_getfd invokes the fcntl callable service to get the file descriptor flags for a file.
Parameters
fd The file descriptor (a number) for the file.
Usage Notes
The file descriptor flags are returned in RETVAL. The only POSIX-defined flag is
FCTLCLOEXEC. To determine if this flag is set, use this expression:
(retval//2)=1
Example
To get the file descriptor flags for file descriptor ð:
"f_getfd ð"
f_getfl
55──f_getfl──fd────────────────────────────────────────────────────5%
Function
f_getfl invokes the fcntl callable service to get the file status flags for a file.
Parameters
fd The file descriptor (a number) for the file.
Usage Notes
RETVAL returns the file status flags as a numeric value (see Appendix A):
Flag Description
O_CREAT Create the file if it does not exist.
O_EXCL Fail if the file does exist and O_CREAT is set.
O_NOCTTY Do not make this file a controlling terminal for the calling
process.
O_TRUNC If the file exists, truncate it to zero length.
O_APPEND Set the offset to EOF before each write.
O_NONBLOCK An open, read, or write on the file will not block (wait for
terminal input).
O_RDWR Open for read and write.
O_RDONLY Open for read-only.
O_WRONLY Open for write-only.
O_SYNC Force synchronous updates.
You can use the open flags to test specific values. The easiest way to test a value
is to convert both the RETVAL and the flags to binary data, and then logically AND
them. For example, to test O_WRITE and O_TRUNC:
wrtr=D2C(O_WRITE+O_TRUNC,4))
If BITAND(D2C(retval,4),wrtr)=wrtr Then
Do /\ o_write and o_trunc are set \/
End
Example
In the following example, assume that fd was assigned a value earlier in the exec:
"f_getfl" fd
f_getlk
55──f_getlk──fd──stem──────────────────────────────────────────────5%
Function
f_getlk invokes the fcntl callable service to return information on a file segment for
which locks are set, cleared, or queried.
Parameters
fd The file descriptor (a number) for the file.
stem
The name of a stem variable that is the flock structure used to query, set, or
clear a lock; or to return information. To specify the information, you can specify
a numeric value (see Appendix A) or the predefined variables beginning with
L_ used to derive the appropriate numeric value. For example, stem.1 and
stem.l_type are both the lock-type request:
Variable Description
L_LEN The length of the byte range to be set, cleared, or queried.
L_PID The process ID of the process holding the blocking lock, if
one was found.
L_START The starting offset byte of the lock to be set, cleared, or
queried.
L_TYPE The type of lock being set, cleared, or queried. To specify
the information, you can specify a numeric value (see
Appendix A) or one of the following predefined variables
used to derive the appropriate numeric value:
F_RDLCK Shared or read lock. This type of lock specifies
that the process can read the locked part of the
file, and other processes cannot write on that
part of the file in the meantime. A process can
change a held write lock, or any part of it, to a
read lock, thereby making it available for other
processes to read. Multiple processes can have
read locks on the same part of a file
simultaneously. To establish a read lock, a
process must have the file accessed for reading.
F_WRLCK Exclusive or write lock. This type of lock
indicates that the process can write on the
locked part of the file, without interference from
other processes. If one process puts a write lock
on part of a file, no other process can establish
a read lock or write lock on that same part of the
file. A process cannot put a write lock on part of
a file if there is already a read lock on an
overlapping part of the file, unless that process
is the only owner of that overlapping read lock.
In such a case, the read lock on the overlapping
section is replaced by the write lock being
requested. To establish a write lock, a process
must have the file accessed for writing.
L_TYPE (continued) F_UNLCK Unlock. This is used to unlock all locks held on
the given range by the requesting process.
Variable Description
L_WHENCE The flag for the starting offset. To specify the information,
you can specify a numeric value (see Appendix A) or one
of the predefined variables beginning with SEEK_ used to
derive the appropriate numeric value. Valid values are:
SEEK_CUR The current offset
SEEK_END The end of the file
SEEK_SET The specified offset
Example
In the following example, assume that rec was assigned a value earlier in the exec:
lock.l_len=4ð
lock.l_start=rec\4ð
lock.l_type=f_wrlck
lock.l_whence=seek_set
"f_getlk" fd "lock."
if lock.l_type=f_unlck then
/\ lock is available for the requested 4ð byte record \/
fork
There is no fork syscall command. Instead of using fork, see “spawn” on
page 151.
forkexecm
55──forkexecm──program──┬──────┬───────────────────────────────────5%
└─parm─┘
Function
forkexecm invokes the fork and execmvs callable services to fork and exec a
program to be executed from the LINKLIB, LPALIB, or STEPLIB library.
Parameters
program
The name of the program.
parm
A parameter to be passed to the program.
Usage Notes
1. If the exec fails, the child process ends with a SIGABRT signal.
2. If the fork succeeds, RETVAL contains the PID for the child process.
3. The child process has a unique process ID (PID) that does not match any
active process group ID.
4. If a hierarchical file system (HFS) file has its FCTLCLOFORK flag set on, it is
not inherited by the child process. This flag is set with the fcntl callable service.
5. The process and system utilization times for the child are set to zero.
6. Any file locks previously set by the parent are not inherited by the child.
7. The child process has no alarms set (similar to the results of a call to the alarm
service with Wait_time specified as zero).
8. The child has no pending signals.
9. The following characteristics of the calling process are changed when the new
executable program is given control by the execmvs callable service:
The prior process image is replaced with a new process image for the
executable program to be run.
All open files marked close-on-exec and all open directory streams are
closed.
All signals that have sigaction settings are reset to their default actions.
10. The input passed to the MVS executable file by the service is consistent with
what is passed as input to MVS programs. On input, the MVS program receives
a single-entry parameter list pointed to by register 1. The high-order bit of the
single parameter entry is set to 1.
The single parameter entry is the address of a 2-byte length field followed by
an argument string. The length field describes the length of the data that
follows it. If a null argument and argument length are specified in the call, the
length field specifies ð bytes on input to the executable file.
11. The call can invoke both unauthorized and authorized MVS programs:
Example
In the following example, assume that pgm was assigned a value earlier in the
exec:
"forkexecm (pgm) 'hello world'"
fpathconf
55──fpathconf──fd──name────────────────────────────────────────────5%
Function
fpathconf invokes the fpathconf callable service to let a program determine the
current value of a configurable limit or variable associated with a file or directory.
The value is returned in RETVAL.
Parameters
fd The file descriptor (a number) for the file or directory.
name
A numeric value that indicates which configurable limit will be returned. You
can specify a numeric value (see Appendix A) or one of the following
predefined variables used to derive the appropriate numeric value:
Variable Description
PC_LINK_MAX Maximum value of a file's link count.
PC_MAX_CANON Maximum number of bytes in a terminal canonical
input line.
PC_MAX_INPUT Minimum number of bytes for which space will be
available in a terminal input queue; therefore, the
maximum number of bytes a portable application may
require to be typed as input before reading them.
PC_NAME_MAX Maximum number of bytes in a filename (not a string
length; count excludes a terminating null).
PC_PATH_MAX Maximum number of bytes in a pathname (not a
string length; count excludes a terminating null).
PC_PIPE_BUF Maximum number of bytes that can be written
atomically when writing to a pipe.
PC_POSIX_CHOWN_RESTRICTED Change ownership ( “chown” on page 33) function is
restricted to a process with appropriate privileges,
and to changing the group ID (GID) of a file only to
the effective group ID of the process or to one of its
supplementary group IDs.
PC_POSIX_NO_TRUNC Pathname components longer than 255 bytes
generate an error.
PC_POSIX_VDISABLE Terminal attributes maintained by the system can be
disabled using this character value.
Usage Notes
1. If name refers to MAX_CANON, MAX_INPUT, or _POSIX_VDISABLE, then the
following applies:
If fd does not refer to a terminal file, the function returns −1 and sets the
ERRNO to EINVAL.
2. If name refers to NAME_MAX, PATH_MAX, or _POSIX_NO_TRUNC, the
following applies:
If fd does not refer to a directory, the function still returns the requested
information using the parent directory of the specified file.
3. If name refers to PC_PIPE_BUF, the following applies:
Example
To determine the maximum number of bytes that can be written atomically to the
file identified by file descriptor 1:
"fpathconf 1 (pc_pipe_buf)"
f_setfd
55──f_setfd──fd──close_exec────────────────────────────────────────5%
Function
f_setfd invokes the fcntl callable service to set file descriptor flags.
Parameters
fd The file descriptor (a number) for the file.
close_exec
A numeric value to indicate whether this file descriptor should remain open
after an exec:
Example
To set the flags for the file identified by file descriptor ð and indicate that this file
descriptor should remain open during an exec:
"f_setfd ð ð"
f_setfl
55──f_setfl──fd──flags─────────────────────────────────────────────5%
Function
f_setfl invokes the fcntl callable service to set file status flags.
Parameters
fd The file descriptor (a number) for the file.
flags
A value that sets the file status flags. To specify the information, you can
specify a numeric value (see Appendix A) or a predefined variable beginning
with O_ used to derive the appropriate numeric value. The permitted values
are:
Variable Description
O_APPEND Set offset to EOF on write.
O_NONBLOCK Do not block an open, a read, or a write on the file (do not
wait for terminal input).
O_SYNC Force synchronous updates.
Example
To set the O_APPEND file status flag for the file identified by file descriptor 1:
"f_setfl 1" o_append
f_setlk
55──f_setlk──fd──stem──────────────────────────────────────────────5%
Function
f_setlk invokes the fcntl callable service to set or release a lock on part of a file.
Parameters
fd The file descriptor (a number) for the file.
stem
The name of a stem variable that is the flock structure used to set or release
the lock. To access the information, you can specify a numeric value (see
Appendix A) or the predefined variables beginning with L_ that derive the
appropriate numeric value. For example, stem.1 and stem.l_type are both the
lock-type request.
Variable Description
L_LEN The length of the byte range to be set, cleared, or queried.
L_PID The process ID of the process holding the blocking lock, if
one was found.
L_START The starting offset byte of the lock to be set, cleared, or
queried.
L_TYPE The type of lock being set, cleared, or queried. To specify
the information, you can specify a numeric value (see
Appendix A) or one of the following predefined variables
used to derive the appropriate numeric value:
F_RDLCK Shared or read lock. This type of lock specifies
that the process can read the locked part of the
file, and other processes cannot write on that
part of the file in the meantime. A process can
change a held write lock, or any part of it, to a
read lock, thereby making it available for other
processes to read. Multiple processes can have
read locks on the same part of a file
simultaneously. To establish a read lock, a
process must have the file accessed for reading.
F_WRLCK Exclusive or write lock. This type of lock
indicates that the process can write on the
locked part of the file, without interference from
other processes. If one process puts a write lock
on part of a file, no other process can establish
a read lock or write lock on that same part of the
file. A process cannot put a write lock on part of
a file if there is already a read lock on an
overlapping part of the file, unless that process
is the only owner of that overlapping read lock.
In such a case, the read lock on the overlapping
section is replaced by the write lock being
requested. To establish a write lock, a process
must have the file accessed for writing.
L_TYPE (continued) F_UNLCK Unlock. This is used to unlock all locks held on
the given range by the requesting process.
Variable Description
L_WHENCE The flag for the starting offset. To specify the information,
you can specify a numeric value (see Appendix A) or one
of the predefined variables beginning with SEEK_ used to
derive the appropriate numeric value. Valid values are:
SEEK_CUR The current offset
SEEK_END The end of the file
SEEK_SET The specified offset
Usage Notes
If the lock cannot be obtained, a RETVAL of −1 is returned along with an
appropriate ERRNO and ERRNOJR. You can also use F_SETLK to release locks
already held, by setting l_type to F_UNLCK.
All of a process's locks on a file are removed when the process closes a file
descriptor for that file. Locks are not inherited by child processes created with the
fork service.
Advisory Locking: All locks are advisory only. Processes can use locks to inform
each other that they want to protect parts of a file, but locks do not prevent I/O on
the locked parts. A process that has appropriate permissions on a file can perform
whatever I/O it chooses, regardless of which locks are set. Therefore, file locking is
only a convention, and it works only when all processes respect the convention.
Example
The following example locks a 40-byte record (rec). Assume that rec was assigned
a value earlier in the exec:
lock.l_len=4ð
lock.l_start=rec\4ð
lock.l_type=f_wrlck
lock.l_whence=seek_set
"f_setlk (fd) lock."
f_setlkw
55──f_setlkw──fd──stem─────────────────────────────────────────────5%
Function
f_setlkw invokes the fcntl callable service to set or release a lock on part of a file
and, if another process has a lock on some or all of the requested range, wait until
the specified range is free and the request can be completed.
stem
The name of a stem variable that is the flock structure used to set or release
the lock. To specify the lock information, you can specify a numeric value (see
Appendix A) or the predefined variables beginning with L_ used to derive the
appropriate numeric value. For example, stem.1 and stem.l_type are both the
lock-type request.
Variable Description
L_LEN The length of the byte range to be set, cleared, or queried.
L_PID The process ID of the process holding the blocking lock, if
one was found.
L_START The starting offset byte of the lock to be set, cleared, or
queried.
L_TYPE The type of lock being set, cleared, or queried. To specify
the information, you can specify a numeric value (see
Appendix A) or one of the following predefined variables
used to derive the appropriate numeric value:
F_RDLCK Shared or read lock. This type of lock specifies
that the process can read the locked part of the
file, and other processes cannot write on that
part of the file in the meantime. A process can
change a held write lock, or any part of it, to a
read lock, thereby making it available for other
processes to read. Multiple processes can have
read locks on the same part of a file
simultaneously. To establish a read lock, a
process must have the file accessed for reading.
F_WRLCK Exclusive or write lock. This type of lock
indicates that the process can write on the
locked part of the file, without interference from
other processes. If one process puts a write lock
on part of a file, no other process can establish
a read lock or write lock on that same part of the
file. A process cannot put a write lock on part of
a file if there is already a read lock on an
overlapping part of the file, unless that process
is the only owner of that overlapping read lock.
In such a case, the read lock on the overlapping
section is replaced by the write lock being
requested. To establish a write lock, a process
must have the file accessed for writing.
L_TYPE (continued) F_UNLCK Unlock. This is used to unlock all locks held on
the given range by the requesting process.
Variable Description
L_WHENCE The flag for the starting offset. To specify the information,
you can specify a numeric value (see Appendix A) or one
of the predefined variables beginning with SEEK_ used to
derive the appropriate numeric value. Valid values are:
SEEK_CUR The current offset
SEEK_END The end of the file
SEEK_SET The specified offset
Usage Notes
If the lock cannot be obtained because another process has a lock on all or part of
the requested range, the f_setlkw request waits until the specified range becomes
free and the request can be completed. You can also use f_setlkw to release locks
already held, by setting l_type to F_UNLCK.
f_setlkw operations have the potential for encountering deadlocks. This happens
when process A is waiting for process B to unlock a region, and B is waiting for A
to unlock a different region. If the system detects that a f_setlkw might cause a
deadlock, the fcntl service returns with a RETVAL of −1 and an ERRNO of
EDEADLK.
Example
The following example locks a 40-byte record (rec). Assume that rec was assigned
a value earlier in the exec:
lock.l_len=4ð
lock.l_start=rec\4ð
lock.l_type=f_wrlck
lock.l_whence=seek_set
"f_setlkw (fd) lock."
fstat
55──fstat──fd──stem────────────────────────────────────────────────5%
Function
fstat invokes the fstat callable service to get status information about a file that is
identified by its file descriptor.
Parameters
fd The file descriptor (a number) for the file.
stem
The name of a stem variable used to return the status information. Upon return,
stem.0 contains the number of variables that are returned. To access the status
values, you can use a numeric value (see Appendix A) or any of the
predefined variables that begin with ST_. For example, stem.9 and
stem.st_atime are both the request for the time of last access.
Variable Description
ST_AAUDIT Auditor audit information.
ST_ATIME Time of last access.
ST_AUDITID RACF File ID for auditing.
ST_BLKSIZE File block size.
ST_BLOCKS Blocks allocated.
ST_CCSID Coded character set ID.
ST_CRTIME File creation time.
ST_CTIME Time of last file status change.
ST_DEV Device ID of the file.
ST_EXTLINK External symbolic link flag, set to ð or 1.
ST_FID File identifier.
ST_FILEFMT Format of the file. To specify the format, you can specify a
numeric value (see Appendix A) or one of the following
predefined variables used to derive the appropriate numeric
value:
S_FFBINARY Binary data
S_FFCR Text data delimited by a carriage return
character
S_FFCRLF Text data delimited by carriage return and
line feed characters
S_FFLF Text data delimited by a line feed
character
S_FFLFCR Text data delimited by a line feed and
carriage return characters
S_FFNA Text data with the file format not specified
S_FFNL Text data delimited by a newline character
ST_GENVALUE General attribute values.
ST_GID Group ID of the group of the file.
ST_INO File serial number.
ST_MAJOR Major number for a character special file.
ST_MINOR Minor number for a character special file.
ST_MODE File mode, permission bits only.
ST_MTIME Time of last data modification.
ST_NLINK Number of links.
ST_RTIME File backup time stamp (reference time).
ST_SETGID Set Group ID on execution flag, set to ð or 1.
Variable Description
ST_SETUID Set User ID on execution flag, set to ð or 1.
ST_SIZE File size for a regular file, in bytes. If file size exceeds
231−1 bytes, size is expressed in megabytes, using an M
(for example, 3123M).
ST_STICKY Sticky bit flag (keep loaded executable in storage), set to ð
or 1.
ST_TYPE Numeric value that represents the file type for this file. You
can use a numeric value (see Appendix A) or any of the
predefined variables that begin with S_ to determine the file
type:
S_ISCHR Character special file
S_ISDIR Directory
S_ISFIFO FIFO special file
S_ISREG Regular file
S_ISSYM Symbolic link
ST_UAUDIT Area for user audit information.
ST_UID User ID of the owner of the file.
Usage Notes
All time values returned in stem are in POSIX format. Time is in seconds since
00:00:00 GMT, January 1, 1970. You can use gmtime to convert it to other forms.
Example
In the following example, assume that fd was assigned a value earlier in the exec:
"fstat (fd) st."
fstatvfs
55──fstatvfs──fd──stem─────────────────────────────────────────────5%
Function
fstatvfs invokes the fstatvfs callable service to obtain information about a file
system identified by a file descriptor that refers to a file in that file system.
Parameters
fd A file descriptor referring to a file from the desired file system.
stem
The name of a stem variable used to return the information. On return, stem.0
contains the number of variables returned. You can use the predefined
variables beginning with STFS_ or their equivalent numeric values to access
the status values they represent. (See Appendix A for the numeric values.) For
example, stem.stfs_avail accesses the number of blocks available in the file
system.
Variable Description
STFS_AVAIL Space available to unprivileged users in block-size units.
STFS_BFREE Total number of free blocks.
STFS_BLOCKSIZE Block size.
STFS_FAVAIL Number of free file nodes available to unprivileged users.
STFS_FFREE Total number of free file nodes.
STFS_FILES Total number of file nodes in the file system.
STFS_FRSIZE Fundamental file system block size.
STFS_FSID File system ID set by the logical file system.
STFS_INUSE Allocated space in block-size units.
STFS_INVARSEC Number of seconds the file system will remain unchanged.
STFS_NAMEMAX Maximum length of file name.
STFS_NOSUID SETUID and SETGID are not supported.
STFS_RDONLY File system is read-only.
STFS_TOTAL Total space in block-size units.
Example
In the following example, assume that fd was assigned a value earlier in the exec:
"fstatvfs" fd st.
fsync
55──fsync──fd──────────────────────────────────────────────────────5%
Function
fsync invokes the fsync callable service to write changes on the direct access
storage device that holds the file identified by the file descriptor.
Parameters
fd The file descriptor (a number) for the file.
Usage Notes
On return from a successful call, all updates have been saved on the direct access
storage that holds the file.
Example
To invoke fsync for file descriptor 1:
"fsync 1"
ftrunc
55──ftrunc──fd──file_size──────────────────────────────────────────5%
Function
ftrunc invokes the ftrunc callable service to change the size of the file identified by
the file descriptor.
Parameters
fd The file descriptor (a number) for the file.
file_size
The new size of the file, in bytes.
Usage Notes
1. The ftrunc service changes the file size to file_size bytes, beginning at the first
byte of the file. If the file was previously larger than file_size, all data from
file_size to the original end of the file is removed. If the file was previously
shorter than file_size, bytes between the old and new lengths are read as
zeros.
2. Full blocks are returned to the file system so that they can be used again, and
the file size is changed to the lesser of file_size or the current length of the file.
3. The file offset is not changed.
Example
In the following example, assume that fd was assigned a value earlier in the exec.
To truncate fd to ð bytes:
"ftrunc" fd ð
getcwd
55──getcwd──variable───────────────────────────────────────────────5%
Function
getcwd invokes the getcwd callable service to get the pathname of the working
directory.
Parameters
variable
The name of the variable where the pathname of the working directory is to be
stored.
Example
To get the pathname of the working directory:
"getcwd cwd"
getegid
55──getegid────────────────────────────────────────────────────────5%
Function
getegid invokes the getegid callable service to get the effective group ID (GID) of
the calling process.
Usage Notes
1. The effective GID is returned in RETVAL.
2. If the service fails, the process abends.
geteuid
55──geteuid────────────────────────────────────────────────────────5%
Function
geteuid invokes the geteuid callable service to get the effective user ID (UID) of
the calling process.
Usage Notes
1. The effective UID is returned in RETVAL.
2. If the service fails, the process abends.
getgid
55──getgid─────────────────────────────────────────────────────────5%
Function
getgid invokes the getgid callable service to get the real group ID (GID) of the
calling process.
Usage Notes
1. The GID is returned in RETVAL.
2. If the service fails, the process abends.
getgrent
55──getgrent──stem─────────────────────────────────────────────────5%
Function
getgrent invokes the getgrent callable service to retrieve a group database entry.
stem
The name of a stem variable used to return the information. Upon return,
stem.0 contains the number of variables returned. To access the status values,
you can specify a numeric value (see Appendix A) or the predefined variable
beginning with GR_ used to derive the appropriate numeric value. For example,
you can specify stem.2 or stem.gr_gid to access the group ID:
Variable Description
GR_GID The group ID.
GR_MEM The stem index of the first member name returned.
GR_MEMBERS The number of members returned.
GR_NAME The name of the group.
Usage Notes
1. The service is intended to be used to search the group database sequentially.
The first call to this service from a given task returns the first group entry in the
group database. Subsequent calls from the same task return the next group
entry found, until no more entries exist, at which time a RETVAL of ð is
returned.
2. The setgrent service can be used to reset this sequential search.
Example
To list all groups in the group data base:
do forever
"getgrent gr."
if retval=ð | retval=-1 then
leave
say gr.gr_name
end
getgrid
55──getgrgid──gid──stem────────────────────────────────────────────5%
Function
getgrgid invokes the getgrgid callable service to get information about a group and
its members; the group is identified by its group ID (GID).
Parameters
gid
A numeric value.
stem
The name of a stem variable used to return the information. Upon return,
stem.0 contains the number of variables returned. To access the status values,
you can specify a numeric value (see Appendix A) or the predefined variable
beginning with GR_ used to derive the appropriate numeric value. For example,
you can specify stem.2 or stem.gr_gid to access the group ID:
Variable Description
GR_GID The group ID.
GR_MEM The stem index of the first member name returned.
GR_MEMBERS The number of members returned.
GR_NAME The name of the group.
Usage Notes
A RETVAL greater than zero indicates success. A RETVAL of −1 or ð indicates
failure. A RETVAL of ð has an ERRNOJR, but no ERRNO.
Example
In the following example, assume that gid was assigned a value earlier in the exec.
To get a list of names connected with a group ID:
"getgrgid (gid) gr."
say 'Users connected to group number' gid ':'
do i=gr_mem to gr.ð
say gr.i
end
getgrnam
55──getgrnam──name──stem───────────────────────────────────────────5%
Function
getgrnam invokes the getgrnam callable service to get information about a group
and its members. The group is identified by its name.
Parameters
name
A string that specifies the group name as defined to the system.
stem
The name of a stem variable used to return the information. Upon return,
stem.0 contains the number of variables returned. To access the status values,
you can specify a numeric value (see Appendix A) or the predefined variable
beginning with GR_ used to derive the appropriate numeric value. For example,
you can specify stem.2 or stem.gr_gid to access the group ID:
Variable Description
GR_GID The group ID.
GR_MEM The stem index of the first member name returned.
GR_MEMBERS The number of members returned.
GR_NAME The name of the group.
Usage Notes
1. A RETVAL greater than zero indicates success. A RETVAL of −1 or ð indicates
failure. A RETVAL of ð has an ERRNOJR, but no ERRNO.
2. The return values point to data that can change or disappear after the next
getgrnam or getgrgid call from that task. Each task manages its own storage
separately. Move data to your own dynamic storage if you need it for future
reference.
3. The storage is key ð non-fetch-protected storage that is managed by OS/390
OpenEdition.
Example
To get information about the group named SYS1:
"getgrnam SYS1 gr."
say 'Users connected to group SYS1:'
do i=gr_mem to gr.ð
say gr.i
end
getgroups
55──getgroups──stem────────────────────────────────────────────────5%
Function
getgroups invokes the getgroups callable service to get the number of
supplementary group IDs (GIDs) for the calling process and a list of those
supplementary group IDs.
Parameters
stem
The name of a stem variable used to return the information. Upon return,
stem.0 contains the number of variables returned. stem.1 to stem.n (where n is
the number of variables returned) each contain a group ID.
Usage Notes
A RETVAL greater than zero indicates success. A RETVAL of −1 or ð indicates
failure. A RETVAL of ð has an ERRNOJR, but no ERRNO.
Example
To invoke getgroups:
"getgroups grps."
getgroupsbyname
55──getgroupsbyname──name──stem────────────────────────────────────5%
Function
getgroupsbyname invokes the getgroupsbyname callable service to get the
number of supplementary group IDs (GIDs) for a specified user name and,
optionally, get a list of those supplementary group IDs.
Parameters
name
A string that specifies the name of the user as defined to the system.
stem
The name of a stem variable used to return the information. Upon return,
stem.0 contains the number of variables returned. stem.1 to stem.n (where n is
the number of variables returned) each contain a supplementary group ID for
name.
Usage Notes
A RETVAL greater than zero indicates success. A RETVAL of −1 or ð indicates
failure. A RETVAL of ð has an ERRNOJR, but no ERRNO.
Example
To get the number of supplementary group IDs for the user MEGA:
"getgroupsbyname MEGA supgrp."
getlogin
55──getlogin──variable─────────────────────────────────────────────5%
Function
getlogin invokes the getlogin callable service to get the user login name associated
with the calling process.
Parameters
variable
The name of the variable in which the login name is returned.
Usage Notes
If the service fails, the process abends.
Example
To invoke getlogin and store the login name in the variable myid:
"getlogin myid"
getment
55──getment──length──variable──────────────────────────────────────5%
Function
getment invokes the w_getmntent callable service to get information about the
mounted file systems and return the information in the format used by OS/390
OpenEdition callable services. Alternatively, you can use the getmntent syscall
command to format the mount entries in a stem.
Parameters
length
The size of the specified variable. If the length is ð, RETVAL contains the total
number of mounted file systems; otherwise, RETVAL contains the number of
entries returned.
variable
The name of the buffer where the information about the mount entries is to be
stored. Clear the buffer on the first call and do not alter it between calls.
Usage Notes
1. Before a program calls getment for the first time, the variable should be
dropped, set to blanks, or set to nulls.
2. If more than one call is made to getment, use the same variable on each call,
because part of the information returned in the variable tells the file system
where to continue retrieving its information.
3. getment normally returns information about as many file systems as are
mounted, or as many as fit in the passed variable. The number of entries
contained in the variable is returned. The caller must have a variable large
enough to receive information about at least a single mount entry with each
call. If a zero-length variable is passed, no information is returned, but the
return value contains the total number of mounted file systems. This value
could then be used to get enough storage to retrieve information on all these
file systems in one additional call.
4. You could also retrieve all mount entries by setting up a loop that continues to
call getment until a return value of either −1 (in an error) or ð (no more entries
found) is returned.
Example
In the following example, assume that buf was assigned a value earlier in the exec.
This example returns the number of mounted file systems in RETVAL:
"getment ð buf"
getmntent
55──getmntent──stem──┬───────┬─────────────────────────────────────5%
└─devno─┘
Function
getmntent invokes the w_getmntent callable service to get information about the
mounted file systems, or a specific mounted file system, and return the information
formatted in a stem.
Parameters
stem
The name of a stem variable used to return the mount table information. The
stem has two dimensions: the field name, followed by a period and the number
of the mount table entry. For example, you can access the file system name for
the first entry in the mount table as stem.mnte_fsname.1.
For the field name, you can specify a numeric value (see Appendix A) or the
predefined variable beginning with MNTE_ used to derive the appropriate
numeric value. For example, you could use stem.mnte_fsname.1 or stem.6.1 to
access the file system name for the first entry:
Variable Description
MNTE_DD The ddname specified on the mount.
MNTE_DEV The device ID of the file system.
MNTE_FSNAME The name of the HFS data set containing the file system.
MNTE_FSTYPE The file system type; for example, HFS.
MNTE_MODE The file system type mount method. You can specify a
numeric value (see Appendix A) or one of the following
predefined variables used to derive the appropriate numeric
value:
MNT_MODE_RDWR
MNT_MODE_RDONLY
MNTE_PARDEV The ST_DEV of the parent file system.
MNTE_PARM The parameter specified with mount().
MNTE_PATH The mountpoint pathname.
MNTE_QJOBNAME The job name of the quiesce requestor.
MNTE_QPID The PID of the quiesce requestor.
MNTE_ROOTINO The inode of the mountpoint.
Variable Description
MNTE_STATUS The status of the file system. To specify the information,
you can specify a numeric value (see Appendix A) or one
of the following predefined variables used to derive the
appropriate numeric value:
MNT_ASYNCHMOUNT Asynchronous mount in
progress for this file system.
MNT_FILEACTIVE File system is active.
MNT_FILEDEAD File system is dead.
MNT_FILEDRAIN File system is being
unmounted with the drain
option.
MNT_FILEFORCE File system is being
unmounted with the force
option.
MNT_FILEIMMED File system is being
unmounted with the
immediate option.
MNT_FILENORM File system is being
unmounted with the normal
option.
MNT_FILERESET File system is being reset.
MNT_IMMEDTRIED File system unmount with
the immediate option failed.
MNT_MOUNTINPROGRESS Mount in progress for this
file system
MNT_QUIESCED File system is quiesced.
MNTE_TYPE The file system type.
devno
An optional parameter, this is the device number for a specific file system for
which you want the mount information. Specifying ð is the equivalent of not
specifying a device number.
Example
To invoke w_getmntent:
"getmntent mounts."
getpgrp
55──getpgrp────────────────────────────────────────────────────────5%
Function
getpgrp invokes the getpgrp callable service to get the process group ID (PGID) of
the calling process.
Usage Notes
1. The PGID for the calling process is returned in RETVAL.
2. If the service fails, the process abends.
getpid
55──getpid─────────────────────────────────────────────────────────5%
Function
getpid invokes the getpid callable service to get the process ID (PID) of the calling
process.
Usage Notes
1. The PID for the calling process is returned in RETVAL.
2. If the service fails, the process abends.
getppid
55──getppid────────────────────────────────────────────────────────5%
Function
getppid invokes the getppid callable service to get the parent process ID (PPID) of
the calling process.
Usage Notes
1. The parent PID for the calling process is returned in RETVAL.
2. If the service fails, the process abends.
getpsent
55──getpsent──stem─────────────────────────────────────────────────5%
Function
getpsent invokes the w_getpsent callable service to provide data describing the
status of all the processes to which you are authorized. The data is formatted in a
stem. The PS_ variables, or their numeric equivalents, are used to access the
fields.
Parameters
stem
Upon return, stem.0 contains the number of processes for which information is
returned. stem.1 through stem.n (where n is the number of entries returned)
each contain process informati on for the nth process.
You can use the predefined variables that begin with PS_ or their equivalent
numeric values (see Appendix A) to access the information. For example,
stem.1.ps_pid is the process ID for the first process returned.
Variable Description
PS_CMD Command.
PS_CONTTY Controlling tty.
PS_EGID Effective group ID.
PS_EUID Effective user ID.
PS_FGPID Foreground process group ID.
PS_MAXVNODES Maximum number of vnode tokens allowed.
PS_PATH Pathname.
PS_PGPID Process Group ID.
PS_PID Process ID.
PS_PPID Parent Process ID.
PS_RGID Real group ID.
PS_RUID Real user ID.
PS_SERVERFLAGS Server flags.
PS_SERVERNAME Server name supplied on registration.
PS_SERVERTYPE Server type (File=1; Lock=2).
PS_SGID Saved set group ID.
PS_SID Session ID (leader).
PS_SIZE Total size.
PS_STARTTIME Starting time, in POSIX format (seconds since the Epoch,
00:00:00 on 1 January 1970).
PS_STAT Process status.
Variable Description
PS_STATE Process state. This value can be expressed as one of the
following predefined variables or as an alphabetic value
(see Appendix A):
PS_CHILD Waiting for a child process.
PS_FORK fork() a new process.
PS_FREEZE QUIESCEFREEZE
PS_MSGRCV IPC MSGRCV WAIT
PS_MSGSND IPC MSGSND WAIT
PS_PAUSE MVSPAUSE
PS_QUIESCE Quiesce termination wait.
PS_RUN Running, not in kernel wait.
PS_SEMWT IPC SEMOP WAIT
PS_SLEEP sleep() issued.
PS_WAITC Communication kernel wait.
PS_WAITF File system kernel wait.
PS_WAITO Other kernel wait.
PS_ZOMBIE Process cancelled.
PS_ZOMBIE2 Process terminated yet still the session or
process group leader.
PS_SUID Saved set user ID.
PS_SYSTIME System CPU time, a value of the type clock_t, which needs
to be divided by sysconf(_SC_CLK_TK) to convert it to
seconds. For OS/390 OpenEdition, this value is expressed
in hundredths of a second.
PS_USERTIME User CPU time, a value of the type clock_t, which needs to
be divided by sysconf(_SC_CLK_TK) to convert it to
seconds. For OS/390 OpenEdition, this value is expressed
in hundredths of a second.
PS_VNODECOUNT Current number of vnode tokens.
Usage Notes
1. Information is returned for only those processes for which RACF allows the
user access based on effective user ID, real user ID, or saved set user ID.
2. PS_STARTTIME is in seconds since the Epoch (00:00:00 on 1 January 1970).
3. PS_USERTIME and PS_SYSTIME are task-elapsed times in 1/100ths of
seconds.
Example
This exec will produce output similar to the ps -A shell command, displaying
information on all accessible processes:
/\ rexx \/
address syscall
say right('PID',12) left('TTY',1ð) ' TIME' 'COMMAND'
ps.ð=ð
'getpsent ps.' /\ get process data \/
do i=1 to ps.ð /\ process each entry returned \/
t=(ps.i.ps_usertime + 5ð) % 1ðð /\ change time to seconds \/
'gmtime (t) gm.' /\ convert to usable format \/
if gm.tm_hour=ð then /\ set hours: samp ignores day \/
h=' '
else
h=right(gm.tm_hour,2,ð)':'
m=right(gm.tm_min,2,ð)':' /\ set minutes \/
parse value reverse(ps.i.ps_contty),
with tty '/' /\ get tty filename \/
tty=reverse(tty)
say right(ps.i.ps_pid,12), /\ display process id \/
say right(ps.i.ps_pid,12), /\ display process id \/
left(tty,1ð), /\ display controlling tty \/
h || m || right(gm.tm_sec,2,ð), /\ display process time \/
ps.i.ps_cmd /\ display command \/
end
return ð
getpwent
55──getpwent──stem─────────────────────────────────────────────────5%
Function
getpwent invokes the getpwent callable service to retrieve a user database entry.
Parameters
stem
The name of a stem variable used to return the information. Upon return,
stem.0 contains the number of variables returned. You can use a numeric value
(see Appendix A) or the predefined variables beginning with PW_ to access
the values:
Variable Description
PW_DIR The initial working directory.
PW_GID The group ID.
PW_NAME The TSO/E user ID.
PW_SHELL The name of the initial user program.
PW_UID The user ID (UID) as defined to RACF.
Example
To list all users in the user database:
do forever
"getpwent pw."
if retval=ð | retval=-1 then
leave
say pw.pw_name
end
getpwnam
55──getpwnam──name──stem───────────────────────────────────────────5%
Function
getpwnam invokes the getpwnam callable service to get information about a user,
identified by user name.
Parameters
name
The user name as defined to the system.
stem
The name of a stem variable used to return the information. Upon return,
stem.0 contains the number of variables returned. To access the information,
you can specify a numeric value (see Appendix A) or the predefined variable
beginning with PW_ used to derive the appropriate numeric value. For
example, to access the name of the user's initial working directory, you can
specify stem.4 or stem.pw_dir:
Variable Description
PW_DIR The initial working directory.
PW_GID The group ID.
PW_NAME The TSO/E user ID.
PW_SHELL The name of the initial user program.
PW_UID The user ID (UID) as defined to RACF.
Usage Notes
A RETVAL greater than zero indicates success. A RETVAL of −1 or ð indicates
failure. A RETVAL of ð has an ERRNOJR, but no ERRNO.
If an entry for the specified name is not found in the user database, the
RETVAL is ð.
Example
To get information about the user JANET:
"getpwnam JANET pw."
getpwuid
55──getpwuid──uid──stem────────────────────────────────────────────5%
Function
getpwuid invokes the getpwuid callable service to get information about a user,
identified by UID.
Parameters
uid
A numeric value that is the user's UID as defined to the system.
stem
The name of a stem variable used to return the information. Upon return,
stem.0 contains the number of variables returned. You can use a numeric value
(see Appendix A) or the predefined variables beginning with PW_ to access
the values:
Variable Description
PW_DIR The initial working directory.
PW_GID The group ID.
PW_NAME The TSO/E user ID.
PW_SHELL The name of the initial user program.
PW_UID The user ID (UID) as defined to RACF.
Usage Notes
A RETVAL greater than zero indicates success. A RETVAL of −1 or ð indicates
failure. A RETVAL of ð has an ERRNOJR, but no ERRNO.
Example
To get information about the user with UID 42:
"getpwuid 42 pw."
getrlimit
55──getrlimit──resource──stem──────────────────────────────────────5%
Function
getrlimit invokes the getrlimit callable service to get the maximum and current
resource limits for the calling process.
Parameters
resource
The resource whose limit is being requested. Resources that have limits with
values greater than RLIM_INFINITY will return values of RLIM_INFINITY.
You can use the predefined variables beginning with RLIMIT_ or their
equivalent numeric values to access the limits. (See Appendix A for the
numeric values.)
Variable Description
RLIMIT_AS Maximum address space size for a process.
RLIMIT_CORE Maximum size (in bytes) of a core dump created by a
process.
RLIMIT_CPU Maximum amount of CPU time (in seconds) used by a
process.
RLIMIT_FSIZE Maximum files size (in bytes) created by a process.
RLIMIT_NOFILE Maximum number of open file descriptors for a process.
stem
The name of the stem variable used to return the limit. stem.1 is the first word
and stem.2 is the second word. The first word contains the current limit; the
second word contains the maximum limit. The values for each word are
dependent on the resource specified.
Example
To print the maximum and current limit for number of open files allowed:
"getrlimit" rlimit_nofile r.
say 'maximum open limit is' r.2
say 'current open limit is' r.1
getuid
55──getuid─────────────────────────────────────────────────────────5%
Function
getuid invokes the getuid callable service to get the real user ID of the calling
process.
Usage Notes
Upon return, RETVAL contains the UID. If the service fails, the process abends.
gmtime
55──gmtime──time──stem─────────────────────────────────────────────5%
Function
gmtime converts time expressed in seconds since Epoch into month, day, and year
time format.
Parameters
time
A numeric value, the time expressed as “POSIX time,” the number of seconds
since the Epoch (00:00:00 on 1 January 1970).
stem
The name of a stem variable used to return the information. Upon return,
stem.0 contains the number of variables returned. To access the status values,
you can specify a numeric value (see Appendix A) or the predefined variable
beginning with TM_ used to derive the appropriate numeric value. For example,
to access the year, you can specify stem.6 or stem.tm_year:
Variable Description
TM_HOUR The hour of the day.
TM_ISDST The daylight saving time flag. This flag is always zero (−1)
for Greenwich Mean Time (GMT).
TM_MDAY The day of the month, 1 to 31.
TM_MIN The minutes after the hour, 0 to 59.
TM_MON The months since January, 0 to 11.
TM_SEC The seconds after the minute, 0 to 59.
TM_WDAY The days since Sunday, 0 to 6.
TM_YDAY The days since January 1, 0 to 365.
TM_YEAR The year.
Example
The st_ctime in the following example was set with a stat call:
"gmtime" st.st_ctime "tm."
ioctl
55──ioctl──fd──command──buffer──┬────────┬─────────────────────────5%
└─length─┘
Function
ioctl invokes the w_ioctl service to issue ioctl commands to a file.
Note: Hierarchical file system (HFS) files and pipes do not support ioctl
commands.
Parameters
fd A file descriptor for an open file.
Note: REXX does not support ioctl commands for sockets.
command
The numeric value for an ioctl command. The commands that can be specified
vary by device and are defined by the device driver.
buffer
The name of a buffer containing the argument to be passed to the device
driver. The argument is limited to 1024 bytes.
length
An optional numeric value indicating the length of the argument. If length is not
specified, the length of the buffer is used.
isatty
55──isatty──fd─────────────────────────────────────────────────────5%
Function
isatty invokes the isatty callable service to determine if a file is a terminal.
Parameters
fd The file descriptor (a number) for the file.
Usage Notes
On return, RETVAL contains either ð (not a tty) or 1 (a tty).
Example
To test if file descriptor ð is a terminal:
"isatty ð"
kill
55──kill──pid──signal──────────────────────────────────────────────5%
Function
kill invokes the kill callable service to send a signal to a process or process group.
Parameters
pid
A number, the process ID of the process or process group to which the caller
wants to send a signal.
signal
The signal to be sent. You can set the value by using a numeric value (see
Appendix A) or the predefined variable beginning with SIG used to derive the
numeric value:
Variable Description
SIGABND Abend
SIGABRT Abnormal termination
SIGALRM Timeout
SIGBUS Bus error
SIGCHLD Child process terminated or stopped
SIGCONT Continue if stopped
SIGDCE Exclusive use by DCE
SIGFPE Erroneous arithmetic operation, such as division by zero or an operation
resulting in an overflow
SIGHUP Hangup detected on the controlling terminal
SIGILL Termination (cannot be caught or ignored)
SIGINT Interactive attention
SIGIO Completion of input or output
SIGIOERR Error on input/output; used by the C runtime library
SIGKILL Termination that cannot be caught or ignored
SIGPIPE Write on a pipe with no readers
SIGPOLL Pollable event
SIGPROF Profiling timer expired
SIGQUIT Interactive termination
SIGSEGV Detection of an incorrect memory reference
SIGSTOP Stop that cannot be caught or ignored
SIGSYS Bad system call
SIGTERM Termination
SIGTRAP Trap used by the ptrace callable service
SIGTSTP Interactive stop
Variable Description
SIGTTIN Read from a controlling terminal attempted by a member of a background
process group
SIGTTOU Write from a controlling terminal attempted by a member of a background
process group
SIGURG High bandwidth data is available at a socket
SIGUSR1 Reserved as application-defined signal 1
SIGUSR2 Reserved as application-defined signal 2
SIGVTALRM Virtual timer expired
SIGXCPU CPU time limit exceeded
SIGXFSZ File size limit exceeded
Usage Notes
1. A caller can send a signal if the real or effective user ID of the caller is the
same as the real or saved set user ID of the intended recipient. A caller can
also send signals if it has appropriate privileges.
2. Regardless of user ID, a caller can always send a SIGCONT signal to a
process that is a member of the same session as the sender.
3. A caller can also send a signal to itself. If the signal is not blocked, at least one
pending unblocked signal is delivered to the sender before the service returns
control. Provided that no other unblocked signals are pending, the signal
delivered is the signal sent.
See “Using the REXX Signal Services” on page 8 for information on using signal
services.
Example
In the following example, assume that pid was assigned a value earlier in the exec:
"kill" pid sighup
lchown
55──lchown──pathname──uid──gid─────────────────────────────────────5%
Function
lchown invokes the lchown callable service to change the owner or group for a file,
directory, or symbolic link.
Parameters
pathname
The pathname for a file, directory, or symbolic link.
uid
The numeric UID for the new owner or the present UID, or −1 if there is no
change to the UID.
GID
The numeric GID for the new group or the present GID, or −1 if there is no
change to the GID.
Usage Notes
1. If lchown's target is a symbolic link, it modifies the ownership of the actual
symbolic link file instead of the ownership of the file pointed to by the symbolic
link.
2. The lchown service changes the owner UID and owner GID of a file. Only a
superuser can change the owner UID of a file.
3. The owner GID of a file can be changed by a superuser, or if a caller meets all
of these conditions:
The effective UID of the caller matches the file's owner UID.
The uid value specified in the change request matches the file's owner UID.
The gid value specified in the change request is the effective GID, or one
of the supplementary GIDs, of the caller.
4. The set-user-ID-on-execution and set-group-ID-on-execution permissions of the
file mode are automatically turned off.
5. If the change request is successful, the change time for the file is updated.
6. Values for both uid and gid must be specified as they are to be set. If you want
to change only one of these values, the other must be set to its present value
to remain unchanged.
Example
In the following example, assume that pathname, uid, and gid were assigned a
value earlier in the exec:
"lchown (pathname) (uid) (gid)"
link
55──link──old_path──new_path───────────────────────────────────────5%
Function
link invokes the link callable service to create a hard link to a file (not a directory);
that is, it creates a new name for an existing file. The new name does not replace
the old one.
Parameters
old_path
A pathname, the current name for the file.
new_path
A pathname, the new name for the file.
Usage Notes
1. The link service creates a link named new_path to an existing file named
old_path. This provides an alternate pathname for the existing file, so that the
file can be accessed by the old name or the new name. The link can be stored
in the same directory as the original file, or in a different directory.
2. The link and the file must be in the same file system.
3. If the link is created successfully, the service increments the link count of the
file. The link count shows how many links exist for a file. If the link is not
created successfully, the link count is not incremented.
4. Links are allowed only to files, not to directories.
5. If the link is created successfully, the change time of the linked-to file is
updated and the change and modification times of the directory that holds the
link are updated.
Example
To create the hard link /usr/bin/grep to the file /bin/grep:
"link /bin/grep /usr/bin/grep"
lseek
55──lseek──fd──position──whence────────────────────────────────────5%
Function
lseek invokes the lseek callable service to change the file offset of a file to a new
position. The file offset is the position in a file from which data is next read or to
which data is next written.
Parameters
fd The file descriptor (a number) for the file whose offset you want to change. The
file descriptor is returned when the file is opened.
position
A number indicating the number of bytes by which you want to change the
offset. If the number is unsigned, the offset is moved forward that number of
bytes; if the number is preceded by a − (minus sign), the offset is moved
backward that number of bytes.
whence
A numeric value that indicates the point from which the offset is calculated. You
can specify a numeric value (see Appendix A) or the predefined variable
beginning with SEEK_ used to derive the appropriate numeric value:
Variable Description
SEEK_CUR Set the file offset to current offset plus the specified offset.
SEEK_END Set the file offset to EOF plus the specified offset.
SEEK_SET Set the file offset to the specified offset.
Usage Notes
1. position gives the length and direction of the offset change. whence states
where the change is to start. For example, assume that a file is 2000 bytes
long, and that the current file offset is 1000:
2. The file offset can be moved beyond the end of the file. If data is written at the
new file offset, there will be a gap between the old end of the file and the start
of the new data. A request to read data from anywhere within that gap
completes successfully, and returns bytes with the value of zero in the buffer
and the actual number of bytes read.
Seeking alone, however, does not extend the file. Only if data is written at the
new offset does the length of the file change.
Example
To change the offset of file descriptor fd (assuming that it was assigned a value
earlier in the exec) to the beginning of the file (offset ð):
"lseek" fd ð seek_set
lstat
55──lstat──pathname──stem──────────────────────────────────────────5%
Function
lstat invokes the lstat callable service to obtain status information about a file.
Parameters
pathname
A pathname for the file.
stem
The name of a stem variable used to return the information. Upon return,
stem.0 contains the number of variables returned. To obtain the desired status
information, you can use a numeric value (see Appendix A) or the predefined
variables beginning with ST_ used to derive the numeric value. See “fstat” on
page 67 for a list of those variables.
Usage Notes
1. If the pathname specified is a symbolic link, the status information returned
relates to the symbolic link, rather than to the file to which the symbolic link
refers.
2. All time values returned are in POSIX format. Time is in seconds since
00:00:00 GMT, January 1, 1970. You can use gmtime to convert it to other
forms.
Example
In the following example, assume that pathname was assigned a value earlier in
the exec:
"lstat (pathname) st."
mkdir
55──mkdir──pathname──mode──────────────────────────────────────────5%
Function
mkdir invokes the mkdir callable service to create a new, empty directory.
Parameters
pathname
A pathname for the directory.
mode
A three- or four-digit number, corresponding to the access permission bits.
Each digit must be in the range ð–7, and at least three digits must be specified.
For more information on permissions, see Appendix B.
Usage Notes
1. The file permission bits specified in mode are modified by the file creation mask
of the calling process (see “umask” on page 165), and are then used to set the
file permission bits of the new directory.
2. The new directory's owner ID is set to the effective user ID (UID) of the calling
process.
3. The mkdir service sets the access, change, and modification times for the new
directory. It also sets the change and modification times for the directory that
contains the new directory.
Example
In the following example, assume that pathname and mode were assigned a value
earlier in the exec:
"mkdir (pathname)" mode
mkfifo
55──mkfifo──pathname──mode─────────────────────────────────────────5%
Function
mkfifo invokes the mknod callable service to create a new FIFO special file.
Parameters
pathname
A pathname for the file.
mode
A three- or four-digit number, corresponding to the access permission bits.
Each digit must be in the range ð–7, and at least three digits must be specified.
For more information on permissions, see Appendix B.
Usage Notes
1. The file permission bits specified in mode are modified by the process's file
creation mask (see “umask” on page 165 ), and then used to set the file
permission bits of the file being created.
2. The file's owner ID is set to the process's effective user ID (UID). The group ID
is set to the group ID (GID) of the directory containing the file.
3. The mknod service sets the access, change, and modification times for the new
file. It also sets the change and modification times for the directory that
contains the new file.
Example
In the following example, assume that pathname was assigned a value earlier in
the exec. The mode 777 grants read-write-execute permission to everyone.
"mkfifo (pathname) 777"
mknod
55──mknod──pathname──mode──major──minor────────────────────────────5%
Function
mknod invokes the mknod callable service to create a new character special file.
You must be a superuser to use this function.
Parameters
pathname
A pathname for the file.
mode
A three- or four-digit number, corresponding to the access permission bits.
Each digit must be in the range ð–7, and at least three digits must be specified.
For more information on permissions, see Appendix B.
major
The device major number corresponds to a device driver supporting a class of
devices (for example, interactive terminals). For information on specifying the
device major number, see OS/390 OpenEdition Planning.
minor
The number that corresponds to a specific device within the class of devices
referred to by the device major number. For information on specifying the
device minor number, see OS/390 OpenEdition Planning.
Usage Notes
1. The file permission bits specified in mode are modified by the process's file
creation mask (see “umask” on page 165 ), and then used to set the file
permission bits of the file being created.
2. The file's owner ID is set to the process's effective user ID (UID). The group ID
is set to the group ID (GID) of the directory containing the file.
3. The mknod service sets the access, change, and modification times for the new
file. It also sets the change and modification times for the directory that
contains the new file.
Example
To create /dev/null with read-write-execute permission for everyone:
"mknod /dev/null 777 4 ð"
mount
55──mount──pathname──name──type──flags──┬──────┬───────────────────5%
└─parm─┘
Function
mount invokes the mount callable service to mount a file system, making the files
in it available for use. You must be a superuser to use this function.
Parameters
pathname
The pathname for the mount point.
name
The name of the file system to be mounted. You must specify HFS data set
names as fully qualified names in uppercase letters. Do not enclose the data
set name in single quotes.
type
The type of file system, as defined by the FILESYSTYPE parameter on the
BPXPRMxx parmlib member (for example, HFS). Specify this as it is specified
on the parmlib member.
flags
A value indicating how the file system is to be mounted. To specify the
information, you can specify a numeric value (see Appendix A), or one or more
of the predefined variables beginning with MTM_. If more than one variable is
specified, they are added together like open flags. (RDONLY and RDWR
cannot be specified together.) The predefined variables used to derive the
appropriate numeric value are:
MTM_NOSUID This specifies that the SETUID and SETGID mode bits
on any executable in this file system are to be ignored
when the program is run.
MTM_RDONLY Mount read-only
MTM_RDWR Mount read-write
MTM_SYNCHONLY Mount must be completed synchronously; that is,
mount() must not return +1.
parm
The name of a variable that contains a parameter string to be passed to the
physical file system. The format and content of the string are specified by the
physical file system that is to perform the logical mount.
For an HFS file system, parm is not used.
Usage Notes
1. In order to mount a file system, the caller must be a superuser.
2. The mount service effectively creates a virtual file system. After a file system is
mounted, references to the pathname that is mounted refer to the root directory
on the mounted file system.
3. A file system can be mounted at only one point.
4. Parameter specifics for the HFS physical file system:
The name value must be uppercase and must be the name of the data set.
The parm parameter is not used.
Example
To mount the HFS data set HFS.BIN.V1R1M0 on the mountpoint /v1r1m0 as a
read-only file system:
"mount /v1r1mð HFS.BIN.V1R1Mð HFS" mtm_rdonly
open
55──open──pathname──o_flags──┬──────┬──────────────────────────────5%
└─mode─┘
Function
open invokes the open callable service to access a file and create a file descriptor
for it. The file descriptor is returned in RETVAL.
Parameters
pathname
A pathname for the file.
o_flags
One or more numeric values that describe how the file is to be opened. You
can specify a numeric value (see Appendix A) or any of the predefined
variables that begin with O_ used to derive the appropriate numeric value. For
example, the numeric values 128+3 or 131 or the predefined variables
o_creat+o_rdwr could be used to specify how the file is to be opened:
Variable Description
O_APPEND Set the offset to EOF before each write.
O_CREAT Create the file if it does not exist.
O_EXCL Fail if the file does exist and O_CREAT is set.
O_NOCTTY Do not make this file a controlling terminal for the calling
process.
O_NONBLOCK Do not block an open, a read, or a write on the file (do not
wait for terminal input).
O_RDONLY Open for read-only.
O_RDWR Open for read and write.
O_SYNC Force synchronous updates.
O_TRUNC Write, starting at the beginning of the file.
O_WRONLY Open for write-only.
mode
A three- or four-digit number, corresponding to the access permission bits. If
this optional parameter is not supplied, the mode is defaulted to ððð, which is
useful for opening an existing file. For an explanation of how mode is handled if
you are creating a file, see the usage notes below.
Each digit must be in the range ð–7, and at least three digits must be specified.
For more information on permissions, see Appendix B.
Usage Notes
When a file is created with the O_CREAT or O_EXCL options, the file permission
bits as specified in the mode parameter are modified by the process's file creation
mask (see “umask” on page 165 ), and then used to set the file permission bits of
the file being created.
O_EXCL Option: If the O_EXCL bit is set and the create bit is not set, the
O_EXCL bit is ignored.
O_TRUNC Option: Turning on the O_TRUNC bit opens the file as though it had
been created earlier but never written into. The mode and owner of the file do not
change (although the change time and modification time do); but the file's contents
are discarded. The file offset, which indicates where the next write is to occur,
points to the first byte of the file.
O_NONBLOCK Option: A FIFO special file is a shared file from which the first
data written is the first data read. The O_NONBLOCK option is a way of
coordinating write and read requests between processes sharing a FIFO special
file. It works this way, provided that no other conditions interfere with opening the
file successfully:
If a file is opened read-only and O_NONBLOCK is specified, the open request
succeeds. Control returns to the caller immediately.
If a file is opened write-only and O_NONBLOCK is specified, the open request
completes successfully, provided that another process has the file open for
reading. If another process does not have the file open for reading, the request
ends with RETVAL set to −1.
If a file is opened read-only and O_NONBLOCK is omitted, the request is
blocked (control is not returned to the caller) until another process opens the
file for writing.
If a file is opened write-only and O_NONBLOCK is omitted, the request is
blocked (control is not returned to the caller) until another process opens the
file for reading.
If the O_SYNC update option is used, the program is assured that all data
updates have been written to permanent storage.
Example
To open or create the file /u/linda/my.exec with read-write-execute permission for
the owner, and to read and write starting at the beginning of the file:
"open /u/linda/my.exec" o_rdwr+o_trunc+o_creat 7ðð
opendir
55──opendir──pathname──────────────────────────────────────────────5%
Function
opendir invokes the opendir callable service to open a directory stream so that it
can be read by rddir. The file descriptor is returned in RETVAL.
Parameters
pathname
A pathname for the directory.
Usage Notes
1. You can use opendir and closedir together with the rddir syscall command,
but not with the readdir command. The rddir command reads a directory in the
readdir callable service format. Alternatively, you can simply use the readdir
syscall command to read an entire directory and format it in a stem.
2. The opendir service opens a directory so that the first rddir service (see “rddir”
on page 121) starts reading at the first entry in the directory.
3. RETVAL is a file descriptor for a directory only. It can be used only as input to
services that expect a directory file descriptor. These services are closedir,
rewinddir, and rddir.
Example
To open the directory /u/edman:
"opendir /u/edman"
pathconf
55──pathconf──pathname──name───────────────────────────────────────5%
Function
pathconf invokes the pathconf callable service to determine the current values of a
configurable limit or option (variable) that is associated with a file or directory. The
limit or option is returned in RETVAL.
Parameters
pathname
A pathname for a file or directory.
name
A numeric value that indicates which limit is returned. You can specify a
numeric value (see Appendix A) or the predefined variable beginning with PC_
used to derive the appropriate numeric value.
Variable Description
PC_LINK_MAX Maximum value of a file's link count.
PC_MAX_CANON Maximum number of bytes in a terminal canonical
input line.
PC_MAX_INPUT Minimum number of bytes for which space will be
available in a terminal input queue; therefore, the
maximum number of bytes a portable application may
require to be typed as input before reading them.
PC_NAME_MAX Maximum number of bytes in a filename (not a string
length; count excludes a terminating null).
PC_PATH_MAX Maximum number of bytes in a pathname (not a
string length; count excludes a terminating null).
PC_PIPE_BUF Maximum number of bytes that can be written
atomically when writing to a pipe.
PC_POSIX_CHOWN_RESTRICTED Change ownership ( “chown” on page 33) function is
restricted to a process with appropriate privileges,
and to changing the group ID (GID) of a file only to
the effective group ID of the process or to one of its
supplementary group IDs.
PC_POSIX_NO_TRUNC Pathname components longer than 255 bytes
generate an error.
PC_POSIX_VDISABLE Terminal attributes maintained by the system can be
disabled using this character value.
Usage Notes
1. If name refers to MAX_CANON, MAX_INPUT, or _POSIX_VDISABLE, the
following applies:
If pathname does not refer to a terminal file, the service returns −1 in
RETVAL and sets ERRNO to EINVAL.
2. If name refers to NAME_MAX, PATH_MAX, or _POSIX_NO_TRUNC, the
following applies:
If pathname does not refer to a directory, the service still returns the
requested information using the parent directory of the specified file.
3. If name refers to PC_PIPE_BUF, the following applies:
Example
To determine the maximum number of bytes allowed in a pathname in the root
directory:
"pathconf /" pc_name_max
pause
55──pause──────────────────────────────────────────────────────────5%
Function
pause invokes the pause callable service to suspend execution of the calling
thread until delivery of a signal that either executes a signal-catching function or
ends the thread. See “Using the REXX Signal Services” on page 8 for more
information.
Usage Notes
1. A thread that calls pause does not resume processing until a signal is delivered
with an action to either process a signal-handling function or end the thread.
Some signals can be blocked by the thread's signal mask; see “sigprocmask”
on page 146 for details.
2. If an incoming unblocked signal ends the thread, pause never returns to the
caller.
3. A return code is set when any failures are encountered that prevent this
function from completing successfully.
pfsctl
55──pfsctl──type──command──buffer──┬────────┬──────────────────────5%
└─length─┘
Function
pfsctl invokes the pfsctl service to issue physical file system (PFS) control
commands to a PFS. The meaning of the command and argument are specific to
and defined by the PFS.
Parameters
type
The type of file system, as defined by the FILESYSTYPE parameter on the
BPXPRMxx parmlib member—for example, HFS. Specify this as it is specified
on the parmlib member.
command
The name of a PFS control command.
buffer
The name of a buffer containing the argument to be passed to the PFS. The
argument is limited to 4095 bytes.
length
An optional numeric value, indicating the length of the argument. If length is not
specified, the length of the buffer is used. The maximum length allowed is 4095
bytes.
Usage Notes
1. This service is provided for communication between a program running in a
user process and a physical file system.
It is similar to ioctl, but the command is directed to the physical file system
itself rather than to, or for, a particular file or device.
2. As an example of how you could use this function in writing a physical file
system, consider the requirement to display status and performance statistics
about the physical file system. You can collect this information in the physical
file system, but you need a way to display it to the user.
With pfsctl, your status utility program can easily fetch the information it needs
from the physical file system.
pipe
55──pipe──stem─────────────────────────────────────────────────────5%
Function
pipe invokes the pipe callable service to create a pipe; or an I/O channel that a
process can use to communicate with another process, another thread (in this
same process or another process), or, in some cases, with itself. Data can be
written into one end of the pipe and read from the other end.
Parameters
stem
On return, stem.0 contains the number of variables returned. Two stem
variables are returned:
stem.1 The file descriptor for the end of the pipe that you read from
stem.2 The file descriptor for the end of the pipe that you write to
Usage Notes
When the pipe call creates a pipe, the O_NONBLOCK and FD_CLOEXEC flags are
turned off on both ends of the pipe. You can turn these flags on or off by invoking:
“f_setfl” on page 62 for the flag O_NONBLOCK
“f_setfd” on page 61 for the flag FD_CLOEXEC
Example
To create a pipe:
"pipe pfd."
pt3270
55──pt327ð──fd──option─────────────────────────────────────────────5%
Function
pt3270 invokes the tcgetattr and tcsetattr callable services to query, set, and reset
3270 passthrough mode.
A REXX program running under a shell started from the OMVS TSO/E command
can use this service to send and receive a 3270 data stream or issue TSO/E
commands.
Parameters
fd The file descriptor for the file.
option
A number that identifies the service being requested:
Number Service
1 Query 3270 passthrough support for this file.
On return, RETVAL will contain a code for the current state of the
file descriptor, or -1 if there is an error.
0 or -1 This file cannot support 3270 passthrough mode.
1 This file can support 3270 passthrough mode.
3 This file is currently in 3270 passthrough mode.
2 Set 3270 passthrough support for this file. If this is attempted on a
file that does not support 3270 passthrough mode, on return
RETVAL contains -1 and ERRNO contains the value for ENOSYS.
3 Reset 3270 passthrough support for this file.
Example
The following is an example of a REXX program that can accept a TSO/E
command as its argument and issue the command through OMVS using 3270
passthrough mode. This REXX program would be located in the HFS and run as a
command from the shell.
/\ rexx \/
parse arg cmd
if cmd=' then return
address syscall
'pt327ð 1 2' /\ set passthrough mode on stdout \/
if retval=-1 then
do
say 'Cannot set passthrough mode' retval errno errnojr
return
end
buf='ff51ððððððð1ððð1'x ||, /\ OMVS passthrough command \/
d2c(length(cmd),4) || cmd
"write 1 buf" /\ send command to OMVS \/
"read 1 ibuf 1ððð" /\ discard the response \/
'pt327ð 1 3' /\ reset passthrough mode \/
return ð
quiesce
55──quiesce──name──────────────────────────────────────────────────5%
Function
quiesce invokes the quiesce callable service to quiesce a file system, making the
files in it unavailable for use. You must be a superuser to quiesce a file system.
Parameters
name
The name of the file system to be quiesced, specified as the name of an HFS
data set. You must specify HFS data set names as fully qualified names in
uppercase letters. Do not enclose the data set name in single quotes.
Usage Notes
1. After a quiesce service request, the file system is unavailable for use until a
subsequent unquiesce service request is received.
2. Users accessing files in a quiesced HFS file system are suspended until an
unquiesce request for the file system is processed. Other file systems may
send an EAGAIN instead of suspending the user.
3. If a file system that is not mounted is quiesced, that file system cannot be
mounted until the file system is unquiesced. This ensures that no one can use
the file system while it is quiesced.
Example
To quiesce an HFS data set named HFS.USR.SCHOEN:
"quiesce HFS.USR.SCHOEN"
rddir
55──rddir──fd──variable──length────────────────────────────────────5%
Function
rddir invokes the readdir callable service to read multiple name entries from a
directory and format it in the readdir callable service format. To format this type of
information in a stem, see “readdir” on page 125. The number of entries read is
returned in RETVAL.
Parameters
fd The file descriptor (a number) for the directory to be read.
variable The name of the buffer into which the directory entries are to be
read.
length The size of the buffer. After the read completes, the length of
variable is the size of the buffer. The number of entries is returned
in RETVAL.
Usage Notes
1. You can use this command only with file descriptors opened using the opendir
syscall command. The rddir syscall command reads a directory in the readdir
callable service format. You can use opendir, rewinddir, and closedir
together with the rddir syscall command, but not with the readdir syscall
command. Alternatively, you can simply use the readdir syscall command to
read an entire directory and format it in a stem.
2. The buffer contains a variable number of variable-length directory entries. Only
full entries are placed in the buffer, up to the buffer size specified, and the
number of entries is returned.
3. Each directory entry returned has the following format:
2-byte Entry_length. The total entry length, including itself.
2-byte Name_length. Length of the following Member_name subfield.
Member_name. A character field of length Name_length. This name is not
null-terminated.
File system specific data. If name_length + 4 = entry_length, this subfield is
not present.
The entries are packed together, and the length fields are not aligned on any
particular boundary.
4. The buffer returned by one call to the readdir service must be used again on
the next call to the readdir service to continue reading entries from where you
left off. The buffer must not be altered between calls, unless the directory has
been rewound.
5. The end of the directory is indicated in either of two ways:
A RETVAL of ð entries is returned.
Some physical file systems may return a null name entry as the last entry
in the caller's buffer. A null name entry has an Entry_length of 4 and a
Name_length of ð.
Both conditions should be checked for by the caller of the readdir service.
Example
To read the entries from the directory with file descriptor 4 into the buffer named
buf, which is 300 bytes long:
"rddir 4 buf 3ðð"
read
55──read──fd──variable──length─────────────────────────────────────5%
Function
read invokes the read callable service to read a specified number of bytes from a
file into a buffer that you provide. The number of bytes read is returned in RETVAL.
Parameters
fd The file descriptor (a number) for the file to be read.
variable The name of the buffer into which the data is to be read.
Usage Notes
Length: The value of length is not checked against any OS/390 OpenEdition
system limit.
Access Time: A successful read updates the access time of the file read.
Origin of Bytes Read: If the file specified by fd is a regular file, or any other type
of file where a seek operation is possible, bytes are read from the file offset
associated with the file descriptor. A successful read increments the file offset by
the number of bytes read.
For files where no seek operation is possible, there is no file offset associated with
the file descriptor. Reading begins at the current position in the file.
Number of Bytes Read: When a read request completes, the RETVAL field shows
the number of bytes actually read—a number less than or equal to the number
specified as length. The following are some reasons why the number of bytes read
might be less than the number of bytes requested:
Fewer than the requested number of bytes remained in the file; the end of file
was reached before length bytes were read.
The service was interrupted by a signal after some but not all of the requested
bytes were read. (If no bytes were read, the return value is set to —1 and an
error is reported.)
The file is a pipe, FIFO, or special file and fewer bytes than length specified
were available for reading.
There are several reasons why a read request might complete successfully with no
bytes read (that is, with RETVAL set to ð). For example, zero bytes are read in
these cases:
The call specified a length of zero.
The starting position for the read was at or beyond the end of the file.
The file being read is a FIFO file or a pipe, and no process has the pipe open
for writing.
The file being read is a slave pseudoterminal and a zero-length canonical file
was written to the master.
Nonblocking: If a process has a pipe open for reading with nonblocking specified,
a request to read from the file ends with a return value of —1 and a “Resource
temporarily unavailable” return code. But if nonblocking was not specified, the read
request is blocked (does not return) until some data is written or the pipe is closed
by all other processes that have the pipe open for writing.
Both master and slave pseudoterminals operate this way, too, except that how they
act depends on how they were opened. If the master or the slave is opened
blocking, the reads are blocked if there is no data. If it is opened nonblocking,
EAGAIN is returned if there is no data.
SIGTTOU Processing: The read service causes signal SIGTTIN to be sent under
the following conditions:
The process is attempting to read from its controlling terminal, and
The process is running in a background process group, and
The SIGTTIN signal is not blocked or ignored, and
The process group of the process is not orphaned.
If these conditions are met, SIGTTIN is sent. If SIGTTIN has a handler, the handler
gets control and the read ends with the return code set to EINTRO. If SIGTTIN is
set to default, the process stops in the read and continues when the process is
moved to the foreground.
Example
In the following example, assume that fd was assigned a value earlier in the exec.
This reads 1000 characters from the file fd into the buffer buf:
"read (fd) buf 1ððð"
readdir
55──readdir──pathname──stem──┬───────┬─────────────────────────────5%
└─stem2─┘
Function
readdir invokes the opendir, readdir, and closedir callable services to read multiple
name entries from a directory and format the information in a stem.
Parameters
pathname A pathname for a directory.
Usage Notes
The rddir command reads a directory in the readdir callable service format. You
can use opendir and closedir together with the rddir syscall command, but not
with the readdir syscall command. The readdir syscall command reads a directory
and formats it in a stem.
Example
To read the root directory and return information about the directory entries and a
stat structure for each directory entry:
"readdir / root. rootst."
readfile
55──readfile──pathname──stem───────────────────────────────────────5%
Function
readfile invokes the open, read, and close callable services to read from a text file
and format it in a stem.
Parameters
pathname A pathname for the file to be read.
stem Upon return, stem.0 contain the number of lines read. stem.1
through stem.n (where n is the number of lines) each contains
a line read.
Usage Notes
1. The maximum allowable length of a line in the file is 1024 characters; if there
are lines longer than that, the RC is −23.
2. The newline characters that delimit the lines in a text file are stripped before
the lines are saved in the stem.
Example
In the following example, assume that pathname was assigned a value earlier in
the exec:
"readfile (pathname) file."
readlink
55──readlink──pathname──┬──────────┬───────────────────────────────5%
└─variable─┘
Function
readlink invokes the readlink callable service to read the contents of a symbolic
link. A symbolic link is a file that contains the pathname for another file. The length,
in bytes, of the contents of the link is returned in RETVAL. If a variable is specified,
the pathname is read into it.
Parameters
pathname A pathname for the symbolic link.
variable The name of the variable to hold the contents of the symbolic
link. After the link is read, the length of the variable is the
length of the symbolic link.
Example
In the following example, assume that sl and linkbuf were assigned a value earlier
in the exec:
"readlink (sl) linkbuf"
realpath
55──realpath──pathname──variable───────────────────────────────────5%
Function
realpath invokes the realpath callable service to resolve a pathname to a full
pathname without any symbolic links.
Parameters
pathname
The pathname to resolve.
variable
The name of the variable to contain the resolved pathname that is returned.
Example
The following example retrieves the real pathname for the working directory:
"realpath . mycwd"
rename
55──rename──old_pathname──new_pathname─────────────────────────────5%
Function
rename invokes the rename callable service to change the name of a file or
directory.
Parameters
old_pathname An existing pathname.
Usage Notes
The rename service changes the name of a file or directory from old_pathname to
new_pathname. When renaming finishes successfully, the change and modification
times for the parent directories of old_pathname and new_pathname are updated.
The calling process needs write permission for the directory containing
old_pathname and the directory containing new_pathname. The caller does not
need write permission for the files themselves.
If old_pathname is the name of a file, new_pathname must also name a file, not a
directory. If new_pathname is an existing file, it is unlinked. Then the file specified
as old_pathname is given new_pathname. The pathname new_pathname always
stays in existence; at the beginning of the operation, new_pathname refers to its
original file, and at the end, it refers to the file that used to be old_pathname.
new_pathname cannot be a directory under old_pathname; that is, the old directory
cannot be part of the pathname prefix of the new one.
Example
In the following example, assume that old and new were assigned values earlier in
the exec:
"rename (old) (new)"
rewinddir
55──rewinddir──fd──────────────────────────────────────────────────5%
Function
rewinddir invokes the rewinddir callable service to “rewind,” or reset, to the
beginning of an open directory. The next call to rddir reads the first entry in the
directory.
Parameters
fd The file descriptor (a number) returned from an opendir syscall
command. This is the file descriptor for the directory to be
reset.
Usage Notes
You can use this command only with file descriptors opened using the opendir
syscall command. The rddir syscall command reads a directory in the readdir
callable service format. You can use opendir, rewinddir, and closedir together
with the rddir syscall command, but not with the readdir syscall command.
Alternatively, you can simply use readdir syscall command to read an entire
directory and format it in a stem.
If the contents of the directory you specify have changed since the directory was
opened, a call to the rewinddir service will reset the pointer into the directory to the
beginning so that a subsequent call to the readdir service will read the new
contents.
Example
To rewind the directory associated with file descriptor 4:
"rewinddir 4"
rmdir
55──rmdir──pathname────────────────────────────────────────────────5%
Function
rmdir invokes the rmdir callable service to remove a directory. The directory must
be empty.
Parameters
pathname A pathname for the directory.
Usage Notes
1. The directory must be empty.
2. If the directory is successfully removed, the change and modification times for
the parent directory are updated.
3. If the link count of the directory becomes zero and no process has the directory
open, the directory itself is deleted. The space occupied by the directory is
freed for new use.
4. If any process has the directory open when the last link is removed, the
directory itself is not removed until the last process closes the directory. New
files cannot be created under a directory after the last link is removed, even if
the directory is still open.
Example
To remove the directory /u/ehk0:
"rmdir /u/ehkð"
setegid
55──setegid──gid───────────────────────────────────────────────────5%
Function
setegid invokes the setegid callable service to set the effective group ID (GID) of
the calling process.
Parameters
gid
The numeric GID that the calling process is to assume.
Usage Notes
1. If gid is equal to the real group ID or the saved set group ID of the process, the
effective group ID is set to gid.
2. If gid is not the same as the real group ID, and the calling process has the
appropriate privileges, the effective group ID is set to gid.
3. The setegid service does not change any supplementary group IDs of the
calling process.
Example
In the following example, assume that gid was assigned a value earlier in the exec:
"setegid" gid
seteuid
55──seteuid──uid───────────────────────────────────────────────────5%
Function
seteuid invokes the seteuid callable service to set the effective user ID (UID) of the
calling process.
Parameters
uid
The numeric UID that the calling process is to assume.
Usage Notes
1. A user can switch to superuser authority (with an effective UID of ð) if the user
is permitted to the BPX.SUPERUSER FACILITY class profile within RACF.
2. If uid is the same as the process's real or saved set UID, or the user has the
appropriate privilege, the seteuid service sets the effective UID to be the same
as uid.
Example
In the following example, assume that uid was assigned a value earlier in the exec:
"seteuid (uid)"
setgid
55──setgid──gid────────────────────────────────────────────────────5%
Function
setgid invokes the setgid callable service to set the real, effective, and saved set
group IDs (GIDs) for the calling process.
Parameters
gid
The numeric GID that the calling process is to assume.
Usage Notes
1. If gid is equal to the real group ID or the saved set group ID of the process, the
effective group ID is set to gid.
2. If gid is not the same as the real group ID, and the calling process has the
appropriate privileges, then the real, saved set, and effective group IDs are set
to gid.
3. The setgid service does not change any supplementary group IDs of the calling
process.
Example
In the following example, assume that gid was assigned a value earlier in the exec:
"setgid (gid)"
setgrent
55──setgrent───────────────────────────────────────────────────────5%
Function
setgrent invokes the setgrent callable service to rewind, or reset to the beginning,
the group database, allowing repeated searches. For more information, see
“getgrent” on page 76.
setpgid
55──setpgid──pid──pgid─────────────────────────────────────────────5%
Function
setpgid invokes the setpgid callable service to place a process in a process group.
To identify the group, you specify a process group ID. You can assign a process to
a different group, or you can start a new group with that process as its leader.
Parameters
pid
The numeric process ID (PID) of the process to be placed in a process group.
If the ID is specified as ð, the system uses the process ID of the calling
process.
pgid
The ID of the process group. If the ID is specified as ð, the system uses the
process group ID indicated by pid.
Usage Notes
1. The process group ID to be assigned to the group must be within the calling
process's session.
2. The subject process (the process identified by pid) must be a child of the
process that issues the service, and it must be in the same session; but it
cannot be the session leader. It can be the caller.
Example
In the following example, assume that pid and pgid were assigned values earlier in
the exec:
"setpgid" pid pgid
setpwent
55──setpwent───────────────────────────────────────────────────────5%
Function
setpwent invokes the setpwent callable service to effectively rewind the user
database to allow repeated searches. For more information, see “getpwent” on
page 91.
setrlimit
55──setrlimit──resource──stem──────────────────────────────────────5%
Function
setrlimit invokes the setrlimit callable service to set resource limits for the calling
process. A resource limit is a pair of values; one specifies the current limit and the
other a maximum limit.
Parameters
resource
The resource whose limit is being set. The maximum resource limit is
RLIM_INFINITY.
You can use the predefined variables beginning with RLIMIT_, or their
equivalent numeric values, to specify the resource. (See Appendix A for the
numeric values.)
stem
The name of the stem variable used to set the limit. stem.1 is the first word,
which sets the current limit, and stem.2 is the second word, which sets the
maximum limit. The values for each word depend on the resource specified. To
specify no limit, use RLIM_INFINITY.
Usage Notes
1. The current limit may be modified to any value that is less than or equal to the
maximum limit. For the RLIMIT_CPU, RLIMIT_NOFILE, and RLIMIT_AS
resources, if the setrlimit service is called with a current limit that is lower than
the current usage, the setrlimit service fails with an EINVAL errno.
2. The maximum limit may be lowered to any value that is greater than or equal to
the current limit.
3. The maximum limit can only be raised by a process that has superuser
authority.
4. Both the current limit and maximum limit can be changed via a single call to
setrlimit.
5. If the setrlimit service is called with a current limit that is greater than the
maximum limit, setrlimit returns an EINVAL errno.
6. The resource limit values are propagated across exec and fork. An exception
exists for exec. If a daemon process invokes exec and it invoked setuid before
invoking exec, the limit values are set based on the limit values specified in
OS/390 OpenEdition parmlib member BPXPRMxx.
7. For a process that is not the only process within an address space, the
RLIMIT_CPU and RLIMIT_AS limits are shared with all the processes within the
address space. For RLIMIT_CPU, when the current limit is exceeded, action is
taken on the first process within the address space. If the action is termination,
all the processes within the address space are terminated.
8. In addition to the RLIMIT_CORE limit values, CORE dump defaults are set by
SYSMDUMP defaults. See the OS/390 MVS Initialization and Tuning Guide for
information on setting up SYSMDUMP defaults via the IEADMR00 parmlib
member.
9. Core dumps are taken in 4160-byte increments. Therefore, RLIMIT_CORE
values affect the size of core dumps in 4160-byte increments. For example, if
the RLIMIT_CORE current limit value is 4000, core dumps will contain no data.
If the RLIMIT_CORE current limit value is 8000, the maximum size of a core
dump is 4160 bytes.
10. Limits may have an infinite value of RLIM_INFINITY.
11. When setting RLIMIT_NOFILE, the maximum limit cannot exceed the system
defined limit of 65 535.
12. When setting RLIMIT_NOFILE, the current limit must be set higher than the
value of the highest open file descriptor. Attempting to lower the current limit to
a value less than or equal to the highest open file descriptor results in an error
of EINVAL.
13. When setting RLIMIT_FSIZE, a limit of 0 prevents the creation of new files and
the expansion of existing files.
Example
To reduce the maximum number of open files to 100 and current limit to 50:
r.2=1ðð
r.1=5ð
"setrlimit" rlimit_nofile r.
setsid
55──setsid──sid────────────────────────────────────────────────────5%
Function
setsid invokes the setsid callable service to create a new session with the calling
process as its session leader. The caller becomes the group leader of a new
process group.
Parameters
sid
The process ID of the calling process, which becomes the session or process
group ID of the new process group.
Usage Notes
The calling process does not have a controlling terminal.
Example
In the following example, assume that sid was assigned a value earlier in the exec:
"setsid" sid
setuid
55──setuid──uid────────────────────────────────────────────────────5%
Function
setuid invokes the setuid callable service to set the real, effective, and saved set
user IDs for the calling process.
Parameters
uid
The numeric UID the process is to assume.
Usage Notes
1. A user can switch to superuser authority (with an effective UID of ð) if the user
is permitted to the BPX.SUPERUSER FACILITY class profile within RACF.
2. If uid is the same as the process's real UID or the saved set UID, the setuid
service sets the effective UID to be the same as uid.
If uid is not the same as the real UID of the process, and the calling process
has appropriate privileges, then the real, effective, and saved set UIDs are set
to uid.
Example
In the following example, assume that uid was assigned a value earlier in the exec:
"setuid" uid
sigaction
55──sigaction──signal──new_handler──new_flag────────────────────────5
5──old_handler──old_flag───────────────────────────────────────────5%
Function
sigaction invokes the sigaction callable service to examine, change, or both
examine and change the action associated with a specific signal for all the threads
in the process.
Note: All threads within a process share the signal handlers (a set of additional
signals to be masked) and the flags specified by the sigaction callable
service.
Parameters
signal
The signal, as specified by a numeric value or a predefined variable beginning
with SIG.
Variable Description
SIGABND Abend
SIGABRT Abnormal termination
SIGALRM Timeout
SIGBUS Bus error
SIGCHLD Child process terminated or stopped
SIGCONT Continue if stopped
SIGDCE Exclusive use by DCE
SIGFPE Erroneous arithmetic operation, such as division by zero or an operation
resulting in an overflow
SIGHUP Hangup detected on the controlling terminal
SIGILL Termination (cannot be caught or ignored)
SIGINT Interactive attention
SIGIO Completion of input or output
SIGIOERR Error on input/output; used by the C runtime library
SIGKILL Termination that cannot be caught or ignored
SIGPIPE Write on a pipe with no readers
SIGPOLL Pollable event
SIGPROF Profiling timer expired
SIGQUIT Interactive termination
SIGSEGV Detection of an incorrect memory reference
SIGSTOP Stop that cannot be caught or ignored
SIGSYS Bad system call
SIGTERM Termination
SIGTRAP Trap used by the ptrace callable service
Variable Description
SIGTSTP Interactive stop
SIGTTIN Read from a controlling terminal attempted by a member of a background
process group
SIGTTOU Write from a controlling terminal attempted by a member of a background
process group
SIGURG High bandwidth data is available at a socket
SIGUSR1 Reserved as application-defined signal 1
SIGUSR2 Reserved as application-defined signal 2
SIGVTALRM Virtual timer expired
SIGXCPU CPU time limit exceeded
SIGXFSZ File size limit exceeded
new_handler
Specifies the new setting for handling the signal. The following predefined
variables may be used for new_handler:
Variable Description
SIG_CAT Set signal handling to catch the signal.
SIG_DFL Set signal handling to the default action.
SIG_IGN Set signal handling to ignore the signal.
SIG_QRY Query the handling for that signal.
new_flag
Used to modify the behavior of the specified signal. Specify one of these:
Variable Description
ð Use the default behavior.
SA_NOCLDWAIT Do not create zombie processes when child
processes exit.
SA_RESETHAND Reset the signal action to the default, SIG_DFL,
when delivered.
SA_NOCLDSTOP Do not generate SIGCHLD when the child processes
stop.
old_handler
A variable name for the buffer where the system returns the old (current) signal
handling action.
old_flag
The name of the variable that will store the old (current) signal action flags.
Usage Notes
1. If new_handler is set to the action SIG_DFL for a signal that cannot be caught
or ignored, the sigaction request is ignored and the return value is set to ð.
2. Setting a signal action to ignore for a signal that is pending causes the pending
signal to be discarded.
3. Setting signal action SIG_IGN or catch for signals SIGSTOP or SIGKILL is not
allowed.
4. Setting signal action SIG_IGN for SIGCHLD or SIGIO is not allowed.
5. The sigaction caller's thread must be registered for signals. You can register
the thread by calling syscalls('SIGON'). If the thread is not registered for
signals, the sigaction service fails with an ERRNO of EINVAL and ERRNOJR of
JRNotSigSetup.
Example
To catch a SIGALRM signal:
"sigaction" sigalrm sig_cat ð "prevhndlr prevflag"
sigpending
55──sigpending──variable───────────────────────────────────────────5%
Function
sigpending invokes the sigpending callable service to return the union of the set of
signals pending on the thread and the set of signals pending on the process.
Pending signals at the process level are moved to the thread that called the
sigpending callable service.
Parameters
variable
The name of the variable that will store a string of 64 characters with values ð
or 1, representing the 64 bits in a signal mask.
Example
To invoke sigpending:
"sigpending sigset"
sigprocmask
55──sigprocmask──number──new_mask──variable────────────────────────5%
Function
sigprocmask invokes the sigprocmask callable service to examine or change the
calling thread's signal mask.
Parameters
number
To specify the action to be taken on the thread's signal mask, you can specify
a numeric value (see Appendix A) or the predefined variable beginning with
SIG_ used to derive the appropriate numeric value. Use one of the following
predefined variables:
Variable Description
SIG_BLOCK Add the signals in new_mask to those to be blocked for this
thread.
SIG_SETMASK Replace the thread's signal mask with new_mask.
SIG_UNBLOCK Delete the signals in new_mask from those blocked for this
thread.
new_mask
The new signal mask, a string of 64 characters with values ð or 1. The first
character represents signal number 1. A string shorter than 64 characters is
padded on the right with zeros. Mask bits set on represent signals that are
blocked. For more information on signals, see “Using the REXX Signal
Services” on page 8.
variable
The name of the buffer that will store the old signal mask, a string of 64
characters with values ð or 1, representing the 64 bits in a signal mask. Mask
bits set on represent signals that are blocked. A zero indicates that no signal
mask was returned.
Usage Notes
1. The sigprocmask service examines, changes, or both examines and changes
the signal mask for the calling thread. This mask is called the thread's signal
mask. If there are any pending unblocked signals, either at the process level or
at the current thread's level after changing the signal mask, at least one of the
signals is delivered to the thread before the sigprocmask service returns.
2. You cannot block the SIGKILL and the SIGSTOP signals. If you call the
sigprocmask service with a request that would block those signals, that part of
your request is ignored and no error is indicated.
3. A request to block signals that are not supported is accepted, and a return
value of zero is returned.
4. All pending unblocked signals are moved from the process level to the current
thread.
Example
In the following example, assume that newsigset was assigned a value earlier in
the exec:
"sigprocmask" sig_setmask newsigset "oldsigset"
sigsuspend
55──sigsuspend──mask───────────────────────────────────────────────5%
Function
sigsuspend invokes the sigsuspend callable service to replace a thread's current
signal mask with a new signal mask; then it suspends the caller's thread until
delivery of a signal whose action is either to process a signal-catching service or to
end the thread.
Parameters
mask
The new signal mask, a string of up to 64 characters with the values ð or 1.
The first character represents signal number 1. A string shorter than 64
characters is padded on the right with zeros. For more information on signals,
see “Using the REXX Signal Services” on page 8.
Usage Notes
1. The caller's thread starts running again when it receives one of the signals not
blocked by the mask set by this call, or a system failure occurs that sets the
return code to some value other than EINTR.
2. The signal mask represents a set of signals that will be blocked. Blocked
signals do not “wake up” the suspended service. The signals SIGSTOP and
SIGKILL cannot be blocked or ignored; they are delivered to the program no
matter what the signal mask specifies.
3. If the signal action is to end the thread, the sigsuspend service does not return.
4. All pending unblocked signals are moved from the process level to the current
thread.
Example
In the following example, assume that sigmask was assigned a value earlier in the
exec:
"sigsuspend" sigmask
sleep
55──sleep──number──────────────────────────────────────────────────5%
Function
sleep invokes the sleep callable service to suspend running of the calling thread
(process) until either the number of seconds specified by number has elapsed, or a
signal is delivered to the calling thread to invoke a signal-catching function or end
the thread.
Parameters
number
The number of seconds to suspend the process. For more information on
signals, see “Using the REXX Signal Services” on page 8.
Usage Notes
1. The suspension can actually be longer than the requested time, due to the
scheduling of other activity by the system.
2. The sleep service suspends the thread running for a specified number of
seconds, or until a signal is delivered to the calling thread that invokes a
signal-catching function or ends the thread. An unblocked signal received
during this time prematurely “wakes up” the thread. The appropriate
signal-handling function is invoked to handle the signal. When that
signal-handling function returns, the sleep service returns immediately, even if
there is “sleep time” remaining.
3. The sleep service returns a zero in RETVAL if it has slept for the number of
seconds specified. If the time specified by number has not elapsed when the
sleep service is interrupted because of the delivery of a signal, the sleep
service returns the unslept amount of time (the requested time minus the time
actually slept when the signal was delivered) in seconds. Any time consumed
by signal-catching functions is not reflected in the value returned by the sleep
service.
4. The following are usage notes for a SIGALRM signal generated by the alarm or
kill calls during the execution of the sleep call:
If the calling thread has SIGALRM blocked prior to calling the sleep
service, the sleep service does not return when SIGALRM is generated,
and the SIGALRM signal is left pending when sleep returns.
If the calling process has SIGALRM ignored when the SIGALRM signal is
generated, then the sleep service does not return and the SIGALRM signal
is ignored.
If the calling process has SIGALRM set to a signal-catching function, that
function interrupts the sleep service and receives control. The sleep service
returns any unslept amount of time, as it does for any other type of signal.
5. An EC6 abend is generated when the caller's PSW key or RB state prevents
signals from being delivered.
Example
In the following example, assume that timer was assigned a value earlier in the
exec:
"sleep (timer)"
spawn
55──spawn──pathname──fd_count──fd_map──arg_stem──env_stem──────────5%
Function
spawn invokes the spawn callable service to create a new process, called a child
process, to run a hierarchical file system (HFS) executable file. It remaps the calling
process's file descriptors for the child process.
Parameters
pathname
A pathname for the executable file. Pathnames can begin with or without a
slash:
fd_count
The number of file descriptors that can be inherited by the child process. In the
new process, all file descriptors greater than or equal to fd_count are closed.
fd_map
A stem variable. The stem index specifies the child's file descriptor; for
example, stem.0 specifies the child's file descriptor ð. This array selects the file
descriptors to be inherited. The value assigned to the variable indicates the
parent's file descriptor that will be mapped to the child's file descriptor. For
example, if stem.0 is 4, the child process inherits the parent's file descriptor 4
as its descriptor ð. Any of the stem variables that contains a negative number
or a nonnumeric value is closed in the child.
arg_stem
A stem variable. stem.0 contains the number of arguments you are passing to
the program. The first argument should always specify the absolute or relative
pathname of the program to be executed. If a relative pathname is used and
PATH is specified, PATH is used to resolve the name; otherwise, the name is
processed as relative to the current directory. If a PATH environment variable is
not passed, the first argument should specify the absolute pathname or a
relative pathname for the program.
env_stem
A stem variable. stem.0 contains the number of environment variables that you
want the program to be run with. To propagate the current environment, pass
__environment . Specify each environment variable as VNAME=value.
Usage Notes
1. The new process (called the child process) inherits the following attributes from
the process that calls spawn (called the parent process):
Session membership.
Real user ID.
Real group ID.
Example
In the following example, /bin/ls is run mapping its STDOUT and STDERR to file
descriptors 4 and 5, which were previously opened in the exec, and STDIN is
closed:
map.ð=-1
map.1=4
map.2=5
parm.ð=2
parm.1='/bin/ls'
parm.2='/'
'spawn /bin/ls 3 map. parm. _ _environment.'
spawnp
55──spawnp──filename──fd_count──fd_map──arg_stem──env_stem─────────5%
Function
spawnp invokes the spawn callable service and creates a new process, called a
child process, to run a hierarchical file system (HFS) executable file. spawnp
functions identically to the spawn function, except that it uses the PATH
environment variable to resolve relative filenames.
stat
55──stat──pathname──stem───────────────────────────────────────────5%
Function
stat invokes the stat callable service to obtain status about a specified file. You
specify the file by its name. If the pathname specified refers to a symbolic link, the
symbolic link name is resolved to a file and the status information for that file is
returned. To obtain status information about a symbolic link, rather than the file it
refers to, see “lstat” on page 105.
To use a file descriptor to obtain this information, see “fstat” on page 67.
Parameters
pathname
A pathname for the file.
stem
The name of a stem variable used to return the information. Upon return,
stem.0 contains the number of variables returned. You can use the predefined
variables beginning with ST_ or their equivalent numeric values to access the
values they represent. (See Appendix A for the numeric values.)
Variable Description
ST_AAUDIT Auditor audit information.
ST_ATIME Time of last access.
ST_AUDITID RACF File ID for auditing.
ST_BLKSIZE File block size.
ST_BLOCKS Blocks allocated.
ST_CCSID Coded character set ID.
ST_CRTIME File creation time.
ST_CTIME Time of last file status change.
ST_DEV Device ID of the file.
ST_EXTLINK External symbolic link flag, set to ð or 1.
ST_FID File identifier.
ST_FILEFMT Format of the file. To specify the format, you can specify a
numeric value (see Appendix A) or one of the following
predefined variables used to derive the appropriate numeric
value:
S_FFBINARY Binary data
S_FFCR Text data delimited by a carriage return
character
S_FFCRLF Text data delimited by carriage return and
line feed characters
S_FFLF Text data delimited by a line feed
character
S_FFLFCR Text data delimited by a line feed and
carriage return characters
S_FFNA Text data with the file format not specified
S_FFNL Text data delimited by a newline character
ST_GENVALUE General attribute values.
ST_GID Group ID of the group of the file.
ST_INO File serial number.
ST_MAJOR Major number for a character special file.
ST_MINOR Minor number for a character special file.
Variable Description
ST_MODE File mode, permission bits only.
ST_MTIME Time of last data modification.
ST_NLINK Number of links.
ST_RTIME File backup time stamp (reference time).
ST_SETGID Set Group ID on execution flag, set to ð or 1.
ST_SETUID Set User ID on execution flag, set to ð or 1.
ST_SIZE File size for a regular file, in bytes. If file size exceeds
231−1 bytes, size is expressed in megabytes, using an M
(for example, 3123M).
ST_STICKY Sticky bit flag (keep loaded executable in storage), set to ð
or 1.
ST_TYPE Numeric value that represents the file type for this file. You
can use a numeric value (see Appendix A) or any of the
predefined variables that begin with S_ to determine the file
type:
S_ISCHR Character special file
S_ISDIR Directory
S_ISFIFO FIFO special file
S_ISREG Regular file
S_ISSYM Symbolic link
ST_UAUDIT Area for user audit information.
ST_UID User ID of the owner of the file.
The stem variable stem.st_type is a number that represents the file type for this
file. You can use the predefined variables beginning with S_ or their equivalent
numeric values to determine the file type. For example, if stem.st_type is
S_ISDIR, the file is a directory.
Usage Notes
All time fields in stem are in POSIX format. You can use gmtime to convert it to
other forms.
Example
In the following example, assume that path was assigned a value earlier in the
exec:
"stat (path) st."
statfs
55──statfs──name──stem─────────────────────────────────────────────5%
Function
statfs invokes the statfs callable service to obtain status information about a
specified file system.
Parameters
name
The name of the file system to be mounted, specified as the name of an HFS
data set. You must specify the HFS data set name as a fully qualified name in
uppercase letters. Do not enclose the data set name in single quotes.
stem
The name of a stem variable used to return the information. On return, stem.0
contains the number of variables returned. You can use the predefined
variables beginning with STFS_ or their equivalent numeric values to access
the status values they represent. (See Appendix A for the numeric values.) For
example, stem.stfs_avail accesses the number of blocks available in the file
system.
Variable Description
STFS_AVAIL Space available to unprivileged users in block-size units.
STFS_BFREE Total number of free blocks.
STFS_BLOCKSIZE Block size.
STFS_FAVAIL Number of free file nodes available to unprivileged users.
STFS_FFREE Total number of free file nodes.
STFS_FILES Total number of file nodes in the file system.
STFS_FRSIZE Fundamental file system block size.
STFS_FSID File system ID set by the logical file system.
STFS_INUSE Allocated space in block-size units.
STFS_INVARSEC Number of seconds the file system will remain unchanged.
STFS_NAMEMAX Maximum length of file name.
STFS_NOSUID SETUID and SETGID are not supported.
STFS_RDONLY File system is read-only.
STFS_TOTAL Total space in block-size units.
Example
In the following example, assume that fsname was assigned a value earlier in the
exec:
"statfs (fsname) st."
statvfs
55──statvfs──pathname──stem────────────────────────────────────────5%
Function
statvfs invokes the statvfs callable service to obtain status information about a file
system, given the name of a file in the file system.
Parameters
pathname
The name of a file in a file system for which status information is to be
obtained.
stem
The name of a stem variable used to return the information. On return, stem.0
contains the number of variables returned. You can use the predefined
variables beginning with STFS_ or their equivalent numeric values (see
Appendix A) to access the status values they represent. For example,
stem.stfs_avail accesses the number of blocks available in the file system.
Variable Description
STFS_AVAIL Space available to unprivileged users in block-size units.
STFS_BFREE Total number of free blocks.
STFS_BLOCKSIZE Block size.
STFS_FAVAIL Number of free file nodes available to unprivileged users.
STFS_FFREE Total number of free file nodes.
STFS_FILES Total number of file nodes in the file system.
STFS_FRSIZE Fundamental file system block size.
STFS_FSID File system ID set by the logical file system.
STFS_INUSE Allocated space in block-size units.
STFS_INVARSEC Number of seconds the file system will remain unchanged.
STFS_NAMEMAX Maximum length of file name.
STFS_NOSUID SETUID and SETGID are not supported.
STFS_RDONLY File system is read-only.
STFS_TOTAL Total space in block-size units.
Example
In the following example, assume that fsname was assigned a value earlier in the
exec:
"statvfs (fsname) st."
symlink
55──symlink──pathname──linkname────────────────────────────────────5%
Function
symlink invokes the symlink callable service to create a symbolic link to a
pathname. This creates a symbolic link file.
Parameters
pathname
A pathname for the file for which you are creating a symbolic link.
linkname
The pathname for the symbolic link.
Usage Notes
Like a hard link (described in “link” on page 102), a symbolic link allows a file to
have more than one name. The presence of a hard link guarantees the existence of
a file, even after the original name has been removed. A symbolic link, however,
provides no such assurance; in fact, the file identified by pathname need not exist
when the symbolic link is created. In addition, a symbolic link can cross file system
boundaries.
If the symbolic link is not the last component of the original pathname, remaining
components of the original pathname are resolved from there. When a symbolic link
is the last component of a pathname, it may or may not be resolved. Resolution
depends on the function using the pathname. For example, a rename request does
not have a symbolic link resolved when it appears as the final component of either
the new or old pathname. However, an open request does have a symbolic link
resolved when it appears as the last component. When a slash is the last
component of a pathname, and it is preceded by a symbolic link, the symbolic link
is always resolved.
Because the mode of a symbolic link cannot be changed, its mode is ignored
during the lookup process. Any files and directories to which a symbolic link refers
are checked for access permission.
Example
To create a symbolic link named /bin for the file /v.1.1.0/bin:
"symlink /v.1.1.ð/bin /bin"
sysconf
55──sysconf──name──────────────────────────────────────────────────5%
Function
sysconf invokes the sysconf callable service to get the value of a configurable
system variable.
Parameters
name
A numeric value that specifies the configurable variable to be returned. You
can specify a numeric value (see Appendix A) or the predefined variable
beginning with SC_ used to derive the appropriate numeric value:
Variable Description
SC_ARG_MAX The maximum length of all arguments and
environment strings to exec()
SC_CHILD_MAX The maximum number of simultaneous processes per
real user ID
SC_CLK_TCK The number of intervals per second used in defining
the type clock_t, which is used to measure process
execution times
SC_JOB_CONTROL Support for job control
SC_NGROUPS_MAX Maximum number of simultaneous supplementary
group IDs per process
SC_OPEN_MAX Maximum number of simultaneous open files per
process
SC_SAVED_IDS Support for saved set-user-IDs and set-group-IDs
SC_THREAD_TASKS_MAX_NP Constant for querying the maximum number of
threaded tasks per calling process
SC_THREADS_MAX_NP Constant for querying the maximum number of
threads per calling process
SC_TZNAME_MAX The number of bytes supported for the name of a
time zone
SC_VERSION The integer value 199009L
SC_2_CHAR_TERM Constant for querying whether the system supports at
least one raw mode terminal
Usage Notes
SC_MAX_THREADS_NP and SC_MAX_THREAD_TASKS_NP return the limits
defined for the caller's process, not the systemwide limits.
Example
To determine the maximum number of files that a single process can have open at
one time:
"sysconf" sc_open_max
time
55──time───────────────────────────────────────────────────────────5%
Function
time returns in RETVAL the time in POSIX format (seconds since the Epoch,
00:00:00 on 1 January 1970). You can use gmtime to convert it to other forms.
times
55──times──stem────────────────────────────────────────────────────5%
Function
times invokes the times callable service to collect information about processor time
used by the current process or related processes. The elapsed time since the
process was dubbed is returned in RETVAL. This value is of the type clock_t,
which needs to be divided by sysconf(_SC_CLK_TK) to convert it to seconds. For
OS/390 OpenEdition, this value is expressed in hundredths of a second.
Parameters
stem
The name of a stem variable used to return the information. Upon return,
stem.0 contains the number of variables returned. Four variables are returned
in the stem. To access the stem variables, use a numeric value or the
predefined variables beginning with TMS_ used to derive that numeric value.
(For the numeric values, see Appendix A.) For example, you could specify
stem.4 or stem.tms_cstime to obtain system CPU values:
Variable Description
TMS_CSTIME The sum of system CPU time values and child system CPU
time values for all waited-for child processes that have
terminated. Zero if the current process has no waited-for
children.
TMS_CUTIME The sum of user CPU time values and child user CPU time
values for all waited-for child processes that have
terminated. Zero if the current process has no waited-for
children.
TMS_STIME The system CPU time of current process in hundredths of a
second. This is the task control block (TCB) time
accumulated while running in the kernel address space.
TMS_UTIME The user CPU time of current process in hundredths of a
second. This includes the TCB and service request block
(SRB) time of the calling process minus the TCB time
accumulated while running in the kernel address space.
Usage Notes
Processor times for a child process that has ended are not added to the
TMS_CUTIME and TMS_CSTIME of the parent process until the parent issues a
wait or waitpid for that child process.
Example
"times tm."
trunc
55──trunc──pathname──file_size─────────────────────────────────────5%
Function
trunc invokes the trunc callable service to change the size of the file identified by
pathname.
Parameters
pathname
The pathname of the file.
file_size
The new size of the file, in bytes.
Usage Notes
1. The file specified must be a regular file to which the calling process has write
access.
2. The file size changes beginning from the first byte of the file. If the file was
previously larger than the new size, the data from file_size to the original end of
the file is removed. If the file was previously shorter than file_size, bytes
between the old and new lengths are read as zeros.
3. If file_size is greater than the current file size limit for the process, the request
fails with EFBIG, and the SIGXFSZ signal is generated for the process.
Example
To set the file size of /tmp/xxx to 1000 bytes:
"trunc /tmp/xxx 1ððð"
ttyname
55──ttyname──fd──variable──────────────────────────────────────────5%
Function
ttyname invokes the ttyname callable service to obtain the pathname of the
terminal associated with the file descriptor.
Parameters
fd The file descriptor (a number) for the character special file for the terminal.
variable
The name of the variable that stores the pathname for the character special file
for the terminal.
Usage Notes
This service does not return −1 to indicate a failure. If the file descriptor is incorrect,
a null string is returned.
Example
To obtain the pathname for file descriptor ð:
"ttyname ð path"
umask
55──umask──mask────────────────────────────────────────────────────5%
Function
umask invokes the umask callable service to change your process's file mode
creation mask. The file mode creation mask is used by the security package
(RACF) to turn off permission bits in the mode parameter specified. Bit positions
that are set in the file mode creation mask are cleared in the mode of the created
file.
Parameters
mask
A permission bit mask that you specify as a three-digit number. Each digit must
be in the range ð to 7, and all digits must be specified. For more information on
permissions, see Appendix B.
Usage Notes
1. The umask service changes the process's file creation mask. This mask
controls file permission bits that are set whenever the process creates a file.
File permission bits that are turned on in the file creation mask are turned off in
the file permission bits of files created by the process. For example, if a call to
the open service, BPX1OPN, specifies a mode argument with file permission
bits, the process's file creation mask affects that argument: bits that are on in
the mask will be turned off in the mode argument, and therefore in the mode of
the created file.
2. Only the file permission bits of new mask are used.
Example
To create a mask that sets read-write-execute permission on for the owner of the
file and off for everyone else:
"umask ð77"
uname
55──uname──stem────────────────────────────────────────────────────5%
Function
uname invokes the uname callable service to obtain information about the OS/390
OpenEdition system you are running on.
Parameters
stem
The name of a stem variable used to return the information. Upon return,
stem.0 contains the number of variables returned. To access the information,
you can specify a numeric value (see Appendix A) or the predefined variables
beginning with U_ that derive the appropriate numeric value. For example, both
stem.1 and stem.u_sysname access the name of the operating system.
Variable Description
U_MACHINE The name of the hardware type on which the system is
running.
U_NODENAME The name of this node within the communication network.
U_RELEASE The current release level of this implementation.
U_SYSNAME The name of this implementation of the operating system
(OS/390).
U_VERSION The current version level of this release.
Example
"uname uts."
unlink
55──unlink──pathname───────────────────────────────────────────────5%
Function
unlink invokes the unlink callable service to remove a directory entry.
Parameters
pathname
A pathname for the directory entry. The directory entry could be identified by a
pathname for a file, the name of a hard link to a file, or the name of a symbolic
link.
Usage Notes
1. If the name specified refers to a symbolic link, the symbolic link file named by
pathname is deleted.
2. If a file is deleted (that is, if the unlink service request is successful and the link
count becomes zero), the contents of the file are discarded, and the space it
occupied is freed for reuse. However, if another process (or more than one)
has the file open when the last link is removed, the file is not removed until the
last process closes it.
3. When the unlink service is successful in removing the directory entry and
decrementing the link count, whether or not the link count becomes zero, it
returns control to the caller with RETVAL set to ð. It updates the change and
modification times for the parent directory, and the change time for the file itself
(unless the file is deleted).
4. Directories cannot be removed using unlink. To remove a directory, refer to
“rmdir” on page 131.
Example
In the following example, assume that file was assigned a value earlier in the exec:
"unlink (file)"
unmount
55──unmount──name──flags───────────────────────────────────────────5%
Function
unmount invokes the umount callable service to unmount a file system; that is, it
removes a file system from the file hierarchy. You must be a superuser to unmount
a file system.
Parameters
name
The name of the file system to be unmounted, specified as the name of an
HFS data set. You must specify the HFS data set name as a fully qualified
name in uppercase letters. Do not enclose the data set name in single quotes.
flags
The unmount options, expressed as a numeric value. You can specify a
numeric value (see Appendix A) or the predefined variable beginning with
MTM_ used to derive the appropriate numeric value:
Variable Description
MTM_DRAIN An unmount drain request. All uses of the file system are
normally ended before the file system is unmounted.
MTM_FORCE An unmount force request. The file system is unmounted
immediately, forcing any users of the named file system to
fail. All data changes made up to the time of the request
are saved. If there is a problem saving data, the unmount
continues and the data may be lost. So that data will not be
lost, you must issue an unmount immediate request before
an unmount force request.
MTM_IMMED An unmount immediate request. The file system is
unmounted immediately, forcing any users of the named file
system to fail. All data changes made up to the time of the
request are saved. If there is a problem saving data, the
unmount request fails.
MTM_NORMAL A normal unmount request. If no one is using the named
file system, the unmount request is done. Otherwise, the
request is rejected.
MTM_RESET A reset unmount request. This stops a previous unmount
drain request.
MTM_REMOUNT Unmounts the file system, changes the mount mode, and
remounts the file system. A read/write mount mode
changes to read-only. A read-only mount mode changes to
read/write.
Usage Notes
1. A file system that has file systems mounted on it cannot be unmounted. Any
child file systems must be unmounted first.
2. A reset request can stop only an unmount service drain request. There is no
effect if it is issued when there is no umount request outstanding.
Example
To request a normal unmount of the file system HFS.USR.CRISP:
"unmount HFS.USR.CRISP" mtm_normal
unquiesce
55──unquiesce──name──flag──────────────────────────────────────────5%
Function
unquiesce invokes the unquiesce callable service to unquiesce a file system,
making the files in it available for use again. You must be a superuser to use this
function.
Parameters
name
The name of the file system to be unquiesced. You must specify an HFS data
set name as a fully qualified name in uppercase letters. Do not enclose the
data set name in single quotes.
flag
A number specifying the type of unquiesce:
0 Normal unquiesce
1 Forced unquiesce. Request is allowed even if the requester process
is not the process that made the quiesce request.
Usage Notes
An unquiesce service makes a file system available for use again following a
previous quiesce request.
Example
To request a normal unquiesce of the file system HFS.USR.ELIZAB:
"unquiesce HFS.USR.ELIZAB ð'
utime
55──utime──pathname──atime──mtime──────────────────────────────────5%
Function
utime invokes the utime callable service to set the access and modification times of
a file.
Parameters
pathname
A pathname for the file.
atime
A numeric value for the new access time for the file, specified as POSIX time
(seconds since the Epoch, 00:00:00 1 January 1970).
mtime
A numeric value for the new modification time for the file, specified as POSIX
time (seconds since the Epoch, 00:00:00 1 January 1970).
Example
In the following example, assume that file, atm, and mtm were assigned values
earlier in the exec:
"utime (file)" atm mtm
wait
55──wait──stem─────────────────────────────────────────────────────5%
Function
wait invokes the wait callable service to obtain the status of any child process that
has ended or stopped. You can use the wait service to obtain the status of a
process that is being debugged with the ptrace facilities. The term child refers to a
child process created by a fork as well as a process attached by ptrace.
Parameters
stem
The name of a stem variable used to return the information. Upon return,
stem.0 contains the number of variables returned. To access the information in
the stem variables, you can specify a numeric value (see Appendix A) or the
predefined variables beginning with W_ that derive the appropriate numeric
value.
Variable Description
W_CONTINUED Process continued from stop.
W_EXITSTATUS The exit status of the child process.
W_IFEXITED The child process ended normally.
W_IFSIGNALED The child process ended because of a signal that
was not caught.
W_IFSTOPPED Wait if the child process is stopped.
W_STAT3 Byte 3 of the BPXYWAST macro, documented in
OS/390 OpenEdition Programming: Assembler
Callable Services Reference .
W_STAT4 Byte 4 of the BPXYWAST macro, documented in
OS/390 OpenEdition Programming: Assembler
Callable Services Reference .
W_STOPSIG The signal number that caused the child process to
stop.
W_TERMSIG The signal number that caused the child process to
end.
Usage Notes
1. The wait service suspends execution of the calling thread until one of the
requested child or debugged processes ends or until it obtains information
about the process that ended. If a child or debugged process has already
ended but its status has not been reported when wait is called, the routine
immediately returns with that status information to the caller.
2. If the WUNTRACED option is specified, the foregoing also applies for stopped
children or stopped debugged processes.
3. The wait service always returns status for stopped debugged processes, even if
WUNTRACED is not specified.
4. If status is available for one or more processes, the order in which the status is
reported is unspecified.
Note: A debugged process is one that is being monitored for debugging purposes
with the ptrace service.
Example
See “Set Up a Signal to Enforce a Time Limit for a Program” on page 194 for an
example of signal coding that interprets the stem this returns:
"wait wstat."
waitpid
55──waitpid──pid──stem──option─────────────────────────────────────5%
Function
waitpid invokes the wait callable service to obtain the status of a child process that
has ended or stopped. You can use the wait service to obtain the status of a
process that is being debugged with the ptrace facilities. The term child refers to a
child process created by a fork as well as a process attached by ptrace.
Parameters
pid
A numeric value indicating the event the caller is waiting upon:
A value greater than zero is assumed to be a process ID. The caller waits
for the child or debugged process with that specific process ID to end or to
stop.
A value of zero specifies that the caller is waiting for any children or
debugged processes with a process group ID equal to the caller's to end or
to stop.
A value of −1 specifies that the caller is waiting for any of its children or
debugged processes to end or to stop.
If the value is negative and less than −1, its absolute value is assumed to
be a process group ID. The caller waits for any children or debugged
processes with that process group ID to end or to stop.
stem
The name of a stem variable used to return the information. Upon return,
stem.0 contains the number of variables returned. To access the information in
the stem variables, you can use numeric values (see Appendix A), or the
predefined variables beginning with W_ (see their description in “wait” on
page 172).
options
A numeric value or its equivalent predefined variable beginning with W_ that
indicates the wait options for this invocation of the wait service. These options
can be specified separately or together. (For the numeric values, see
Appendix A.)
Variable Description
ð Wait for the child process to end (default processing)
W_NOHANG The wait service does not suspend execution of the calling
process if status is not immediately available for one of the
child processes specified by Process_ID.
W_UNTRACED The wait service also returns the status of any child
processes specified by Process_ID that are stopped, and
whose status has not yet been reported since they stopped.
If this option is not specified, the wait service returns only
the status of processes that end.
Usage Notes
1. Use waitpid when you want to wait for a specified child process. The pid
argument specifies a set of child processes for which status is requested;
waitpid returns the status of a child process from this set.
2. The waitpid service suspends execution of the calling thread until one of the
requested child or debugged processes ends or until it obtains information
about the process that ended. If a child or debugged process has already
ended but its status has not been reported when waitpid is called, the routine
immediately returns with that status information to the caller.
3. If the WUNTRACED option is specified, the foregoing also applies for stopped
children or stopped debugged processes. A debugged process is one that is
being monitored for debugging purposes with the ptrace service.
4. The wait service always returns status for stopped debugged processes, even if
WUNTRACED is not specified.
5. If status is available for one or more processes, the order in which the status is
reported is unspecified.
Example
See “Set Up a Signal to Enforce a Time Limit for a Program” on page 194 for an
example of signal coding that interprets the stem this returns:
write
55──write──fd──variable──┬────────┬────────────────────────────────5%
└─length─┘
Function
write invokes the write callable service to copy data to a buffer and then write it to
an open file. The number of bytes written is returned in RETVAL.
Parameters
fd The file descriptor (a number) for a file.
variable
The name of the variable that is to store the data to be written to the file.
length
The number of bytes to be written to the file identified by fd. If you want a
length longer than 4096 bytes, specify the length parameter. If you do not
specify length, the length of variable is used, up to a maximum length of 4096
bytes. A variable longer than 4096 bytes is truncated to 4096, and RC is set to
4.
Usage Notes
1. Within the variable, you can use the predefined variables beginning with ESC_
the same way you use C language escape sequences to avoid code page
dependence with some control characters. For example:
buf='line 1' || esc_n
appends a newline character to the string 'line 1'.
ESC_A Alert (bell)
ESC_B Backspace
ESC_F Form feed (new page)
ESC_N Newline
ESC_R Carriage return
ESC_T Horizontal tab
ESC_V Vertical tab
2. Return codes:
4 indicates one of these:
– If length was specified, the number of characters specified by length is
not the same as the length of variable. The data is truncated or padded
as required. The characters used for padding are arbitrarily selected.
– If length was not specified, 4 indicates that a variable longer than 4096
bytes was truncated to 4096.
−24 indicates that storage could not be obtained for the buffer.
3. File Offset: If fd specifies a regular file or any other type of file on which you
can seek, the write service begins writing at the file offset associated with that
file descriptor. A successful write operation increments the file offset by the
number of bytes written. If the incremented file offset is greater than the
previous length of the file, the file is extended: the length of the file is set to the
new file offset.
If the file descriptor refers to a file on which you cannot seek, the service
begins writing at the current position. No file offset is associated with such a
file.
If the file was opened with the “append” option, the write routine sets the file
offset to the end of the file before writing output.
4. Number of Bytes Written: Ordinarily, the number of bytes written to the output
file is the number you specify in the length parameter. (This number can be
zero. If you ask to write zero bytes, the service simply returns a return value of
zero, without attempting any other action.)
If the length you specify is greater than the remaining space on the output
device, fewer bytes than you requested are written. When at least 1 byte is
written, the write is considered successful. The return value shows the number
of bytes written. An attempt to write again to the same file, however, causes an
ENOSPC error unless you are using a pseudoterminal. With a pseudoterminal,
if there is not enough room in the buffer for the whole write, the number of
bytes that can fit are written, and the number of bytes written is returned.
However, on the next write (assuming the buffer is still full) there is a block or
EAGAIN is returned, depending on whether the file was opened blocking or
nonblocking.
Similarly, fewer bytes are written if the service is interrupted by a signal after
some but not all of the specified number of bytes are written. The return value
shows the number of bytes written. If no bytes were written before the routine
was interrupted, the return value is −1 and an EINTR error is reported.
5. The write service causes signal SIGTTOU to be sent under all the following
conditions:
The process is attempting to write to its controlling terminal.
TOSTOP is set as a terminal attribute.
The process is running in a background process group.
The SIGTTOU signal is not blocked or ignored.
The process is not an orphan.
If all the conditions are met, SIGTTOU is sent.
6. Write requests to a pipe (FIFO) are handled in the same as write requests to a
regular file, with the following exceptions:
There is no file offset associated with a pipe; each write request appends to
the end of the pipe.
If the size of the write request is less than or equal to the value of the
PIPE_BUFF variable (described in the pathconf service), the write is
guaranteed to be atomic. The data is not interleaved with data from other
write processes on the same pipe. If the size of the write request is greater
than the value of PIPE_BUFF, the data can be interleaved, on arbitrary
boundaries, with writes by other processes, whether or not the
O_NONBLOCK flag is set.
Example
In the following example, assume that fd and buf were assigned values earlier in
the exec:
"write" fd "buf"
writefile
55──writefile──pathname──mode──stem────────────────────────────────5%
Function
writefile invokes the open, write, and close callable services to write text files, with
lines up to 1024 characters long.
Parameters
pathname
A pathname for the file.
mode
A three- or four-digit number, corresponding to the access permission bits.
Each digit must be in the range ð–7, and at least three digits must be specified.
For more information on permissions, see Appendix B.
stem
The name of a stem variable used to return the information written to the file.
Upon return, stem.0 contains the number of variables that are written. stem.1
through stem.n, where n is the total number of variables written, each contain a
line to be written. A newline is written to the file following each line.
Within the stem, you can use the predefined variables beginning with ESC_ the
same way you use C language escape sequences to avoid code page
dependence with some control characters. See the usage notes for “write” on
page 176.
Usage Notes
File I/O stops when writefile sets a return code. writefile can set the following
return codes:
4 A line is longer than 1024 characters.
8 A write was attempted, but failed. RETVAL, ERRNO, and ERRNOJR
contain the return values from the write callable service.
For further usage notes, see:
“close” on page 34
“open” on page 111
“write” on page 176
Example
In the following example, assume that fname and the stem file. were assigned
values earlier in the exec:
"writefile (fname) 6ðð file."
The first three examples can run in TSO/E, batch, or from the shell; they begin with
the call syscalls('ON').
The following line saves the results from the previous example in a text file:
'writefile /u/schoen/root.dir 777 root.'
The program uses open, close, and EXECIO. To read standard input, it accesses
the file /dev/fd0.
For the getopts function called in this program, see “Parse Arguments Passed to a
REXX program: The getopts Function” on page 182.
address syscall
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ Verify that exactly one operand or a pfs type was specified. \/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
if __argv.ð=3 & __argv.2='-t' then
return fstype(__argv.3)
if __argv.ð<>2 then
do
say 'Syntax: unmount <name> or unmount -t <filesystype>'
return 2
end
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ Determine if the name is a pathname. If so, determine file system \/
/\ name via stat(). Otherwise, use the name as entered. \/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
'stat (__argv.2) st.'
if retval =ð & st.st_type=s_isdir then
do
getmntent mnt. x2d(st.st_dev)
fsn=mnt.mnte_fsname.1
end
else
fsn=__argv.2
Notes:
1. The file descriptor map is set up so that the file descriptor for the new file being
created is remapped to file descriptor 1 (standard output) for the new process.
File descriptors 0 and 2 will not be opened in the new process.
2. The first parameter is set to the pathname for the file being spawned.
Additional parameters are set in the format the program expects. In this case,
they specify a long directory listing for the /bin directory.
3. The new process is spawned to run /bin/ls. File descriptors greater than or
equal to 3 are not available to the new process. fd.0 to fd.2 are used in
remapping file descriptors from the parent. The current environment for the
parent is passed to the new process.
For detailed information about these services, see OS/390 OpenEdition File System
Interface Reference.
Security
The file system server services are available only to a registered server. Only a
superuser can use the callable service v_reg to register the process as a server.
The server services can bypass system security for file access.
Tokens
Many tokens flow across the server interface. The types of tokens are:
VFS Represents a mounted file system.
vnode Represents a file or directory that is currently in use. This identifier is
valid only until the token is released, using the v_rel callable service.
FID Uniquely identifies a file or directory in a particular mounted file system;
the file or directory may or may not be currently in use. This identifier is
valid across mounting and unmounting of the file system, as well as
OS/390 OpenEdition restarts.
You must specify tokens as variable names, not as strings. See “Specifying a
Syscall Command” on page 17 for information on specifying variable names. When
a token is returned to the exec, the value of the token is stored in the variable.
When a token variable is used as a parameter on a syscall command, the token
value is extracted from the variable. The format for a token is 8 bytes of binary
data.
v_create
55──v_create──vntoken──filename──type──mode──stem──vntoken2─────────5
5──┬──────────────┬────────────────────────────────────────────────5%
└─major──minor─┘
Function
v_create invokes the v_create callable service to create a new file in the directory
represented by vntoken. The file can be a regular, FIFO, or character special file.
Parameters
vntoken
A variable name that contains the vnode token for the directory in which the file
filename is to be created.
filename
The name of the file. It must not contain null characters.
type
A number used to specify the type of file to be created: a regular, FIFO, or
character special file. You can specify one of the predefined variables
beginning with S_ to set the value—for example, S_ISREG. For a list of the
variables, see “fstat” on page 67.
mode
A three-digit number, corresponding to the access permission bits. Each digit
must be in the range ð–7, and all three digits must be specified. For more
information on permissions, see Appendix B.
stem
The name of a stem variable used to return the status information. Upon return,
stem.0 contains the number of variables that are returned. To obtain the
desired status information, you can use a numeric value or the predefined
variables beginning with ST_ used to derive the numeric value. See “stat” on
page 155 for a list of the predefined variables or Appendix A for the numeric
values.
vntoken2
A variable name that will contain the vntoken of the created file on return.
major
For a character special file (S_ISCHR), the device major number. For a
complete description, see “mknod” on page 108.
minor
For a character special file (S_ISCHR), the device minor number. For a
complete description, see “mknod” on page 108.
Usage Notes
1. If the file named in filename already exists, the v_create service returns a
failing return code, and no vnode token is returned.
2. The caller is responsible for freeing vnode tokens returned by the service by
calling to the v_rel service when they are no longer needed.
Example
In the following example, assume that filenm and vnod were assigned values earlier
in the exec:
"v_create vnod (filenm)" s_isreg 777 "st. filetok"
Chapter 5. OpenMVS Virtual File System (VFS) Server Syscall Commands 199
v_fstatfs
v_fstatfs
55──v_fstatfs──vntoken──stem───────────────────────────────────────5%
Function
v_fstatfs invokes the v_fstatfs callable service to return file system status for the
file system containing the file or directory represented by the specified vntoken.
Parameters
vntoken
A variable name that contains the vnode token for a file or directory in the file
system whose status is to be checked.
stem
The name of a stem variable used to return the status information. Upon return,
stem.0 contains the number of variables that are returned. To obtain the
desired status information, you can use a numeric value or the predefined
variables beginning with STFS_ used to derive the numeric value. For
example, stem.stfs_avail accesses the number of blocks available in the file
system. See “statfs” on page 157 for a list of the predefined variables, or
Appendix A for the numeric values.
Example
In the following example, assume that vnod was assigned a value earlier in the
exec:
" v_fstatfs vnod st."
v_get
55──v_get──vfstoken──fid──vntoken──────────────────────────────────5%
Function
v_get invokes the v_get callable service to return a vnode token for the file or
directory represented by the input FID within the mounted file system represented
by the input VFS token.
Parameters
vfstoken
A variable name that contains the VFS token for the file system where the file
identified by fid resides.
fid A variable that contains a file ID. File IDs are returned in the file attribute
structure in the stem index ST_FID.
vntoken
A variable name that stores the vnode token for the requested file.
Usage Notes
1. The FID (file identifier) uniquely identifies a file in a particular mounted file
system, and its validity persists across mounting and unmounting of the file
system, as well as OS/390 OpenEdition restarts. This distinguishes the FID
from the vnode token, which relates to a file in active use, and whose validity
persists only until the token is released via the v_rel callable service.
A server application uses v_get to convert an FID to a vnode token when it is
preparing to use a file, since the vnode token identifies the file to the other
services.
2. The FID for a file is returned in a stem variable by such services as v_rpn and
v_lookup.
3. The caller is responsible for freeing vnode tokens returned by v_get by calling
to the v_rel service when they are no longer needed.
Example
In the following example, assume that vfs and st.st_fid were assigned values earlier
in the exec:
"v_get vfs st.st_fid vnod"
Chapter 5. OpenMVS Virtual File System (VFS) Server Syscall Commands 201
v_getattr
v_getattr
55──v_getattr──vntoken──stem───────────────────────────────────────5%
Function
v_getattr invokes the v_getattr callable service to get the attributes of the file
represented by vntoken.
Parameters
vntoken
A variable name that contains the vnode token of the file for which the
attributes are returned.
stem
The name of a stem variable used to return the file attribute information. Upon
return, stem.0 contains the number of attribute variables returned. To obtain the
desired information, you can use a numeric value or the predefined variables
beginning with ST_ used to derive the numeric value. See “stat” on page 155
for a list of the variables, or Appendix A for the numeric values.
Example
In the following example, assume that vnod was assigned a value earlier in the
exec:
"v_getattr vnod attr."
v_link
55──v_link──vntoken──filename──vntoken2────────────────────────────5%
Function
v_link invokes the v_link callable service to create a link to the file specified by
vntoken in the directory specified by vntoken2. The link is a new name, filename,
identifying an existing file.
Parameters
vntoken
A variable name that contains the vnode token for the file being linked to.
filename
The new name for the existing file.
vntoken2
A variable name that contains the vnode token for the directory to which
filename is to be added.
Usage Notes
1. v_link creates a link named filename to an existing file specified by vntoken.
This provides an alternative pathname for the existing file, so that you can
access it by the old name or the new name. You can store the link under the
same directory as the original file, or under a different directory on the same file
system.
2. If the link is created successfully, the service routine increments the link count
of the file. The link count shows how many links to a file exist. (If the link is not
created successfully, the link count is not incremented.)
3. Links are not allowed to directories.
4. If the link is created successfully, the change time of the linked-to file is
updated, as are the change and modification times of the directory that
contains filename—that is, the directory that holds the link.
Example
In the following example, assume that filetok, name, and dirtok were assigned
values earlier in the exec:
"v_link filetok (name) dirtok"
Chapter 5. OpenMVS Virtual File System (VFS) Server Syscall Commands 203
v_lockctl
v_lockctl
55──v_lockctl──v_command──stem─────────────────────────────────────5%
Function
v_lockctl invokes the v_lockctl callable service to control advisory byte-range locks
on a file.
Note: All locks are advisory only. Client and local processes can use locks to
inform each other that they want to protect parts of a file, but locks do not
prevent I/O on the locked parts. A process that has appropriate permissions
on a file can perform whatever I/O it chooses, regardless of which locks are
set. Therefore, file locking is only a convention, and it works only when all
processes respect the convention.
Parameters
v_command
The name of a predefined command variable that is used to control the lock.
You can specify a numeric value (see Appendix A) or a predefined
VL_command variable that derives the appropriate numeric value. The
command variables are
Variable Description
VL_REGLOCKER Register the lock server (locker).
VL_UNREGLOCKER Unregister the locker.
VL_LOCK Set a lock in a specified byte range.
VL_LOCKWAIT Set a lock in a specified byte range or wait to set the
lock until the byte range is free.
VL_UNLOCK Unlock all locks in a specified byte range.
VL_QUERY Query for lock information about a file.
VL_PURGE Release all locks on all files, held by a locker or a
group of lockers.
stem
The name of a stem variable that is the structure used to obtain information
about the lock. To access the information, you can specify a numeric value
(see Appendix A) or the predefined variables beginning with VL_ or L_ that
derive the appropriate numeric value—for example, stem.vl_serverpid. The
variables beginning with VL_ are:
Variable Description
VL_SERVERPID Server's PID.
VL_CLIENTPID Server's client's process ID (PID).
VL_LOCKERTOK Token for locker.
VL_CLIENTTID Client's thread's TID. The TID is the individual lock
owner within a locker.
VL_OBJCLASS The class for an object (a single locked file)—for
example, HFS for an HFS file, MVS for an MVS data
set, LFSESA for a LAN file server.
VL_OBJID The unique ID for an object (locked file) within its
class. For an HFS file, the VL_OBJID contains the
device number and FID of the file.
VL_OBJTOK A token to identify the object (locked file) on a
subsequent lock request.
Variable Description
VL_DOSMODE DOS file-sharing field.
VL_DOSACCESS DOS file-sharing field.
For a description of the variables beginning with L_, see “f_getlk” on page 54.
Usage Notes
1. The v_lockctl service locks out other cooperating lockers from part of a file, so
that the locker can read or write to that part of the file without interference from
others.
2. Each locker must be registered before issuing any lock requests. On a
REGLOCKER command, the caller must provide stem variables with these
suffixes:
VL_SERVERPID
VL_CLIENTPID
The VL_LOCKERTOK variable is returned to the caller; it is a token to identify
the locker on subsequent lock requests.
3. On a QUERY, LOCK, LOCKWAIT, or UNLOCK command, the caller provides
stem variables with these suffixes:
VL_LOCKERTOK
VL_CLIENTTID
VL_OBJCLASS
VL_OBJID
VL_OBJTOK (This is optional, but it will improve performance for multiple
lock requests)
To describe the byte range for the command, the caller must also provide stem
variables with the following L_ suffixes:
QUERY L_TYPE, L_START, L_LEN, L_WHENCE
LOCK L_TYPE, L_START, L_LEN, L_WHENCE
LOCKWAIT L_TYPE, L_START, L_LEN, L_WHENCE
UNLOCK L_START, L_LEN, L_WHENCE
The L_ variables are described in “f_getlk” on page 54.
VL_OBJTOK is returned to the caller; it is a token to identify the object on a
subsequent lock request. On a QUERY, lock information describing a lock that
would prevent the proposed lock from being set is returned to the caller.
4. Stem variables with the suffixes L_TYPE, L_START, and L_LEN are needed
whether the request is for setting a lock, releasing a lock, or querying a
particular byte range for a lock. L_WHENCE is always treated as SEEK_SET,
the start of the file.
The L_TYPE variable is used to specify the type of lock to be set or queried.
(L_TYPE is not used to unlock.) You can use a numeric value (see Appendix A
) or one of the following predefined variables used to derive the appropriate
value:
Chapter 5. OpenMVS Virtual File System (VFS) Server Syscall Commands 205
v_lockctl
Type Description
F_RDLCK A read lock, also known as a shared lock. This type of lock
specifies that the locker can read the locked part of the file, and
other lockers cannot write on that part of the file in the meantime.
A locker can change a held write lock, or any part of it, to a read
lock, thereby making it available for other lockers to read. Multiple
lockers can have read locks on the same part of a file
simultaneously.
F_WRLCK A write lock, also known as an exclusive lock. This type of lock
indicates that the locker can write on the locked part of the file,
without interference from other lockers. If one locker puts a write
lock on part of a file, no other locker can establish a read lock or
write lock on that same part of the file. A locker cannot put a write
lock on part of a file if there is already a read lock on an
overlapping part of the file, unless that locker is the only owner of
that overlapping read lock. In such a case, the read lock on the
overlapping section is replaced by the write lock being requested.
F_UNLCK Returned on a query, when there are no locks that would prevent
the proposed lock operation from completing successfully.
The L_WHENCE variable specifies how the byte range offset is to be found
within the file; L_WHENCE is always treated as SEEK_SET, which stands for
the start of the file.
The L_START variable is used to identify the part of the file that is to be
locked, unlocked, or queried. The part of the file affected by the lock begins at
this offset from the start of the file. For example, if L_START has the value 1ð,
a lock request attempts to set a lock beginning 10 bytes past the start of the
file.
Note: Although you cannot request a byte range that begins or extends
beyond the beginning of the file, you can request a byte range that
begins or extends beyond the end of the file.
The L_LEN variable is used to give the size of the locked part of the file, in
bytes. The value specified for L_LEN cannot be negative. If a negative value is
specified for L_LEN, a RETVAL of −1 and an EINVAL ERRNO are returned. If
L_LEN is zero, the locked part of the file begins at L_START and extends to
the end of the file.
The L_PID variable identifies the VL_CLIENTPID of the locker that holds the
lock found on a query request, if one was found.
5. You can set locks by specifying a VL_LOCK as the command parameter. If the
lock cannot be obtained, a RETVAL of −1 is returned along with an appropriate
ERRNO and ERRNOJR.
You can also set locks by specifying a VL_LOCKWAIT as the command
parameter. If the lock cannot be obtained because another process has a lock
on all or part of the requested range, the LOCKWAIT request waits until the
specified range becomes free and the request can be completed.
If a signal interrupts a call to the v_lockctl service while it is waiting in a
LockWait operation, the function returns with a RETVAL of −1, and the ERRNO
EINTR.
Example
This example illustrates several calls to v_lockctl to register a locker, lock a range,
unlock a range, and unregister a locker:
Chapter 5. OpenMVS Virtual File System (VFS) Server Syscall Commands 207
v_lockctl
/\ rexx \/
address syscall
'v_reg 2 RxLocker' /\ register server as a lock server \/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ register locker \/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
lk.vl_serverpid=ð /\ use my pid as server pid \/
lk.vl_clientpid=1 /\ set client process id \/
'v_lockctl' vl_reglocker 'lk.' /\ register client as a locker \/
c1tok=lk.vl_lockertok /\ save client locker token \/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ lock a range \/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
lk.vl_lockertok=c1tok /\ set client locker token \/
lk.vl_clienttid='thread1' /\ invent a thread id \/
lk.vl_objclass=1 /\ invent an object class \/
lk.vl_objid='objectname' /\ invent an object name \/
lk.vl_objtok='' /\ no object token \/
lk.l_len=4ð /\ set length of range to lock \/
lk.l_start=8ð /\ set start of range to lock \/
lk.l_whence=seek_set /\ start of range is absolute \/
lk.l_type=f_wrlck /\ set write lock \/
'v_lockctl' vl_lock 'lk.' /\ try to do the lock \/
obj1=lk.vl_objtok /\ keep returned object token \/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ unlock a range \/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
lk.vl_lockertok=c1tok /\ set client locker token \/
lk.vl_clienttid='thread1' /\ invent a thread id \/
lk.vl_objclass=1 /\ invent an object class \/
lk.vl_objid='objectname' /\ invent an object name \/
lk.vl_objtok=obj1 /\ set object token \/
lk.l_len=4ð /\ set length of range to lock \/
lk.l_start=8ð /\ set start of range to lock \/
lk.l_whence=seek_set /\ start of range is absolute \/
lk.l_type=f_unlck /\ set unlock \/
'v_lockctl' vl_unlock 'lk.' /\ unlock the range \/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ unregister locker \/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
lk.vl_lockertok=c1tok /\ set client locker token \/
'v_lockctl' vl_unreglocker 'lk.' /\ unregister client as a locker \/
return
v_lookup
55──v_lookup──vntoken──filename──stem──vntoken2────────────────────5%
Function
v_lookup invokes the v_lookup callable service to search a directory for a file.
v_lookup accepts a vnode token representing a directory and a name identifying a
file. If the file is found in the directory, a vnode token for the file and the attributes
of the file are returned.
Parameters
vntoken
A variable name that contains the vnode token for the directory in which
filename is looked up.
filename
The name of the file.
stem
The same file attribute information is returned in stem as if a v_getattr had
been used on the file looked up. Upon return, stem.0 contains the number of
attribute variables returned. To access the attribute values, you can use a
numeric value or the predefined variables beginning with ST_ used to derive
the numeric value. See “stat” on page 155 for a list of the predefined variables,
or Appendix A for the numeric values.
vntoken2
The variable name for the buffer that, when returned, will contain the vnode
token for the looked-up file.
Usage Notes
The caller is responsible for freeing vnode tokens returned by the v_lookup service
by calling to the v_rel service when they are no longer needed.
Example
In the following example, assume that dirtok and file were assigned values earlier in
the exec:
"v_lookup dirtok (file) st. outtok"
Chapter 5. OpenMVS Virtual File System (VFS) Server Syscall Commands 209
v_mkdir
v_mkdir
55──v_mkdir──vntoken──directoryname──mode──stem──vntoken2──────────5%
Function
v_mkdir invokes the v_mkdir callable service to create a new empty directory in
the directory represented by vntoken, with the permission specified in mode.
Parameters
vntoken
A variable name that contains the vnode token for the directory in which
filename is to be created.
directoryname
The name of the directory.
mode
A three-digit number, corresponding to the access permission bits for the
directory. Each digit must be in the range ð–7, and all three digits must be
specified. For more information on permissions, see Appendix B.
stem
The same file attribute information is returned in stem as if a v_getattr had
been used on the file specified. Upon return, stem.0 contains the number of
attribute variables returned. To access the attribute information, you can use a
numeric value or the predefined variables beginning with ST_ used to derive
the numeric value. See “stat” on page 155 for a list of the predefined variables,
or Appendix A for the numeric values.
vntoken2
The variable name for the buffer that will contain the vnode token for the newly
created directory.
Usage Notes
1. If the directory named in directoryname already exists, the v_mkdir service
returns a failing return code, and no vntoken2 is returned.
2. The caller is responsible for freeing vnode tokens returned by the v_mkdir
service by calling to the v_rel service when they are no longer needed.
Example
In the following example, assume that dirtok, file, and perm were assigned values
earlier in the exec:
"v_mkdir dirtok (file)" perm "st. newtok"
v_read
55──v_read──vntoken──variable──length──position──stem───────────────5
5──┬──────────────┬────────────────────────────────────────────────5%
└─access_check─┘
Function
v_read invokes the v_rdwr callable service to accept a vnode token representing a
file and to read data from the file. The file attributes are returned when the read
completes. The number of bytes read is returned in RETVAL.
Parameters
vntoken
A variable name that contains the vnode token for the file to be read.
variable
The name of the buffer into which data will be read.
length
The maximum number of characters to read. After the read completes, the
length of variable is the number of bytes read. This value is also returned in
RETVAL.
position
The file offset where the read is to begin, specified in bytes.
stem
The name of a stem variable used to return the file attribute information. Upon
return, stem.0 contains the number of attribute variables returned. The same
information is returned in stem as if a v_getattr had been used on the file. To
obtain the attribute information, you can use a numeric value or the predefined
variables beginning with ST_ used to derive the numeric value. See “stat” on
page 155 for a list of the variables, or Appendix A for the numeric values.
access_check
Specify a ð for no access check, or 1 to indicate the system is to check the
user for read access to the file. The user is defined by the effective UID and
GID. Setting the effective GID does not affect supplemental groups. Also, there
is no support for altering the MVS user identity of the task using the ACEE
(Accessor Environment Element).
Example
In the following example, assume that filetok, bytes, and pos were assigned values
earlier in the exec:
"v_read filetok buffer" bytes pos stem. ð
Chapter 5. OpenMVS Virtual File System (VFS) Server Syscall Commands 211
v_readdir
v_readdir
55──v_readdir──vntoken──stem──start──┬──────────────┬──────────────5%
└─access_check─┘
Function
v_readdir invokes the v_readdir callable service to accept a vnode token
representing a directory and return directory entries from this directory.
Parameters
vntoken
A variable name that contains the vnode token for the directory to be read.
stem
The name of a stem variable used to return the directory entries. Upon return,
stem.0 contains the number of directory entries returned. stem.1 through
stem.n (where n is the number of entries returned) each contain a directory
entry.
Note: Only small directories can be read in a single call. To ensure that you
read to the end of the directory, make calls to v_readdir until no entries
are returned.
start
The number of the first directory entry to be returned. The numbers ð and 1
both indicate that the read should start at the beginning of the directory.
access_check
Specify a ð for no access_check, or 1 to specify that the system is to check the
user for read access to the file. The user is defined by the effective UID and
GID. Setting the effective GID does not affect supplemental groups. Also, there
is no support for altering the MVS user identity of the task using the ACEE.
Example
In the following example, assume that dirtok was assigned a value earlier in the
exec:
"v_readdir dirtok dir. ð"
v_readlink
55──v_readlink──vntoken──variable──────────────────────────────────5%
Function
v_readlink invokes the v_readlink callable service to read the symbolic link file
represented by the vnode token and return its contents in variable.
Parameters
vntoken
A variable name that contains the vnode token for the symbolic link to be read.
The attribute stem returned on call to another function (for example, v_getattr)
identifies whether the symbolic link is a link to an external name in the stem
index ST_EXTLINK. An external name is the name of an object outside the
HFS.
variable
The name of the buffer that, on return, contains the contents of the symbolic
link.
Example
In the following example, assume that symtok was assigned a value earlier in the
exec:
"v_readlink symtok link"
Chapter 5. OpenMVS Virtual File System (VFS) Server Syscall Commands 213
v_reg
v_reg
55──v_reg──type──name──────────────────────────────────────────────5%
Function
v_reg invokes the v_reg callable service to register a process as a server. A
process must be registered using this service before it can use any other vnode
interface services.
Parameters
type
A numeric value that defines the type of server. You can specify:
name
The name of the server, a character string up to 32 bytes in length. There are
no restrictions on the name; for example, it does not have to be unique in the
system.
Usage Notes
1. Only a superuser can register a process as a server.
2. The D OMVS command uses the values supplied in type and name fields to
display information about the currently active servers.
Example
To register a server:
'v_reg 1 "My REXX server"'
v_rel
55──v_rel──vntoken─────────────────────────────────────────────────5%
Function
v_rel invokes the v_rel callable service to accept a vnode token representing a file
descriptor for a file or directory, and to release that token.
Parameters
vntoken
A variable name that contains the vnode token for the file descriptor to be
released.
Usage Notes
1. The vnode token is no longer valid and cannot be used for subsequent
requests after v_rel has successfully processed it.
2. This service must be used to release all vnode tokens obtained from other
operations.
Example
In the following example, assume that vntok was assigned a value earlier in the
exec:
"v_rel vntok"
Chapter 5. OpenMVS Virtual File System (VFS) Server Syscall Commands 215
v_remove
v_remove
55──v_remove──vntoken──filename────────────────────────────────────5%
Function
v_remove invokes the v_remove callable service to remove a directory entry.
Parameters
vntoken
A variable name that contains the vnode token for the directory from which
filename is to be removed.
filename
The name for the directory entry. The directory entry could be identified by a
name for a file, the name of a hard link to a file, or the name of a symbolic link.
Usage Notes
1. If the name specified refers to a symbolic link, the symbolic link file named by
filename is deleted.
2. If the v_remove service is successful and the link count becomes zero, the file
is deleted. The contents of the file are discarded, and the space it occupied is
freed for reuse. However, if another process (or more than one) has the file
open or has a valid vnode token when the last link is removed, the file contents
are not removed until the last process closes the file or releases the vnode
token.
3. When the v_remove service is successful in removing a directory entry and
decrementing the link count, whether or not the link count becomes zero, it
returns control to the caller with RETVAL ð. It updates the change and
modification times for the parent directory, and the change time for the file itself
(unless the file is deleted).
4. You cannot remove a directory using v_remove. To remove a directory, refer
to “v_rmdir” on page 219.
Example
In the following example, assume that dirtok and file were assigned values earlier in
the exec:
"v_remove dirtok (file)"
v_rename
55──v_rename──vntoken──oldname──vntoken2──newname──────────────────5%
Function
v_rename invokes the v_rename callable service to rename a file or directory to a
new name.
Parameters
vntoken
A variable name that contains the vnode token for the directory that contains
the filename oldname.
oldname
The existing name for the file or directory.
vntoken2
A variable name that contains the vnode token for the directory that is to
contain the filename newname.
newname
The new name for the file or directory.
Usage Notes
1. The v_rename service changes the name of a file or directory from oldname to
newname. When renaming completes successfully, the change and
modification times for the parent directories of oldname and newname are
updated.
2. The calling process needs write permission for the directory containing oldname
and the directory containing newname. If oldname and newname are the
names of directories, the caller does not need write permission for the
directories themselves.
3. Renaming files: If oldname and newname are links referring to the same file,
v_rename returns successfully and does not perform any other action.
If oldname is the name of a file, newname must also name a file, not a
directory. If newname is an existing file, it is unlinked. Then the file specified as
oldname is given newname. The pathname newname always stays in
existence; at the beginning of the operation, newname refers to its original file,
and at the end, it refers to the file that used to be oldname.
4. Renaming directories: If oldname is the name of a directory, newname must
also name a directory, not a file. If newname is an existing directory, it must be
empty, containing no files or subdirectories. If it is empty, it is removed.
newname cannot be a directory under oldname; that is, the old directory cannot
be part of the pathname prefix of the new one.
Chapter 5. OpenMVS Virtual File System (VFS) Server Syscall Commands 217
v_rename
Example
In the following example, assume that olddir, oldfile, newdir, and newfile were
assigned values earlier in the exec:
"v_rename olddir (oldfile) newdir (newfile)"
v_rmdir
55──v_rmdir──vntoken──dirname──────────────────────────────────────5%
Function
v_rmdir invokes the v_rmdir callable service to remove an empty directory.
Parameters
vntoken
A variable name that contains the vnode token for the directory from which
dirname is to be removed.
dirname
The name of the empty directory to be removed.
Usage Notes
1. The directory specified by dirname must be empty.
2. If the directory is successfully removed, the change and modification times for
the parent directory are updated.
3. If any process has the directory open when it is removed, the directory itself is
not removed until the last process closes the directory. New files cannot be
created under a directory that is removed, even if the directory is still open.
Example
In the following example, assume that dirtok and dirname were assigned values
earlier in the exec:
"v_rmdir dirtok (dirname)"
Chapter 5. OpenMVS Virtual File System (VFS) Server Syscall Commands 219
v_rpn
v_rpn
55──v_rpn──pathname──vfstoken──vntoken──stem──stem2────────────────5%
Function
v_rpn invokes the v_rpn callable service to accept a pathname of a file or directory
and return a vnode token that represents this file or directory and the VFS token
that represents the mounted file system that contains the file or directory.
Parameters
pathname
The absolute pathname to be resolved, specified as a string.
vfstoken
The name of a variable in which the VFS token for the resolved file is stored.
vntoken
The name of a variable in which the vnode token for the resolved file is stored.
stem
The name of a stem variable used to return the mount entry for the file system.
To access mount table information, you can use a numeric value or the
predefined variables beginning with MNTE_ used to derive the numeric value.
See “getmntent” on page 83 for a description of the MNTE_ variables; see
Appendix A for the numeric values.
stem2
Upon return, stem2.0 contains the number of attribute variables returned. The
same information is returned in stem2 as if a v_getattr had been used on the
file that was just resolved. You can use the predefined variables beginning with
ST_ to access those respective values. For example, stem2.st_size accesses
the file size. See “stat” on page 155 for a description of the ST_ variables.
Usage Notes
1. The mount point pathname is not available in the MNTE_ structure returned by
the variable stem2.mnte_path.
2. The caller is responsible for freeing vnode tokens returned by the v_rpn
service, by calling to the v_rel service when they are no longer needed.
Example
In the following example, assume that path was assigned a value earlier in the
exec:
"v_rpn (path) vfstok filetok mnt. attr."
v_setattr
55──v_setattr──vntoken──attribute_list─────────────────────────────5%
Function
v_setattr invokes the v_setattr callable service to set the attributes associated with
the file represented by the vnode token. You can change the mode, owner, access
time, modification time, change time, reference time, audit flags, general attribute
flags, and file size.
Parameters
vntoken
A variable name that contains the vnode token for the file for which the
attributes are to be set.
attribute_list
A list of attributes to be set and their values. The attributes are expressed
either as numeric values or as the predefined variables beginning with ST_,
followed by arguments for that attribute. For the predefined variables beginning
with ST_, see “chattr” on page 26; for the numeric values, see Appendix A.
Usage Notes
For usage notes, see “chattr” on page 26.
Example
In the following example, assume that vntok was assigned a value earlier in the
exec. This example truncates a file to ð length and sets the mode to 600:
"v_setattr vntok" st_size ð st_mode 6ðð
Chapter 5. OpenMVS Virtual File System (VFS) Server Syscall Commands 221
v_symlink
v_symlink
55──v_symlink──vntoken──filename──pathname──┬─────────┬────────────5%
└─extlink─┘
Function
v_symlink invokes the v_symlink callable service to create a symbolic link to a
pathname or external name. The contents of the symbolic link file is pathname.
Parameters
vntoken
A variable name for the directory that contains the vnode token in which
filename is being created.
filename
The name for the symbolic link.
pathname
The absolute or relative pathname of the file you are linking to (the contents of
the symbolic link).
extlink
Specify 1 if this is a symbolic link to an external name rather than to a
pathname in the file hierarchy. An external name is the name of an object
outside of the file hierarchy.
Usage Notes
1. Like a hard link (described in “v_link” on page 203), a symbolic link allows a file
to have more than one name. The presence of a hard link guarantees the
existence of a file, even after the original name has been removed. A symbolic
link, however, provides no such assurance; in fact, the file identified by
pathname need not exist when the symbolic link is created. In addition, a
symbolic link can cross file system boundaries, and it can refer to objects
outside of a hierarchical file system.
2. When a component of a pathname refers to a symbolic link (but not an external
symbolic link) rather than to a directory, the pathname contained in the
symbolic link is resolved. For v_rpn or other OS/390 OpenEdition callable
services, a symbolic link in a pathname parameter is resolved as follows:
If the pathname in the symbolic link begins with / (slash), the symbolic link
pathname is resolved relative to the process root directory.
If the pathname in the symbolic link does not begin with /, the symbolic link
pathname is resolved relative to the directory that contains the symbolic
link.
If the symbolic link is not the last component of the original pathname,
remaining components of the original pathname are resolved from there.
When a symbolic link is the last component of a pathname, it may or may
not be resolved. Resolution depends on the function using the pathname.
For example, a rename request does not have a symbolic link resolved
when it appears as the final component of either the new or old pathname.
However, an open request does have a symbolic link resolved when it
appears as the last component.
Example
In the following example, assume that dirtok, file, and linkname were assigned
values earlier in the exec:
"v_symlink dirtok (file) (linkname)"
Chapter 5. OpenMVS Virtual File System (VFS) Server Syscall Commands 223
v_write
v_write
55──v_write──vntoken──variable──length──position──stem──────────────5
5──┬──────────────┬────────────────────────────────────────────────5%
└─access_check─┘
Function
v_rdwr invokes the v_rdwr callable service to accept a vnode token representing a
file and to write data to the file. The number of bytes written and the file attributes
are returned in RETVAL when the write completes.
Parameters
vntoken
A variable name that contains the vnode token for the file to be written.
variable
The name of the buffer from which data is to be written.
length
The number of characters to write.
position
The file offset where the write is to start from, specified in bytes.
stem
The name of a stem variable used to return the file attributes. Upon return,
stem.0 contains the number of attribute variables returned. The same
information is returned in stem as if a v_getattr was used on the file. To access
the file attributes, you can use a numeric value or the predefined variables
beginning with ST_ used to derive the numeric value. See “stat” on page 155
for more information about the ST_ predefined variables; see Appendix A for
the numeric values.
access_check
Specify ð for no access check, or 1 for the system to check the user for read
access to the file. The user is defined by the effective UID and GID. Setting the
effective GID does not affect supplemental groups. Also, there is no support for
altering the MVS user identity of the task using the ACEE.
Example
In the following example, assume that filetok, buf, and pos were assigned values
earlier in the exec:
"v_write filetok buf" length(buf) pos
Except for the error numbers and signal numbers, all variables contain an
underscore. This is also true of most of the POSIX names in the C include files.
Data Numeric
Variable Type Value
AUD_FEXEC Dec 512
AUD_FREAD Dec 33554432
AUD_FWRITE Dec 131072
AUD_SEXEC Dec 256
AUD_SREAD Dec 16777216
AUD_SWRITE Dec 65536
E2BIG Hex 91
EACCES Hex 6F
EAGAIN Hex 70
EBADF Hex 71
EBUSY Hex 72
ECHILD Hex 73
EDEADLK Hex 74
EDOM Hex 01
EEXIST Hex 75
EFAULT Hex 76
EFBIG Hex 77
EILSEQ Hex 93
EINTR Hex 78
EINVAL Hex 79
EIO Hex 7A
EISDIR Hex 7B
ELOOP Hex 92
EMFILE Hex 7C
EMLINK Hex 7D
EMVSBADCHAR Hex A0
EMVSCATLG Hex 99
EMVSCVAF Hex 98
F_OK Dec 8
F_RDLCK Dec 1
F_UNLCK Dec 3
F_WRLCK Dec 2
GR_GID Dec 2
GR_MEM Char 4
GR_MEMBERS Dec 3
GR_NAME Char 1
L_LEN Dec 4
L_PID Dec 5
L_START Dec 3
L_TYPE Dec 1
L_WHENCE Dec 2
MNTE_DD Char 4
MNTE_DEV Dec 3
MNTE_FSNAME Char 6
MNTE_FSTYPE Char 5
MNTE_MODE Dec 2
MNTE_PARDEV Dec 9
MNTE_PARM Char 13
MNTE_PATH Char 7
MNTE_QJOBNAME Char 11
MNTE_QPID Dec 12
MNTE_ROOTINO Dec 10
MNTE_STATUS Dec 8
MNTE_TYPE Dec 1
MTM_DRAIN Dec 2
MTM_FORCE Dec 4
MTM_IMMED Dec 8
MTM_NORMAL Dec 16
MTM_NOSUID Dec 262144
MTM_RDONLY Dec 128
MTM_RDWR Dec 64
MTM_REMOUNT Dec 65536
MTM_RESET Dec 1
MTM_SYNCHONLY Dec 512
O_APPEND Dec 8
O_CREAT Dec 128
O_EXCL Dec 64
O_NOCTTY Dec 32
O_NONBLOCK Dec 4
O_RDONLY Dec 2
O_RDWR Dec 3
O_SYNC Dec 256
O_TRUNC Dec 16
O_WRONLY Dec 1
PC_LINK_MAX Dec 2
PC_MAX_CANON Dec 3
PC_MAX_INPUT Dec 4
PC_NAME_MAX Dec 5
PC_PATH_MAX Dec 7
PC_PIPE_BUF Dec 8
PC_POSIX_CHOWN_RESTRICTED Dec 1
PC_POSIX_NO_TRUNC Dec 6
R_OK Dec 4
RLIMIT_AS Dec 5
RLIMIT_CORE Dec 4
RLIMIT_CPU Dec 0
RLIMIT_FSIZE Dec 1
RLIM_INFINITY Dec 2147483647
RLIMIT_NOFILE Dec 6
S_FFBINARY Dec 1
S_FFCR Dec 3
TM_HOUR Dec 1
TM_ISDST Dec 9
TM_MDAY Dec 5
TM_MIN Dec 2
U_MACHINE Char 5
U_NODENAME Char 2
U_RELEASE Char 3
U_SYSNAME Char 1
U_VERSION Char 4
VL_CLIENTPID Dec 7
VL_CLIENTTID Char 9
VL_DOSMODE Char 13
VL_DOSACCESS Char 14
VL_LOCK Dec 3
VL_LOCKERTOK Tok 8
VL_LOCKWAIT Dec 4
VL_OBJCLASS Char 10
VL_OBJID Char 11
VL_OBJTOK Tok 12
VL_PURGE Dec 7
VL_QUERY Dec 6
VL_REGLOCKER Dec 1
VL_SERVERPID Dec 6
VL_UNREGLOCKER Dec 2
VL_UNLOCK Dec 5
W_CONTINUED Dec 3
W_EXITSTATUS Dec 4
W_IFEXITED Dec 3
W_IFSIGNALED Dec 5
W_IFSTOPPED Dec 7
W_NOHANG Dec 1
W_OK Dec 2
W_STAT3 Dec 1
W_STAT4 Dec 2
W_STOPSIG Dec 8
W_TERMSIG Dec 6
W_UNTRACED Dec 2
X_OK Dec 1
Position 1
Specifying the bit in position 1 is optional. You can specify one of these values:
0 Off
1 Sticky bit on
2 Set-group-ID-on execution
3 Set-group-ID-on execution and set the sticky bit on
4 Set-user-ID on execution
5 Set-user-ID on execution and set the sticky bit on.
6 Set-user-ID and set-group-ID on execution
7 Set-user-ID and set-group-ID on execution and set the sticky bit on
Positions 2, 3, and 4
Specifying these bits is required. For each type of access—owner, group, and
other—there is a corresponding octal number:
0 No access (---)
1 Execute-only access (--x)
2 Write-only access (-w-)
3 Write and execute access (-wx)
4 Read-only access (r--)
5 Read and execute access (r-x)
6 Read and write access (rw-)
7 Read, write, and execute access (rwx)
To specify permissions for a file or directory, you use at least a 3-digit octal
number, omitting the digit in the first position. When you specify just three digits,
the first digit describes owner permissions, the second digit describes group
permissions, and the third digit describes permissions for all others. When the first
digit is not set, some typical 3-digit permissions are specified in octal as shown in
Table 2 on page 236.
For example, if you have obtained a file's permission bits and want to use chmod
to turn on the write bits, you could code:
'chmod (file)' BITOR(st.st_mode, 222)
To turn the same bits off, you could code:
'chmod (file)' BITAND(st.st_mode, 555)
A C
absolute value. The numeric value of a real number character special file. (1) A special file that provides
regardless of its algebraic sign (positive or negative). access to an input or output device. The character
[OSF] interface is used for devices that do not use block I/O.
(2) A file that refers to a device. One specific type of
access control. In computer security, ensuring that character special file is a terminal device file. Other
the resources of a computer system can be accessed character special files have no structure defined by
only by authorized users in authorized ways. POSIX.1, and their use is unspecified by POSIX.1.
[POSIX.1] The only character special file supported by
access mode. A form of access permitted to a file. the OpenEdition implementation is the pseudo-TTY.
[POSIX.1]
character type. A data type that consists of
access permission. A group of designations that alphanumeric characters. See also data type.
determine who can access a particular file and how the
user can access the file. child process. A process created as a result of a fork.
The child process receives a copy of the parent's
address space. (1) The memory locations that can be storage and inherits open files. Execution in the child
referred to by a process. [POSIX.1] (2) The code, continues at the instruction following the fork. Contrast
stack, and data that are accessible by a process. with parent process. See also fork, process.
(3) The complete range of addresses that is available
to a programmer. (4) The area of virtual storage controlling process. The session leader that
available for a program. (5) See forked address space, established the connection to the controlling terminal. If
kernel address space, user address space. the terminal subsequently ceases to be a controlling
terminal for this session, the session leader ceases to
appropriate privileges. An implementation-defined be the controlling process. [POSIX.1]
means of associating privileges with a process with
regard to the function calls and function call options controlling terminal. (1) An active terminal at which a
defined in POSIX.1 that need special privileges. user is authorized to enter commands that affect system
[POSIX.1] In the OpenEdition implementation, operation. The controlling terminal for any process
appropriate privilege is defined as superuser authority. normally is the active terminal from which the process
A trusted or privileged attribute is an attribute group for that process was started. A terminal can
associated with a started procedure address space and have no more than one controlling process group and a
to any process associated with the address space. process group can have no more than one controlling
terminal. The controlling process group receives certain
argument. (1) An independent variable. [I][A] interrupt signals from the controlling terminal. [OSF]
(2) Any value of an independent variable, for example, (2) A terminal that is associated with a session. Each
detach. To stop a thread. end of file (EOF). A code that signals that the last
record of a file has been read.
directory. (1) A type of file containing the names and
controlling information for other files or other directories. environment. (1) The settings for shell variables and
(2) A construct for organizing computer files. As files paths set when the user logs in. These variables can
are analogous to folders that hold information, a be modified later by the user. [OSF] (2) A block of
directory is analogous to a drawer that can hold a information passed (“exported”) to a command when the
number of folders. Directories can also contain command is invoked. This block contains a number of
subdirectories, which can contain subdirectories of their environment variables. The environment provides
own. (3) A file that contains directory entries. No two information that the program may use in its operation, in
directory entries in the same directory can have the a form that relieves you of the need to specify it with
same name. [POSIX.1] (4) A file that points to files every command. (3) The set of all factors that may
and to other directories. (5) An index used by a control affect how a program behaves. (4) A named collection
program to locate blocks of data that are stored in of logical and physical resources used to support the
separate areas of a data set in direct access storage. operation of a function. (5) See also environment
variable (ENV).
directory entry. An object that associates a filename
with a file. Several directory entries can associate environment variable (ENV). (1) A name associated
names with the same file. Synonymous with link. with a string of characters, made available to the
[POSIX.1] programs that you run. Some environment variables
used by the OpenEdition shell are PATH, TMPDIR,
dub. To make an MVS address space known to COLUMNS, and LINES. For example, the TMPDIR
OS/390 OpenEdition. Once dubbed, an address space environment variable holds the name of a directory
is considered to be an OpenEdition “process.” Address where shell commands are free to create temporary
spaces created by fork() are automatically dubbed working files. (2) A variable that describes the
when they are created; other address spaces become operating environment of the process and typically
dubbed if they invoke an OpenEdition service. Dubbing includes information about the home directory,
also applies to MVS tasks. A dubbed task is considered command search path, the terminal in use, and the
an OpenEdition “thread.” Tasks created by current time zone (the HOME, PATH, TERM, and TZ
pthread_create() are automatically dubbed threads; variables, respectively). (3) An environment variable
other tasks are dubbed if they invoke an OpenEdition the value of which is the name of a file that contains
service. Contrast with undub. shell commands to customize a shell environment.
When a user first runs the shell, the shell executes his
or her profile. Then the shell runs the commands in the
ENV file. (4) A variable included in the current software
Glossary 243
environment that is available to any called program that first-in-first-out basis. [POSIX.1] (2) A named
requests it. permanent pipe that allows two unrelated processes to
exchange information through a pipe connection.
Epoch. The time 0 hours, 0 minutes, 0 seconds, Synonymous with named pipe.
January 1, 1970, Coordinated Universal Time. See also
seconds since the Epoch. [POSIX.1] file. (1) A set of related records treated as a unit.
(2) A sequence of records. If the file is located in
exec. To overlay the current process with another internal storage, it is an internal file; if it is on an
executable program. See also fork. input/output device, it is an external file. [OSF] (3) A
collection of related data that is stored and retrieved by
executable. See executable file, executable module, an assigned name. [OSF] (4) Linear data that can be
executable program, executable statement. opened, written, read, and closed. A file can also
contain information about the file, such as authorization
executable file. (1) A file suitable for execution. An information. The name used to obtain a file includes the
executable file may be a program that has been directories in the path to the file. (5) Strings of
compiled and link-edited, or it may be a shell script. characters with no additional structure. Structure is
(2) A file that contains programs or commands that assumed only by the processing programs. Files can be
perform operations on actions to be taken. (3) A located relative to the current directory or by an
regular file acceptable as a new process image file by absolute pathname. (6) An object that can be written
the equivalent of the POSIX.1 exec family of functions, to, or read from, or both. A file has certain attributes,
and thus usable as one form of a utility. The standard including access permissions and type. File types
utilities described in POSIX.1 as compilers can produce include regular file, character special file, block special
executable files, but other unspecified methods of file, FIFO special file, and directory. Other types of files
producing executable files may also be provided. The may be defined by the implementation. [POSIX.1] In
internal format of an executable file is unspecified, but a the OpenEdition implementation, the file system does
conforming application shall not assume an executable not support block special files, but it does support
file is a text file. [POSIX.2] (4) See also executable symbolic link files. (7) A collection of information or
program. data that is organized by some method (relative,
indexed, or serial, for example) and stored on a device
executable module. A module in a partitioned data
such as a disk. (8) Synonym for data set. (9) In word
set (PDS) that can be executed. An executable module
processing, synonym for document.
that is copied into an HFS file and then given read and
execute permissions becomes an executable file. On file creation mask. See mask.
the other hand, an executable file is not necessarily an
executable module. file descriptor. (1) A small unsigned integer that a
UNIX system uses to identify a file. A file descriptor is
executable program. (1) A program in a form suitable created by a process through issuing an open system
for execution by a computer. The program can be an call for the filename. A file descriptor ceases to exist
application or a shell script. An executable program is when it is no longer held by any process. [OSF] (2) A
equivalent to an MVS load module. (2) A program that per-process unique, nonnegative integer used to identify
has been link-edited and can therefore be run in a an open file for the purpose of file access. [POSIX.1]
processor. (3) A program that can be executed as a (3) An small positive number used to identify an open
self-contained procedure. It consists of a main program file in I/O operations. By convention, certain file
and, optionally, one or more subprograms. (4) See descriptors are used for the same purpose by all
also executable file, load module. programs. (4) See also standard error (stderr),
standard input (stdin), standard output (stdout).
executable statement. A statement that causes an
action to be taken by the program; for example, to file lock. A means to limit or deny access to a file by
calculate, to test conditions, or to alter normal other users. A file lock can be a read lock or a write
sequential execution. [OSF] lock.
file type. One of the five possible types of files: forked address space. An address space created by
ordinary file, directory, block device, character device, a fork function.
and first-in-first-out (FIFO or named pipe). See also file.
format. (1) A defined arrangement of such things as
first-in-first-out (FIFO). A queuing technique in which characters, fields, and lines, usually used for displays,
the next item to be retrieved is the item that has been in printouts, or files. [OSF] (2) The pattern that
the queue for the longest time. [A] Contrast with determines how data is recorded. [OSF] (3) To
last-in-first out (LIFO). arrange such things as characters, fields, and lines.
(4) In programming languages, a language construct
flag. (1) A modifier that appears on a command line that specifies the representation, in character form, of
with the command name that defines the action of the data objects in a file. [I]
command. [OSF] (2) An indicator or parameter that
shows the setting of a switch. [OSF] (3) A variable fully qualified name. A qualified name that includes
indicating that a certain condition holds. [T] (4) A all names in the hierarchical sequence above the
character that signals the occurrence of some condition, structure member to which the name refers, as well as
such as the end of a word. [A] (5) An internal the name of the member itself. [OSF]
Glossary 245
G J
group. (1) A collection of users who can share access job control. (1) Facilities for monitoring and accessing
authorities for protected resources. [OSF] (2) A list of background processes. [OSF] (2) A facility that
names that are known together by a single name. allows users to selectively stop (suspend) the execution
(3) A set of related records that have the same value of processes and continue (resume) their execution at a
for a particular field in all records. (4) A series of later point. The user typically employs this facility via
records logically joined together. the interactive interface jointly supplied by the terminal
I/O driver and a command interpreter. Conforming
group ID (GID). (1) A unique number assigned to a implementations may optionally support job control
group of related users. The GID can often be facilities; the presence of this option is indicated to the
substituted in commands that take a group name as an application at compile time or run time by the definition
argument. (2) A nonnegative integer, which can be of the [_POSIX_JOB_CONTROL] symbol. [POSIX.1]
contained in an object of type gid_t, that is used to
identify a group of system users. Each system user is a
member of at least one group. When the identity of a K
group is associated with a process, a group ID value is
referred to as a real group ID, an effective group ID, kernel. (1) The part of the OS/390 OpenEdition
one of the (optional) supplementary group IDs, or an component containing programs for such tasks as I/O,
(optional) saved set-group-ID. [POSIX.1] management, and communication. (2) The part of the
(3) Synonymous with group number. system that is an interface with the hardware and
provides services for other system layers such as
group name. A name that uniquely identifies a group system calls, file system support, and device drivers.
of users to the system. (3) The part of an operating system that performs basic
functions such as allocating hardware resources. (4) A
program that can run under different operating system
H environments. See also shell. (5) A part of a program
that must be in central storage in order to load other
hard link. (1) A mechanism that allows the ln parts of the program. (6) Synonym for kernel address
command to assign more than one name to a file. Both space.
the new name and the file being linked must be in the
same file system. [OSF] (2) The relationship between kernel address space. The address space containing
two directory entries that represent the same file; the the MVS support for OpenEdition services. This
result of an execution of the ln utility or the POSIX.1 address space can also be called the kernel. See also
link() function. [POSIX.2] kernel.
home directory. (1) The current directory associated kernel mode. In a multiprocessor environment, the
with the user at the time of login. [POSIX.2] (2) A master in a master-slave relationship. The master
directory associated with an individual user. (3) The processor operates in kernel mode, and the slave
user's current directory on login or after issuing the cd processor operates only in user mode. Kernel mode
command with no argument. handles the interrupts and callable services. User mode
informs the master when issuing a callable service.
Contrast with user mode.
I
kill. An operating system command that stops a
inherit. To copy resources or attributes from a parent process. [OSF]
to a child.
Glossary 247
occurrences from the root segment to an individual function. Once it is created, the file descriptors can be
segment. used to manipulate it, and it behaves identically to a
FIFO special file when accessed in this way. It has no
PATH. An environment variable that lists which name in the file hierarchy. [POSIX.1] (4) To direct
directories on the disk need to be searched for a data so that the output from one process becomes the
command. OpenEdition Shell and Utilities binaries input to another process. (5) An I/O stream that has a
should be placed in a directory on this search list. See descriptor and can be used in unidirectional
also current directory, directory. communications between related processes. [OSF]
(6) See also pipeline.
pathname. (1) A filename specifying all directories
leading to the file. (2) See also relative pathname. pipeline. (1) A chain of two or more processes
(3) A filename specifying all directories leading to a file connected by pipes. Each process in the chain acts as
plus the filename itself. (4) A string that is used to a filter, reading data from the standard input, performing
identify a file. A pathname consists of, at most, some transformation, and writing the results to the
[PATH_MAX] bytes, including the terminating null standard output. (2) A direct, one-way connection
character. It has an optional beginning slash, followed between two or more processes. (3) A serial
by zero or more filenames separated by slashes. If the arrangement of processors or a serial arrangement of
pathname refers to a directory, it may also have one or registers within a processor. Each processor or register
more trailing slashes. Multiple successive slashes are performs part of a task and passes results to the next
considered to be the same as one slash. A pathname processor. Several parts of different tasks can be
that begins with two successive slashes may be performed at the same time. (4) To perform processes
interpreted in an implementation-defined manner, in a series. (5) For increased processing speed, to
although more than two leading slashes shall be treated start execution of an instruction sequence before the
as a single slash. [POSIX.1] In the OpenEdition previous instruction sequence is completed.
implementation, the C/370 functions fopen(), freopen(),
remove(), and rename() interpret names with exactly Portable Operating System Interface. See POSIX.
two leading slashes, no leading blanks or other
characters, and the third character not a slash to mean POSIX. Portable Operating System Interface for
that the rest of the name refers to a traditional MVS Computer Environments, an interface standard
data set. (5) See also relative pathname. governed by the IEEE and based on UNIX. POSIX is
not a product. Rather, it is an evolving family of
pathname component. Synonym for filename. standards describing a wide spectrum of operating
system components ranging from C language and shell
path prefix. A pathname, with an optional ending interfaces to system administration.
slash, that refers to a directory. [POSIX.1]
privilege. See appropriate privileges.
pending. Waiting, as in an operation that is pending.
[OSF] privileged user. A user logged into an account with
root user authority.
permission. A code that determine how the file can be
used by any users who work on the system. [OSF] process. (1) A function being performed or waiting to
be performed. (2) An executing function, or one waiting
PID. Process ID to execute. (3) A function, created by a fork() request,
with three logical sections:
pipe. (1) An interprocess communication mechanism
that connects an output file descriptor to an input file Text, which is the function's instructions.
descriptor. Usually the standard output of one process Data, which the instructions use but do not change.
is connected to the standard input of another, forming a Stack, which is a push-down, pop-up save area of
pipeline. (2) A sequence of one or more commands in the dynamic data that the function operates upon.
FIFO order. The output of one command becomes the The three types of processes are:
input to the next command. A pipe usually contains
User processes, which are associated with a user at
several filters. Pipes allow related or unrelated
a workstation
processes to read and write to each other as if they
Daemon processes, which do systemwide functions
were files; they allow unidirectional communication from
in user mode, such as printer spooling
one process to another. OpenEdition Services treats
Kernel processes, which do systemwide functions in
pipes as though they were files. A named pipe has a
kernel mode, such as paging
directory name and is accessed by a pathname. An
unnamed pipe must be used between a parent process A process can run in a user address space, a forked
and a child process. (3) An object accessed by one of address space, or a kernel address space. In an MVS
the pair of file descriptors created by the pipe() system, a process is handled like a task. See also task.
Glossary 249
to the current directory. (2) A pathname that does not devices can communicate with each other. [OSF]
begin with a slash. The predecessor of the first filename (3) A collection of process groups established for job
in the pathname is taken to be the current working control purposes. Each process group is a member of a
directory of the process. [POSIX.1] See also absolute session. Each process is considered to be a member of
pathname, pathname. the session of which its process group is a member. A
newly created process joins the session of its creator. A
Resource Access Control Facility (RACF). An process can alter its session membership.
IBM-licensed program that provides for access control Implementations that support the setpgid() function can
by identifying and verifying the users to the system, have multiple process groups in the same session.
authorizing access to protected resources, and logging [POSIX.1] Every process group, and associated
detected unauthorized access to protected resources. process, belongs to a session. Any new process also
belongs to the session of the process that created it.
root. (1) The starting point of the file system. (2) The (4) In network architecture, an association of facilities
first directory in the file system. that establish, maintain, and release connections for
communication between stations. [OSF] (5) In SNA,
root directory. (1) The directory that contains all other a logical connection established between two network
directories in the system. (2) The lowest directory in addressable units (NAUs) that allows them to
the file system hierarchy. It is referred to as “/.” (3) A communicate. For routing purposes each session is
directory, associated with a process, that is used in identified by the local or network addresses of the
pathname resolution for pathnames that begin with a session partners.
slash. [POSIX.1] (4) The top directory in the file
system tree. UNIX and POSIX-conforming systems session leader. A process that has created a session.
have a single root directory, with mounted devices. [POSIX.1]
signal handler. A subroutine called when a signal superuser. A system user who operates without
occurs. [OSF] restrictions. A superuser has the special rights and
privileges needed to perform administrative tasks.
signal mask. A mask that defines the set of signals
currently blocked from delivery to a process. superuser authority. The unrestricted ability to
access and modify any part of the operating system,
standard error (stderr). (1) The place where many usually associated with the user who manages the
programs place error messages: the display screen system.
unless another place is specified with redirection.
[OSF] (2) An output stream usually intended to be supplementary group ID. An attribute of a process
used for diagnostic messages. [POSIX.2] (3) The used in determining file access permissions. A process
conventional name for file descriptor 2. By convention, has up to [NGROUPS_MAX] supplementary group IDs
programs write diagnostics and error messages to this in addition to the effective group ID. The supplementary
descriptor. Usually, the descriptor refers to the display group IDs of a process are set to the supplementary
screen, but it may be changed by redirection. This group IDs of the parent process when the process is
descriptor is separate from standard output so that error created. Whether a process's effective group ID is
diagnostics are still visible when the output is included in or omitted from its list of supplementary
redirected. group IDs is unspecified. [POSIX.1] In the OpenEdition
implementation, a supplementary group ID is an
standard input (stdin). (1) The primary source of attribute of a process used in determining file access
data going into a command. Standard input comes from permissions.
the keyboard unless redirection or piping is used, in
which case standard input can be from a file or the symbolic link. A type of file system entry that contains
output from another command. (2) An input stream the pathname of and acts as a pointer to another file or
usually intended to be used for primary data input. directory. [OSF]
[POSIX.2] (3) The conventional name for file
descriptor 0. By convention, programs read input from
this descriptor. Usually, the descriptor refers to the
T
keyboard, but it may be changed by redirection.
thread. (1) A single flow of control within a process.
[POSIX.0] (2) A single, sequential flow of control.
standard output (stdout). (1) The primary destination
of data coming from a command. Standard output goes
to the display unless redirection or piping is used, in
which case standard output can be to a file or another
U
command. (2) An output stream usually intended to be undub. The inverse of dub. Normally, a task (dubbed
used for primary data output. [POSIX.2] (3) The a thread) is undubbed when it ends. An address space
conventional name for file descriptor 1. By convention, (dubbed a process) is undubbed when the last dubbed
programs write output to this descriptor. Usually, the thread ends. Contrast with dub.
descriptor refers to the display screen, but may be
changed by redirection. UNIX. A highly portable operating system originally
developed by Bell Laboratories that features
stderr. Standard error. multiprogramming in a multiuser environment. UNIX is
implemented in the C language. UNIX was originally
stdin. Standard input. developed for use on minicomputers but has been
adapted on mainframes and microcomputers. It is
stdout. Standard output.
especially suitable for multiprocessor, graphics, and
vector-processing systems. Many of the commands in
sticky bit. A file access permission bit that allows
the OpenEdition shell are based on similar commands
multiple users to share a single copy of an executable
available with UNIX System V.
Glossary 251
unmount. To logically disassociate a mountable file user name. (1) In RACF, one to twenty alphanumeric
system from another file system. The TSO/E command characters that represent a RACF-defined user. (2) A
to perform this action is UNMOUNT or UMOUNT. string that is used to identify a user. [POSIX.1]
(3) Synonym for user ID.
user address space. An address space that has at
least one MVS task known to the kernel address space.
This address space can contain a shell or an V
application program that uses OpenEdition services.
VFS. Virtual file system.
user ID. (1) A unique string of characters that
identifies an operator to the system. This string of vnode. Virtual inode. An object in a file system that
characters limits the functions and information the represents a file. Unlike an inode, there is no
operator can use. (2) A nonnegative integer, which can one-to-one correspondence between a vnode and the
be contained in an object of type uid_t, that is used to file system; multiple vnodes can refer to a single file.
identify a system user. When the identity of the user is Vnodes are used to communicate between the upper
associated with a process, a user ID value is referred to half of the file system and the file system
as a real user ID, an effective user ID, or an (optional) representations.
saved set-user-ID. [POSIX.1] (3) The identification
associated with a user or job. The two types of user IDs
are:
W
TSO/E user ID: A string of characters that uniquely working directory. (1) The active directory used to
identifies a TSO/E user or a batch job owner to the resolve pathnames that do not begin with a slash. In
security program for the system. The batch job similar systems, a working directory may be called the
owner is specified on the USER parameter on the current directory or the current working directory. (2) A
JOB statement or inherited from the submitter of the directory, associated with a process, that is used in
job. This user ID identifies a RACF user profile. pathname resolution for pathnames that do not begin
OpenEdition user ID: A fullword integer that the with a slash. [POSIX.1] (3) Synonym for current
security administrator assigns to each MVS user ID. directory. (4) See also current directory.
This integer, referred to as the UID, is the sole
basis for authority checking against such write access. In computer security, permission to write
POSIX-defined resources as hierarchical files. to an object. Synonymous with write permission.
A user ID is equivalent to an account on other open write lock. A lock that prevents any other process
systems. (4) A symbol identifying a system user. from setting a read lock or a write lock on any part of
(5) Synonymous with user identification the protected area. Contrast with read lock. See also
lock.
user mode. In a multiprocessor environment, the slave
in a master-slave relationship. One processor operates write permission. Synonym for write access.
in kernel mode, the other (slave) in user mode. Kernel
mode handles the interrupts and callable service. User 3270 passthrough mode. A mode that lets a program
mode informs the master when making a callable running from the OpenEdition shell send and receive a
service. In user mode, a process is carried out in the 3270 data stream or issue TSO/E commands.
user's program rather than in the kernel. Contrast with
kernel mode.
Index 255
file (continued) file system (continued)
attributes, changing the 26, 41 unmounting a 168
changes unquiescing a 170
writing to DASD 70 file system server
changing the size of 71, 163 creating a file 198
closing a 34 creating a link 203
creating a 36 creating a new directory 210
erasing a 167 creating a symbolic link 222
group, changing the 33, 47 file attributes, setting 221
locks getting the attributes of a file 202
querying 54 locking
setting or releasing 63, 65 advisory 204
mode byte-range 204
changing 31, 46 reading data from a file 211
name, changing a 129 registering a process as a server 214
new releasing a vnode token 215
opening a 36 removing a directory entry 216
offset removing an empty directory 219
changing 103 renaming a file or directory 217
opening a 111 returning a vnode token 201
owner, changing the 33, 47, 101 returning entries from a directory 212
reading bytes from a 123 returning file system status 200
reading lines from a 126 returning the contents of a symbolic link 213
removing a 167 returning vnode and VFS tokens 220
status searching a directory for a file 209
obtaining 155 syscall commands
status flags FID 197
getting the 53 security 197
setting 62 tokens 197
status information VFS 197
accessing 67, 105 vnode 197
file access writing data to a file 224
determining 21 fork syscall command 56
file descriptor forkexecm syscall command 57
creating a 111 fpathconf syscall command 59
file descriptors PC_LINK_MAX 59
0,1, and 2 6, 14 PC_MAX_CANON 59
closing a range of 48 PC_MAX_INPUT 59
duplicating 37, 38, 50, 51 PC_NAME_MAX 59
file attributes, changing 41 PC_PATH_MAX 59
flags PC_PIPE_BUF 59
getting the 52 PC_POSIX_CHOWN_RESTRICTED 59
OS/390 OpenEdition REXX environment 15 PC_POSIX_NO_TRUNC 59
read or write error 6 PC_POSIX_VDISABLE 59
setting the flags 61 fstat syscall command 67
file mode S_FFBINARY 68
creation mask S_FFCR 68
changing the 165 S_FFCRLF 68
filename S_FFLF 68
portable filename character set 17 S_FFLFCR 68
file system S_FFNA 68
mounted S_FFNL 68
getting information about 69, 82, 83, 158 S_ISCHR 68
mounting a 109 S_ISDIR 68
quiescing a 120 S_ISFIFO 68
status S_ISREG 68
obtaining 157
Index 257
getpsent syscall command (continued) getpwuid syscall command (continued)
PS_CONTTY 88 PW_UID 93
PS_EGID 88 getrlimit syscall command 94
PS_EUID 88 RLIMIT_AS 94
PS_FGPID 88 RLIMIT_CORE 94
PS_FORK 89 RLIMIT_CPU 94
PS_FREEZE 89 RLIMIT_FSIZE 94
PS_MAXVNODES 88 RLIMIT_NOFILE 94
PS_MSGRCV 89 getuid syscall command 95
PS_MSGSND 89 gmtime syscall command 96
PS_PATH 88 TM_HOUR 96
PS_PAUSE 89 TM_ISDST 96
PS_PGPID 88 TM_MDAY 96
PS_PID 88 TM_MIN 96
PS_PPID 88 TM_MON 96
PS_QUIESCE 89 TM_SEC 96
PS_RGID 88 TM_WDAY 96
PS_RUID 88 TM_YDAY 96
PS_RUN 89 TM_YEAR 96
PS_SEMWT 89 GR_GID 76, 77, 78
PS_SERVERFLAGS 88 GR_MEM 76, 77, 78
PS_SERVERNAME 88 GR_MEMBERS 76, 77, 78
PS_SERVERTYPE 88 GR_NAME 76, 77, 78
PS_SGID 88 group
PS_SID 88 file or directory
PS_SIZE 88 changing the 33, 47, 101
PS_SLEEP 89 getting information about a 77, 78
PS_STARTTIME 88 symbolic link
PS_STAT 88 changing the 101
PS_STATE 89 group database
PS_SUID 89 retrieving an entry 76
PS_SYSTIME 89 rewinding the 135
PS_USERTIME 89
PS_VNODECOUNT 89
PS_WAITC 89 H
PS_WAITF 89 halt interruption 6
PS_WAITO 89 hard link 102
PS_ZOMBIE 89 removing a 167
PS_ZOMBIE2 89 host command environment
getpwent syscall command 91 customizing the 10
PW_DIR 91 OS/390 OpenEdition processing 1
PW_GID 91 SH 3
PW_NAME 91 input and output 5
PW_SHELL 91 return code 20
PW_UID 91 SYSCALL 2
getpwnam syscall command 92 ending the 3
PW_DIR 92 working directory 17
PW_GID 92
PW_NAME 92
PW_SHELL 92
I
input and output
PW_UID 92
OS/390 OpenEdition processing 5
getpwuid syscall command 93
using syscall commands 6
PW_DIR 93
ioctl syscall command 97
PW_GID 93
IRXEXEC service 14
PW_NAME 93
PW_SHELL 93
Index 259
MNTE_STATUS 84 opendir syscall command 113
MNTE_TYPE 84 OpenEdition
mode publications
changing 31, 46 on CD-ROM xiii
specifying 17 softcopy xiii
modification time, file operating system
setting the 171 getting information about the 166
mount syscall command 109 OS/390 OpenEdition processing
MTM_NOSUID 109 host command environments 1
MTM_RDONLY 109 input and output for 5
MTM_RDWR 109 using TSO/E REXX for 1
MTM_SYNCHONLY 109 OS/390 system
mounted file systems getting information about the 166
getting information about 82, 83 owner
MTM_DRAIN 168 file or directory
MTM_FORCE 168 changing the 33, 47, 101
MTM_IMMED 168 symbolic link
MTM_NORMAL 168 changing the 101
MTM_NOSUID 109
MTM_RDONLY 109
MTM_RDWR 109 P
MTM_REMOUNT 168 parent process ID
MTM_RESET 168 calling process, for the
MTM_SYNCHONLY 109 getting the 87
PARSE EXTERNAL instruction 6, 14
PARSE SOURCE instruction
N tokens returned 7
NUMBER OFF 4 passthrough mode, 3270 119
numeric pathconf syscall command 114
specifying 18 PC_LINK_MAX 114
PC_MAX_CANON 114
PC_MAX_INPUT 114
O PC_NAME_MAX 114
O_APPEND 53, 62, 111 PC_PATH_MAX 114
O_CREAT 53, 111 PC_PIPE_BUF 114
O_EXCL 53, 111 PC_POSIX_CHOWN_RESTRICTED 114
O_NOCTTY 53, 111 PC_POSIX_NO_TRUNC 114
O_NONBLOCK 53, 62, 111, 118 PC_POSIX_VDISABLE 114
O_RDONLY 53, 111 pathname
O_RDWR 53, 111 specifying 17
O_SYNC 53, 62, 111 terminal
O_TRUNC 53, 111 obtaining 164
O_WRONLY 53, 111 pause syscall command 116
octal numbers 235 PC_LINK_MAX 59, 114
offset, file 103 PC_MAX_CANON 59, 114
open syscall command 111 PC_MAX_INPUT 59, 114
O_APPEND 111 PC_NAME_MAX 59, 114
O_CREAT 111 PC_PATH_MAX 59, 114
O_EXCL 111 PC_PIPE_BUF 59, 114
O_NOCTTY 111 PC_POSIX_CHOWN_RESTRICTED 59, 114
O_NONBLOCK 111 PC_POSIX_NO_TRUNC 59, 114
O_RDONLY 111 PC_POSIX_VDISABLE 59, 114
O_RDWR 111 pending signals
O_SYNC 111 moving 145
O_TRUNC 111 performance 11
O_WRONLY 111
Index 261
realpath syscall command 128 saved set group ID
relative pathname calling process, for the
working directory 17 setting the 134
rename syscall command 129 saved set user ID
reserved variables 19 calling process, for the
Resource Access Control Facility (RACF) 11 setting the 141
resource limits SAY 14
getting 94 SAY instruction 6
setting 138 SC_2_CHAR_TERM 160
return code SC_ARG_MAX 160
descriptions 237 SC_CHILD_MAX 160
REXX program, from a 7 SC_CLK_TCK 160
SH host command environment 20 SC_JOB_CONTROL 160
shell 20 SC_NGROUPS_MAX 160
TSO/E 19 SC_OPEN_MAX 160
RETVAL 19 SC_SAVED_IDS 160
rewinddir syscall command 130 SC_THREAD_TASKS_MAX_NP 160
REXX environment SC_THREADS_MAX_NP 160
customizing the 10 SC_TZNAME_MAX 160
REXX program SC_VERSION 160
exit status 7 scope, variable 5
moving from TSO/E to the shell 9 seconds
run from the shell or a program 4 since Epoch
run from TSO/E or batch 2 returning 161
running from the shell or from a program 7 security
running from TSO/E or batch 8 file system server 197
REXX programming services 13 Resource Access Control Facility (RACF) 11
REXX service SEEK_CUR 55, 64, 66, 103
IRXEXEC 14 SEEK_END 55, 64, 66, 103
IRXJCL 14 SEEK_SET 55, 64, 66, 103
RLIM_INFINITY 138 sequence numbers, ISPF 4
RLIMIT_AS 94, 138 setegid syscall command 132
RLIMIT_CORE 94, 138 seteuid syscall command 133
RLIMIT_CPU 94, 138 setgid syscall command 134
RLIMIT_FSIZE 94, 138 setgrent syscall command 135
RLIMIT_NOFILE 94, 138 setpgid syscall command 136
rmdir syscall command 131 setpwent syscall command 137
routine setrlimit syscall command 138
signal interface routine 3 RLIM_INFINITY 138
RLIMIT_AS 138
RLIMIT_CORE 138
S RLIMIT_CPU 138
S_FFBINARY 68, 156 RLIMIT_FSIZE 138
S_FFCR 68, 156 RLIMIT_NOFILE 138
S_FFCRLF 68, 156 setsid syscall command 140
S_FFLF 68, 156 setuid syscall command 141
S_FFLFCR 68, 156 SH environment 3
S_FFNA 68, 156 input and output 5
S_FFNL 68, 156 shell
S_ISCHR 68, 156 return code 20
S_ISDIR 68, 156 running a REXX program from 4
S_ISFIFO 68, 156 SIG_BLOCK 146
S_ISREG 68, 156 SIG_CAT 143
S_ISSYM 68, 156 SIG_DFL 143
SA_NOCLDSTOP 143 SIG_IGN 143
Index 263
ST_BLKSIZE 68, 156 stat syscall command (continued)
ST_BLOCKS 68, 156 ST_MAJOR 156
ST_CCSID 68, 156 ST_MINOR 156
ST_CRTIME 68, 156 ST_MODE 156
ST_CTIME 26, 41, 68, 156 ST_MTIME 156
ST_DEV 68, 156 ST_NLINK 156
ST_EXTLINK 68, 156 ST_RTIME 156
ST_FID 68, 156 ST_SETGID 156
ST_FILEFMT 68, 156 ST_SETUID 156
ST_GENVALUE 26, 41, 68, 156 ST_SIZE 156
ST_GID 68, 156 ST_STICKY 156
ST_INO 68, 156 ST_TYPE 156
ST_MAJOR 68, 156 ST_UAUDIT 156
ST_MINOR 68, 156 ST_UID 156
ST_MODE 26, 41, 68, 156 statfs syscall command 157
ST_MTIME 26, 41, 68, 156 STFS_AVAIL 157
ST_NLINK 68, 156 STFS_BFREE 157
ST_RTIME 26, 41, 68, 156 STFS_BLOCKSIZE 157
ST_SETGID 26, 41, 68, 156 STFS_FAVAIL 157
ST_SETUID 26, 41, 68, 156 STFS_FFREE 157
ST_SIZE 26, 41, 68, 156 STFS_FILES 157
ST_STICKY 26, 41, 68, 156 STFS_FRSIZE 157
ST_TYPE 68, 156 STFS_FSID 157
ST_UAUDIT 26, 41, 68, 156 STFS_INUSE 157
ST_UID 26, 41, 68, 156 STFS_INVARSEC 157
starting time STFS_NAMEMAX 157
process, for a STFS_NOSUID 157
getting the 96 STFS_RDONLY 157
stat syscall command 155 STFS_TOTAL 157
S_FFBINARY 156 status
S_FFCR 156 file
S_FFCRLF 156 obtaining 155
S_FFLF 156 file system
S_FFLFCR 156 obtaining 157
S_FFNA 156 process
S_FFNL 156 obtaining 88
S_FILEFMT 156 statvfs syscall command 158
S_ISCHR 156 STFS_AVAIL 158
S_ISDIR 156 STFS_BFREE 158
S_ISFIFO 156 STFS_BLOCKSIZE 158
S_ISREG 156 STFS_FAVAIL 158
S_ISSYM 156 STFS_FFREE 158
ST_AAUDIT 156 STFS_FILES 158
ST_ATIME 156 STFS_FRSIZE 158
ST_AUDITID 156 STFS_FSID 158
ST_BLKSIZE 156 STFS_INUSE 158
ST_BLOCKS 156 STFS_INVARSEC 158
ST_CCSID 156 STFS_NAMEMAX 158
ST_CRTIME 156 STFS_NOSUID 158
ST_CTIME 156 STFS_RDONLY 158
ST_DEV 156 STFS_TOTAL 158
ST_EXTLINK 156 STDERR 6
ST_FID 156 STDIN 6
ST_GENVALUE 156 STDOUT 6
ST_GID 156 stem
ST_INO 156 specifying 17
Index 265
unmount syscall command 168 v_getattr syscall command (continued)
MTM_DRAIN 168 ST_ATIME 156
MTM_FORCE 168 ST_AUDITID 156
MTM_IMMED 168 ST_BLKSIZE 156
MTM_NORMAL 168 ST_BLOCKS 156
MTM_REMOUNT 168 ST_CCSID 156
MTM_RESET 168 ST_CRTIME 156
unquiesce syscall command 170 ST_CTIME 156
user ST_EXTLINK 156
identified by user ID ST_FID 156
getting information about a 93 ST_FILEFMT 156
identified by user name ST_GENVALUE 156
getting information about a 92 ST_GID 156
login name ST_INO 156
getting a 81 ST_MAJOR 156
supplementary group IDs ST_MINOR 156
getting the 80 ST_MODE 156
user database ST_MTIME 156
retrieving an entry 91 ST_NLINK 156
rewinding the 137 ST_RTIME 156
utime syscall command 171 ST_SETGID 156
ST_SETUID 156
ST_SIZE 156
V ST_STICKY 156
v_create syscall command 198 ST_TYPE 156
v_fstatfs ST_UAUDIT 156
STFS_AVAIL 157 ST_UID 156
STFS_BFREE 157 v_link syscall command 203
STFS_BLOCKSIZE 157 v_lockctl syscall command 204
STFS_FAVAIL 157 F_RDLCK 55
STFS_FFREE 157 F_UNLCK 55
STFS_FILES 157 F_WRLCK 55
STFS_FRSIZE 157 L_LEN 55
STFS_FSID 157 L_PID 55
STFS_INUSE 157 L_START 55
STFS_INVARSEC 157 L_TYPE 55
STFS_NAMEMAX 157 L_WHENCE 55
STFS_NOSUID 157 SEEK_CUR 55
STFS_RDONLY 157 SEEK_END 55
STFS_TOTAL 157 SEEK_SET 55
v_fstatfs syscall command 200 VL_CLIENTPID 204
v_get syscall command 201 VL_CLIENTTID 204
v_getattr syscall command 202 VL_DOSACCESS 205
S_FFBINARY 156 VL_DOSMODE 205
S_FFCR 156 VL_LOCK 204
S_FFCRLF 156 VL_LOCKERTOK 204
S_FFLF 156 VL_LOCKWAIT 204
S_FFLFCR 156 VL_OBJCLASS 204
S_FFNA 156 VL_OBJID 204
S_FFNL 156 VL_OBJTOK 204
S_ISCHR 156 VL_PURGE 204
S_ISDIR 156 VL_QUERY 204
S_ISFIFO 156 VL_REGLOCKER 204
S_ISREG 156 VL_SERVERPID 204
S_ISSYM 156 VL_UNLOCK 204
ST_AAUDIT 156 VL_UNREGLOCKER 204
Index 267
v_read syscall command (continued) v_rpn syscall command (continued)
ST_NLINK 156 ST_AAUDIT 156
ST_RTIME 156 ST_ATIME 156
ST_SETGID 156 ST_AUDITID 156
ST_SETUID 156 ST_BLKSIZE 156
ST_SIZE 156 ST_BLOCKS 156
ST_STICKY 156 ST_CCSID 156
ST_TYPE 156 ST_CRTIME 156
ST_UAUDIT 156 ST_CTIME 156
ST_UID 156 ST_EXTLINK 156
v_readdir syscall command 212 ST_FID 156
v_readlink syscall command 213 ST_FILEFMT 156
v_reg syscall command 214 ST_GENVALUE 156
v_rel syscall command 215 ST_GID 156
v_remove syscall command 216 ST_INO 156
v_rename syscall command 217 ST_MAJOR 156
v_rmdir syscall command 219 ST_MINOR 156
v_rpn syscall command 220 ST_MODE 156
MNT_ASYNCHMOUNT 84 ST_MTIME 156
MNT_FILEACTIVE 84 ST_NLINK 156
MNT_FILEDEAD 84 ST_RTIME 156
MNT_FILEDRAIN 84 ST_SETGID 156
MNT_FILEFORCE 84 ST_SETUID 156
MNT_FILEIMMED 84 ST_SIZE 156
MNT_FILENORM 84 ST_STICKY 156
MNT_FILERESET 84 ST_TYPE 156
MNT_IMMEDTRIED 84 ST_UAUDIT 156
MNT_MODE_RDONLY 83 ST_UID 156
MNT_MODE_RDWR 83 v_setattr syscall command 221
MNT_MOUNTINPROGRESS 84 ST_AAUDIT 26
MNT_QUIESCED 84 ST_ATIME 26
MNTE_DD 83 ST_CTIME 26
MNTE_DEV 83 ST_GENVALUE 26
MNTE_FSNAME 83 ST_MODE 26
MNTE_FSTYPE 83 ST_MTIME 26
MNTE_MODE 83 ST_RTIME 26
MNTE_PARDEV 83 ST_SETGID 26
MNTE_PARM 83 ST_SETUID 26
MNTE_PATH 83 ST_SIZE 26
MNTE_QJOBNAME 83 ST_STICKY 26
MNTE_QPID 83 ST_UAUDIT 26
MNTE_ROOTINO 83 ST_UID 26
MNTE_STATUS 84 v_symlink syscall command 222
MNTE_TYPE 84 v_write syscall command 224
S_FFBINARY 156 S_FFBINARY 156
S_FFCR 156 S_FFCR 156
S_FFCRLF 156 S_FFCRLF 156
S_FFLF 156 S_FFLF 156
S_FFLFCR 156 S_FFLFCR 156
S_FFNA 156 S_FFNA 156
S_FFNL 156 S_FFNL 156
S_ISCHR 156 S_ISCHR 156
S_ISDIR 156 S_ISDIR 156
S_ISFIFO 156 S_ISFIFO 156
S_ISREG 156 S_ISREG 156
S_ISSYM 156 S_ISSYM 156
W
W_CONTINUED 172
W_EXITSTATUS 172
W_IFEXITED 172
W_IFSIGNALED 172
W_IFSTOPPED 172
W_OK 21
W_STAT3 172
W_STAT4 172
W_STOPSIG 172
W_TERMSIG 172
wait syscall command 172
W_CONTINUED 172
W_EXITSTATUS 172
W_IFEXITED 172
W_IFSIGNALED 172
Index 269
Communicating Your Comments to IBM
OS/390
Using REXX and OS/390 OpenEdition
Publication No. SC28-1905-02
If you especially like or dislike anything about this book, please use one of the methods
listed below to send your comments to IBM. Whichever method you choose, make sure you
send your name, address, and telephone number if you would like a reply.
Feel free to comment on specific errors or omissions, accuracy, organization, subject matter,
or completeness of this book. However, the comments you send should pertain to only the
information in this manual and the way in which the information is presented. To request
additional publications, or to ask questions or make comments about the functions of IBM
products or systems, you should talk to your IBM representative or to your IBM authorized
remarketer.
When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute
your comments in any way it believes appropriate without incurring any obligation to you.
If you are mailing an RCF from a country other than the United States, you can give the
RCF to the local IBM branch office or IBM representative for postage-paid mailing.
If you prefer to send comments by mail, use the RCF at the back of this book.
If you prefer to send comments by FAX, use this number:
– FAX: (International Access Code)+1+914+432-9405
If you prefer to send comments electronically, use this network ID:
– IBMLink: (United States customers only): KGNVMC(MHVRCFS)
– IBM Mail Exchange: USIB6TC9 at IBMMAIL
– Internet e-mail: mhvrcfs@vnet.ibm.com
– World Wide Web: http://www.s390.ibm.com/os390
Optionally, if you include your telephone number, we will be able to respond to your
comments by phone.
Reader's Comments — We'd Like to Hear from You
OS/390
Using REXX and OS/390 OpenEdition
Publication No. SC28-1905-02
You may use this form to communicate your comments about this publication, its organization, or subject
matter, with the understanding that IBM may use or distribute whatever information you supply in any way
it believes appropriate without incurring any obligation to you. Your comments will be sent to the author's
department for whatever review and action, if any, are deemed appropriate.
Note: Copies of IBM publications are not stocked at the location to which this form is addressed. Please
direct any requests for copies of publications, or for assistance in using your IBM system, to your IBM
representative or to the IBM branch office serving your locality.
Today's date:
Newsletter number of latest Technical Newsletter (if any) concerning this publication:
Is there anything you especially like or dislike about the organization, presentation, or writing in this
manual? Helpful comments include general usefulness of the book; possible additions, deletions, and
clarifications; specific errors and omissions.
Page Number: Comment:
Name Address
Company or Organization
Phone No.
Cut or Fold
Reader's Comments — We'd Like to Hear from You
IBM
Along Line
SC28-1905-02
NO POSTAGE
NECESSARY
IF MAILED IN THE
UNITED STATES
IBM Corporation
Department 55JA, Mail Station P384
522 South Road
Poughkeepsie NY 12601-5400
Cut or Fold
SC28-1905-02 Along Line
IBM
SC28-19ð5-ð2