CIFS for ClearPath OS 2200 User, Programmer, and Administrator ...

ClearPath Enterprise Servers
CIFS for ClearPath OS 2200
User, Programmer, and Administrator Reference
Manual
Level 6R3
June 2009 7859 6137–009
unisys
imagine it. done.

NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information
described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to
purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the
products described in this document are set forth in such agreement. Unisys cannot accept any financial or other
responsibility that may be the result of your use of the information in this document or software material, including
direct, special, or consequential damages.
You should be very careful to ensure that the use of this information and/or software material complies with the laws,
rules, and regulations of the jurisdictions with respect to which it is used.
The information contained herein is subject to change without notice. Revisions may be issued to advise of such
changes and/or additions.
Notice to U.S. Government End Users: This is commercial computer software or hardware documentation developed at
private expense. Use, reproduction, or disclosure by the Government is subject to the terms of Unisys standard
commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data
rights clauses.
Unisys and ClearPath are registered trademarks of Unisys Corporation in the United States and other countries.
All other brands and products referenced in this document are acknowledged to be the trademarks or registered
trademarks of their respective holders.

ClearPath Enterprise
Servers
CIFS for ClearPath OS 2200
User, Programmer, and
Administrator Reference
Manual
Level 6R3
ClearPath
Enterprise Servers
CIFS for ClearPath
OS 2200
User,
Programmer,
and
Administrator
Reference
Manual
Level 6R3
7859 6137–009 7859 6137–009
Bend here, peel upwards and apply to spine.

Contents
Section 1. Introduction
What CIFS Does ................................................................................... 1–2
Purpose of This Manual ........................................................................ 1–3
Documentation Updates ....................................................................... 1–3
Audience ............................................................................................... 1–3
Notation Conventions ........................................................................... 1–4
File System Structure ........................................................................... 1–5
OS 2200 Directory Hierarchy ............................................... 1–6
Non-/OS2200 Directory Hierarchy ....................................... 1–7
Data Storage ........................................................................ 1–8
File Packing ........................................................................................... 1–9
Security Considerations ...................................................................... 1–10
Communications Interface .................................................................. 1–11
TIP Considerations .............................................................................. 1–12
Section 2. Managing Files from the Workstation
Networking CIFS with Windows NT4/2000/XP/2003/Vista and
Windows 95/98/Me .......................................................................... 2–1
Creating a Share Directory .................................................................... 2–3
Mapping a Drive to a Share Directory ................................................... 2–4
Opening Share Files Using UNC ........................................................... 2–5
Viewing CIFS Directories ...................................................................... 2–7
Section 3. File Concepts
File Definition and File Types ................................................................ 3–1
File Names ........................................................................... 3–2
Directory Definition and Rules for Directories ...................................... 3–4
Rules for Creating Directory Entries .................................... 3–4
Diagram of Directories, Files, and Links .............................. 3–5
File Hierarchies ..................................................................................... 3–6
Path Names........................................................................................... 3–7
Special Path Name Components ......................................... 3–8
Path Name Resolution .......................................................................... 3–9
Open File Descriptions ........................................................................ 3–11
File Descriptors ................................................................................... 3–13
File Permissions .................................................................................. 3–14
Time Information for Files ................................................................... 3–17
File Attributes ...................................................................................... 3–18
File Mode ............................................................................................ 3–18
File Permissions ................................................................ 3–19
7859 6137–009 iii

Contents
File Format ......................................................................... 3–21
File Type ............................................................................. 3–21
Related Functions ................................................................................ 3–23
File I/O Operations ............................................................................... 3–24
Reading and Writing to Files .............................................. 3–24
Directory Entries and Streams ........................................... 3–25
Data Translation .................................................................. 3–25
Advisory Record Locks ....................................................... 3–26
Using Pipes ........................................................................ 3–29
Related Functions ............................................................... 3–31
Environment Variables ......................................................................... 3–32
Section 4. Utility Interfaces
Masking with @CIFSUT ......................................................................... 4–3
backup ................................................................................................... 4–4
binjar ...................................................................................................... 4–5
cat (type) ................................................................................................ 4–6
cd (chdir) ................................................................................................ 4–7
chmod .................................................................................................... 4–8
chown .................................................................................................. 4–10
cp (copy) .............................................................................................. 4–11
date ...................................................................................................... 4–13
deltree .................................................................................................. 4–14
echo ..................................................................................................... 4–15
help ...................................................................................................... 4–16
keys...................................................................................................... 4–17
ln ......................................................................................................... 4–18
ls (dir) ................................................................................................... 4–19
mkdir (md) ............................................................................................ 4–22
mkfifo ................................................................................................... 4–23
mv (move) ............................................................................................ 4–24
pwd (cd) ............................................................................................... 4–25
rm (del) ................................................................................................. 4–26
rmdir (rd) .............................................................................................. 4–28
set ........................................................................................................ 4–29
setsys .................................................................................................. 4–30
share .................................................................................................... 4–31
size ....................................................................................................... 4–32
touch .................................................................................................... 4–33
unshare ................................................................................................ 4–35
use ....................................................................................................... 4–36
version ................................................................................................. 4–37
xlate ..................................................................................................... 4–38
Section 5. C Program Interfaces
Table of C APIs ...................................................................................... 5–2
access() .................................................................................................. 5–6
chdir() ..................................................................................................... 5–8
chmod() .................................................................................................. 5–9
iv 7859 6137–009

Contents
chown() ............................................................................................... 5–11
clearerr() .............................................................................................. 5–13
close() .................................................................................................. 5–14
closedir() .............................................................................................. 5–15
creat() .................................................................................................. 5–16
dup() .................................................................................................... 5–18
dup2() .................................................................................................. 5–19
end_process() ...................................................................................... 5–20
fclose() ................................................................................................. 5–21
fcntl() ................................................................................................... 5–22
fdatasync() ........................................................................................... 5–33
fdopen() ............................................................................................... 5–34
feof() .................................................................................................... 5–35
ferror() ................................................................................................. 5–36
fflush() ................................................................................................. 5–37
fgetc() .................................................................................................. 5–38
fgetpos() .............................................................................................. 5–39
fgets() .................................................................................................. 5–40
fileno() ................................................................................................. 5–41
fopen() ................................................................................................. 5–42
fprintf() ................................................................................................. 5–44
fputc() .................................................................................................. 5–49
fputs() .................................................................................................. 5–50
fread() .................................................................................................. 5–51
freopen() .............................................................................................. 5–52
fscanf() ................................................................................................ 5–53
fseek() ................................................................................................. 5–57
fsetpos() .............................................................................................. 5–58
fstat() ................................................................................................... 5–59
fsync() .................................................................................................. 5–61
ftell() .................................................................................................... 5–62
ftruncate() ............................................................................................ 5–63
fwrite() ................................................................................................. 5–64
getc() ................................................................................................... 5–65
getchar() .............................................................................................. 5–66
getcwd() .............................................................................................. 5–67
getpwnam() ......................................................................................... 5–68
getpwuid() ........................................................................................... 5–69
gets() ................................................................................................... 5–71
getuid() ................................................................................................ 5–72
istat() ................................................................................................... 5–73
link() ..................................................................................................... 5–75
lseek() .................................................................................................. 5–78
mask() .................................................................................................. 5–81
mkdir() ................................................................................................. 5–82
mkfifo() ................................................................................................ 5–84
new_process() ..................................................................................... 5–86
open() .................................................................................................. 5–87
opendir() .............................................................................................. 5–94
pack() ................................................................................................... 5–95
perror() ................................................................................................. 5–97
pipe() ................................................................................................... 5–98
7859 6137–009 v

Contents
printf() ................................................................................................ 5–100
putc() .................................................................................................. 5–101
putchar() ............................................................................................. 5–102
puts() .................................................................................................. 5–103
read() .................................................................................................. 5–104
readdir() .............................................................................................. 5–107
realpath() ............................................................................................ 5–109
remove() ............................................................................................. 5–110
rename() ............................................................................................. 5–111
rewind() .............................................................................................. 5–115
rewinddir() .......................................................................................... 5–116
rmdir() ................................................................................................ 5–117
scanf() ................................................................................................ 5–118
share() ................................................................................................ 5–119
sprintf() ............................................................................................... 5–120
sscanf() .............................................................................................. 5–121
stat() ................................................................................................... 5–122
strerror() ............................................................................................. 5–123
tmpfile() .............................................................................................. 5–124
tmpnam() ........................................................................................... 5–125
truncate() ............................................................................................ 5–126
umask() .............................................................................................. 5–127
uname() .............................................................................................. 5–129
ungetc() .............................................................................................. 5–130
unlink() ............................................................................................... 5–131
utime() ................................................................................................ 5–132
vfprintf() ............................................................................................. 5–135
vprintf() ............................................................................................... 5–136
vsprintf() ............................................................................................. 5–137
write() ................................................................................................. 5–138
xlate() ................................................................................................. 5–142
Section 6. COBOL Program Interfaces
Table of UCOB COPY PROCS ............................................................... 6–1
Table of UCOB APIs .............................................................................. 6–2
CIFS$ACCESS ....................................................................................... 6–5
CIFS$CHDIR .......................................................................................... 6–8
CIFS$CHMOD ....................................................................................... 6–9
CIFS$CHOWN ..................................................................................... 6–12
CIFS$CLEARERR ................................................................................. 6–14
CIFS$CLOSE ........................................................................................ 6–15
CIFS$CLOSEDIR .................................................................................. 6–17
CIFS$CREAT ........................................................................................ 6–19
CIFS$DUP ............................................................................................ 6–21
CIFS$DUP2 .......................................................................................... 6–23
CIFS$FCLOSE ...................................................................................... 6–25
CIFS$FCNTL ........................................................................................ 6–26
CIFS$FDATASYNC .............................................................................. 6–39
CIFS$FDOPEN ..................................................................................... 6–41
CIFS$FEOF .......................................................................................... 6–43
vi 7859 6137–009

Contents
CIFS$FERROR .................................................................................... 6–44
CIFS$FFLUSH ..................................................................................... 6–45
CIFS$FGETC ....................................................................................... 6–46
CIFS$FGETPOS .................................................................................. 6–47
CIFS$FGETS........................................................................................ 6–48
CIFS$FILENO ...................................................................................... 6–49
CIFS$FOPEN ....................................................................................... 6–50
CIFS$FPRINTF .................................................................................... 6–52
CIFS$FPUTC ....................................................................................... 6–57
CIFS$FPUTS........................................................................................ 6–58
CIFS$FREAD ....................................................................................... 6–59
CIFS$FREOPEN .................................................................................. 6–61
CIFS$FSCANF ..................................................................................... 6–63
CIFS$FSEEK ........................................................................................ 6–67
CIFS$FSETPOS ................................................................................... 6–68
CIFS$FSTAT ........................................................................................ 6–69
CIFS$FSYNC ....................................................................................... 6–71
CIFS$FTELL ........................................................................................ 6–72
CIFS$FTRUNCATE .............................................................................. 6–73
CIFS$FWRITE ..................................................................................... 6–74
CIFS$GETC ......................................................................................... 6–75
CIFS$GETCWD ................................................................................... 6–77
CIFS$GETS.......................................................................................... 6–78
CIFS$ISTAT ......................................................................................... 6–79
CIFS$LINK ........................................................................................... 6–81
CIFS$LSEEK ........................................................................................ 6–84
CIFS$MASK ........................................................................................ 6–87
CIFS$MKDIR ....................................................................................... 6–88
CIFS$MKFIFO ..................................................................................... 6–90
CIFS$OPEN ......................................................................................... 6–92
CIFS$OPENDIR ................................................................................. 6–100
CIFS$PACK ....................................................................................... 6–102
CIFS$PERROR .................................................................................. 6–104
CIFS$PIPE ......................................................................................... 6–105
CIFS$PRINTF .................................................................................... 6–107
CIFS$PUTC ....................................................................................... 6–108
CIFS$PUTCHAR ................................................................................ 6–109
CIFS$PUTS........................................................................................ 6–110
CIFS$READ ....................................................................................... 6–111
CIFS$READDIR ................................................................................. 6–115
CIFS$REMOVE ................................................................................. 6–118
CIFS$RENAME ................................................................................. 6–119
CIFS$REWIND .................................................................................. 6–123
CIFS$REWINDDIR ............................................................................ 6–124
CIFS$RMDIR ..................................................................................... 6–126
CIFS$SCANF ..................................................................................... 6–128
CIFS$SHARE ..................................................................................... 6–129
CIFS$SPRINTF .................................................................................. 6–130
CIFS$SSCANF ................................................................................... 6–131
CIFS$STAT ........................................................................................ 6–132
CIFS$STDERR ................................................................................... 6–134
CIFS$STDIN ...................................................................................... 6–135
7859 6137–009 vii

Contents
Section 7. CIFS Client
CIFS$STDOUT ................................................................................... 6–136
CIFS$STRERROR .............................................................................. 6–137
CIFS$TMPFILE .................................................................................. 6–138
CIFS$TMPNAM ................................................................................. 6–139
CIFS$TRUNCATE ............................................................................... 6–140
CIFS$UMASK .................................................................................... 6–141
CIFS$UNAME .................................................................................... 6–143
CIFS$UNGETC ................................................................................... 6–144
CIFS$UNLINK .................................................................................... 6–145
CIFS$UTIME ...................................................................................... 6–147
CIFS$WRITE ...................................................................................... 6–150
CIFS$XLATE ...................................................................................... 6–155
Example Program .............................................................................. 6–157
Accessing a Remote System ................................................................ 7–1
Using Passwords ................................................................................... 7–3
Section 8. ZIPUT Processor
Using the ZIPUT Processor ................................................................... 8–1
ZIPUT Arguments .................................................................................. 8–2
Section 9. Administration
CIFS Installation Overview .................................................................... 9–1
Directory Synchronization ...................................................................... 9–2
CIFS Subsystem User ID ....................................................................... 9–4
Populate ................................................................................................. 9–4
Starting the CIFS Background Run ........................................................ 9–5
Stopping the CIFS Subsystem and Background Run ............................ 9–7
CIFS Background Run Options .............................................................. 9–8
CIFS Background Run Console Keyins .................................................. 9–9
CIFS Backup Procedure ....................................................................... 9–10
CIFS File Security Enforcement ........................................................... 9–11
CIFS Network Access Security ............................................................ 9–12
Local OS 2200 Authentication ............................................................. 9–13
Network Authentication ....................................................................... 9–14
OS 2200 User ID Requirements .......................................................... 9–18
LAN Manager Authentication Level ..................................................... 9–20
Environment Variables ......................................................................... 9–21
File Filtering ......................................................................................... 9–26
Appendix A. Limitations, Considerations, and Restrictions
Appendix B. Error Codes
Glossary ............................................................................................. 1
viii 7859 6137–009

Contents
Index ............................................................................................. 1
7859 6137–009 ix

Contents
x 7859 6137–009

Figures
9–1. Network Authentication Menu Items .............................................................. 9–15
9–2. Example Fully-Qualified Network User Name ................................................. 9–17
7859 6137–009 xi

Figures
xii 7859 6137–009

Section 1
Introduction
This guide describes CIFS for ClearPath OS 2200, an implementation of the Common
Internet File System (CIFS) specification that allows access to OS 2200 files through
standard Internet protocols.
CIFS permits direct access to files stored in OS 2200 through SMB clients like Windows
Explorer. Users can move, copy, delete, and display properties of their OS 2200 files.
They can also edit files with Notepad, Word, image processors, and so on, and save
changes to the files. Using Windows drag-and-drop functions, users can copy or move
files between their workstation and OS 2200.
The CIFS specification is created by Microsoft Corporation and is based on the existing
Server Messages Block (SMB) protocol. SMB is a client/server request/response
protocol for sharing files, printers, serial ports, and communication abstractions.
Programmers access CIFS services and Application Program Interfaces (APIs) by calling
them as functions from a C compiler and COBOL compiler program. Most services can
also be accessed through utility commands.
CIFS includes four components: the CIFS Host Infrastructure subsystem (CIFSHI), the
CIFS Library (CIFSLIB), the CIFS Utility (CIFSUT), and the ZIP Utility (ZIPUT). The CIFSHI
component includes the communications layers necessary for a remote client to use
CIFS on OS 2200 and for OS 2200 programs to access files on remote hosts, as well as
the file system structure and host APIs. CIFSLIB consists of a C compiler and COBOL
compiler-callable layer of interfaces to CIFSHI as well as I/O stream handling functions.
CIFSUT provides a simple command-line interface to CIFS capabilities. ZIPUT
manipulates ZIP files or other archives using the ZIP file format.
CIFS supports Windows 95/98/Me, Windows NT4/2000/XP/2003/Vista, and other SMB
clients (such as Samba). See Appendix A, “Limitations, Considerations, and
Restrictions.”
7859 6137–009 1–1

Introduction
What CIFS Does
When CIFS is installed on OS 2200, it sets up an alternative file system with a POSIX-like
hierarchical directory structure (an inverted tree-like structure with branches from the
system root directory to each file and directory) that supports long file and directory
names. A background run populates a special directory, called /os2200, with aliases for
all OS 2200 files (except certain system files) found in the Exec Master File Directories
(MFD).
The CIFS installation process also installs a text-based utility, @CIFSUT that provides a
command line interface to manipulate files and directories within the CIFS file system.
The utility accepts commands modeled after those typically available in Windows
95/98/Me and Windows NT4/2000/XP/2003/Vista systems, and other systems similar to
UNIX.
Using @CIFSUT, users can create non-/os2200 directories and files. They can also make
directories visible on a network using the CIFS share interface. Once a share directory is
created, users can manage the files and directories to which they have the necessary
access permissions. Using Windows Explorer, users can move, copy, delete, edit (using
Windows programs), save, and display the properties of any file in a share directory
(again, assuming they have the correct permissions).
CIFS creates an alias for each file added to a non-/os2200 directory. This alias has a
native OS 2200 file name and appears in the /os2200 directory. Therefore, all the files in
the non-/os2200 hierarchy has two file names in CIFS: the name assigned by the user
and a native OS 2200 name.
CIFS continuously maintains its file structure by monitoring system log entries to keep
the /os2200 directory in sync with the Exec MFDs. As a result, every file that is
cataloged, deleted, or has its accessibility changed in an Exec MFD automatically causes
the associated update in the CIFS directories. To ensure the CIFS directories are brought
up to date, a synchronization process is run every time the CIFS subsystem initializes
and at the site administrator’s discretion.
The following diagram shows an example file structure created by CIFS. Note that the
element “myfile” can be accessed by the path name /gjs3/Directory1/myfile or by its
native OS 2200 name /os2200/qual/file/myfile.
1–2 7859 6137–009

Introduction
When a file is created in the non-/os2200 directory hierarchy, CIFS normally stores the
file data as an OS 2200 SDF element. It uses OS 2200 file and element names
consisting of the qualifier SYS$CIFS$, an internally generated file name, and the
requested name and extension as element and version, if possible. If the specified file
name is not a legal OS 2200 element name (it is too long or contains illegal characters),
CIFS generates a 12/12 alias for the OS 2200 element and version.
Purpose of This Manual
This manual supports the Common Interface File System (CIFS) implementation for the
ClearPath OS 2200 by describing CIFS. It includes user, programmer, and administrator
information, and is intended for use with all supported OS 2200 systems.
Use this manual to look up specific topics or read it sequentially to learn about unfamiliar
topics. The guide contains information to introduce CIFS, define terminology, and
summarize functions.
Documentation Updates
Audience
otherfile
gjs3
This document contains all the information that was available at the time of publication.
Changes identified after release of this document are included in problem list entry (PLE)
18569205. To obtain a copy of the PLE, contact your Unisys representative or access the
current PLE from the Unisys Product Support Web site:
http://www.support.unisys.com/all/ple/18569205
/os2200
Note: If you are not logged into the Product Support site, you will be asked to do so.
This manual is intended for OS 2200 end users, system administrators, C and COBOL
programmers whose applications must be portable or who wish to use CIFS capabilities.
Users must have a good understanding of the OS 2200 file structure but not necessarily
the CIFS specification. Knowledge of Windows or POSIX-compliant file systems can be
useful.
7859 6137–009 1–3
/
Directory1
myfile myfile
file
qual

Introduction
Notation Conventions
The following notation and organizational conventions are used throughout this manual:
• Brackets ([ ])
Brackets enclose optional arguments. The brackets themselves are not coded when
using a CIFS interface.
• Vertical bar (|)
A vertical bar means the arguments are mutually exclusive and you can use only one.
Using two or more mutually exclusive arguments produces undefined results, unless
otherwise stated.
• Ellipsis (...)
An ellipsis means the previous syntax (either an option and its option argument or an
operand) can occur one or more times.
If the ellipsis follows syntax that is enclosed in brackets, the syntax in the brackets
can occur zero or more times. Do not repeat an option that does not have an option
argument because the results are undefined, unless otherwise stated.
• Options
− Hyphen (POSIX format) or a forward slash (Windows format)
A hyphen or a forward slash identifies the argument that follows it as an option;
the delimiter is therefore required.
− Grouped order
Individual options are usually grouped ahead of options that take arguments.
Only one hyphen is required to precede a group of options.
− Alphabetical order
Within a group (that is, options with or without arguments), options are usually
listed alphabetically for convenience, but have no implied relationships unless
order dependencies are stated. When used, independent options can appear in
any order.
− Space
• Operands
A space shown between an option and its argument in the synopsis is optional
unless otherwise stated. However, including a blank always results in correct
code and is recommended for portable applications. When the synopsis shows
no space between an option and its argument, the argument must immediately
follow the option.
− Order
The order of operands is significant.
1–4 7859 6137–009

− Blanks
A blank (sequence of spaces) is required to separate operands.
• Multiple lines
Introduction
Complex or mutually exclusive cases can be shown on separate lines, especially if
mutually exclusive arguments affect the validity of other options and operands for
that case.
• Indentation
Indented lines merely continue the argument and do not imply new input lines.
When used, these lines appear on a single logical line.
• Default case
For some interfaces, the synopsis contains the default case showing the values used
for certain options when you call the utility without arguments. Default values are
also included in the appropriate option descriptions.
• Graphics symbols
The following symbols are used in graphics throughout this document:
− Circles are usually used to represent processes and directories.
− Cylinders or rectangles are used to represent files.
• Variable entities in syntax appear in italics as in the following example, where path
and mode are the variables:
int creat(const char * path, mode_t mode);
• Symbolic constants include attributes, valid values for function variables, privileges,
and defined keywords; they are in uppercase type. Examples include S_1100SDF
and O_CREAT.
• Function names, standard field names in structures, and standard variable names are
in lowercase type. Function names are always followed by parentheses; field names
can contain underscores. Some examples are
− The open() function
− The st_mode member of the stat structure
− The errno variable
File System Structure
CIFS uses a POSIX-like hierarchical directory structure that supports long file and
directory names. Names in each level are separated by a forward slash (/) character.
Each file and directory name can be up to 4095 bytes long. When creating files and
directories, CIFS maintains the case of alphabetic characters but ignores case based on
the ISO 8859-1 character set when accessing existing names.
7859 6137–009 1–5

Introduction
A reference to a CIFS file or directory that begins with a forward slash is considered an
absolute reference. The path to the file or directory starts at the root of the file system
hierarchy. A reference that does not begin with a slash is interpreted as relative to the
caller’s current working directory. (CIFS supplies several mechanisms for changing the
current working directory; see below for details.) Directory references that consist only
of one or more periods are interpreted as designating directory entries in the hierarchy.
One period indicates the current directory in the reference, two periods indicate the
parent of the current directory in the reference, three periods indicate the parent’s
parent, and so on.
For example, the following utility command
cd /a/b/c/d/e/f/...
sets the current working directory to /a/b/c/d.
OS 2200 Directory Hierarchy
CIFS provides access to all OS 2200 files and elements through a special directory:
/os2200. During CIFS initialization, all OS 2200 files (except certain system files) are
automatically added to the /os2200 directory. CIFS monitors changes to the OS 2200 file
environment and updates the /os2200 hierarchy accordingly.
Files and elements are addressed within the /os2200 directory with the following name
mapping:
/os2200/[mfd#]qual/file[([+|-]n)][/elt[.[ver][.type]]]
where:
os2200 is the special reserved directory name.
mfd# is the OS 2200 Master File Directory (MFD), either STD# or SHARED#
qual is the OS 2200 file qualifier.
file is the OS 2200 file name.
n is an optional absolute or relative F-cycle.
elt is the OS 2200 program file element name.
ver is the OS 2200 program file element version.
type is an optional OS 2200 element type (one of the following: rel, abs, omn); a
symbolic (SDF) element is used if a type is not explicitly specified.
If an MFD is specified, only a file or directory in the requested MFD (STD# or SHARED#)
can be accessed. If no MFD is specified, selection depends on the Exec configuration
parameters DOUBLE_MFD_SEARCH and DIRECTORY_SELECTION, as well as the
user’s current @QUAL,D setting. If an F-cycle is not specified, the latest F-cycle is
assumed. If an element name is not specified, an OS 2200 data or program file is
assumed. If neither an element version nor an element type is specified, the period
before the version field must also be omitted.
1–6 7859 6137–009

Introduction
New OS 2200 data and program files can be created in the /os2200 directory hierarchy,
but the qualifier and file name must conform to the OS 2200 qualifier and file name
syntax rules: 12 characters or less consisting of any combination of letters, numbers,
hyphen (-), and the dollar sign ($). Also, all /os2200 names are maintained in lower case,
but may be referenced in upper, lower, or mixed case.
Element names need not conform to OS 2200 syntax rules. When needed, CIFS
creates a syntactically valid alias so the element can be accessed outside of CIFS.
A file reference in the /os2200 hierarchy cannot specify just a qualifier.
Either a qualifier and file name (for OS 2200 data files), or a qualifier, file name, and
element (for elements in OS 2200 program files) must be present in the absolute
reference or in the current working directory plus relative reference. However, a
directory reference in the /os2200 hierarchy can operate at any level above the element.
Links are allowed to target files or elements in the /os2200 directory hierarchy, but no
links can be created from the /os2200 directory hierarchy. For example,
/mydir/link-to-os2200-file can be a link pointing to /os2200/qual/file, but /os2200/qual/link
is not allowed.
Access permissions for elements are initially set to those of the containing program file.
CIFS utility commands and program interfaces can be used to make element
permissions different from those of the containing program file, but such changes are
not effective outside of CIFS (when accessed through traditional OS 2200 I/O interfaces).
Non-/OS2200 Directory Hierarchy
All directory names starting with a forward slash (/) and not /os2200 are in the
non-/os2200 directory hierarchy. Directories and files within this hierarchy can have
names up to 4095 bytes long. The value of each byte must be in the range 0x01 through
0xFF. Spaces, periods, quotation marks, parentheses, so on, as well as many unprintable
characters, are allowed. A forward slash has special meaning, in that it separates the
levels of the hierarchy. Using characters other than the normal ASCII printable set can
cause difficulty in some application or client programs.
Most files in the non-/os2200 directory hierarchy automatically appear in the /os2200
directory hierarchy, since CIFS files are normally stored as OS 2200 files and elements.
When a file is created in the non-/os2200 directory hierarchy, CIFS uses OS 2200 file and
element names consisting of the qualifier SYS$CIFS$, an internally generated file name,
and the requested name and extension as element and version, if possible. If the
specified file name is not a legal OS 2200 element name (it is too long or contains illegal
characters), CIFS generates a 12/12 alias for the OS 2200 element and version. The USE
command of CIFSUT is available to attach an OS 2200 internal name to a CIFS-generated
file name. This makes it easier for non-CIFS-aware 2200 programs to access
CIFS-created files.
Files in the /dev directory (there are only four) do not have aliases in the /os2200
hierarchy, nor are they accessible from the network. The /dev/tty file is used to represent
the terminal or symbiont streams associated with each run utilizing CIFS; read and write
requests to /dev/tty are automatically directed to the current READ$ and PRINT$ files or
devices of the requesting program. The /dev/null file is a “bit bucket”: read requests
always return zero byes; write requests always complete normally, but the data are
7859 6137–009 1–7

Introduction
Data Storage
discarded. The /dev/random and /dev/urandom files are a source of random bytes that
can be used for such purposes as modeling or cryptography. Note that /dev/random and
/dev/urandom can only be read from, not written to.
Files accessed through CIFS are normally stored as Standard Data Format (SDF)
elements in OS 2200 program files. The environment variable, CIFS$NEXTFILE, can be
used to force storage in a data file, if required. The SDF format is transparent to network
clients and programs using the CIFS APIs because on read operations, CIFS always
returns the exact byte sequences supplied on write requests. To facilitate data access by
programs using traditional OS 2200 I/O mechanisms, CIFS interprets various line
termination sequences as record breaks.
• A single line feed (0x0A) – the Linux/UNIX standard compatible with UCS Runtime
System I/O handling
• A carriage return line feed sequence (0x0D and 0x0A) – typically used by Windows
text files
• A single carriage return (0x0D) – the normal Apple Mac OS line terminator
Files using terminators other than a plain line feed can be filtered to make them
compatible with Linux/UNIX based programs by using the w-option of the CIFSUT cp and
copy commands. There is no limit on record length, though files are limited to
approximately 29 MB when stored as standard OS 2200 elements (34 GB in Large
Element Program Files (LEPF)).
CIFS always writes SDF files and elements using 9-bit or 18-bit characters, but is not
normally concerned with the character set being used in any particular file. Similarly,
CIFS normally passes back the input bytes from SDF data records directly to the caller.
However, for Fieldata files, CIFS converts the characters to ASCII before storing them in
the caller’s buffer; CIFS never writes Fieldata. Also, a user can specify translation to or
from UNICODE by setting appropriate attributes on a directory with the CIFSUT utility or
through a program interface.
CIFS determines the size of a System Data Format (SDF) file or element based on the
number of bytes contained in the data records, plus one or two (depending on the type
of line terminator) for each data record that is not continued. This determination occurs
the first time a file is read, and is remembered internally by CIFS thereafter. Note that a
file may be updated outside CIFS in such a way that the update is not readily detectable;
for example, rewriting an SDF data file without changing the number of tracks it
occupies. When this happens, the remembered size might not reflect the new size of
the file. You can use the truncate() program interface or the CIFSUT size command to
inform CIFS to recalculate the size when such an update is made.
CIFS recognizes the file name extensions .rel, .abs, and .omn as indicative of the
OS 2200 element types relocatable, executable, and omnibus, respectively. Files with
these extensions are handled with direct, rather than SDF, I/O operations. These special
extensions must follow one other period somewhere in the file name in order to be
interpreted as element types. For example, the name “program.abs” would be stored in
SDF format with the version “abs,” whereas ”program.ver.abs” would be treated as an
1–8 7859 6137–009

Introduction
OS 2200 executable with the name ‘program/ver”; ”program..abs” would refer to the
executable element ”program” (no version).
The additional element-specific information kept in a program file table of contents for a
relocatable or executable element is appended to the text of the element when read by
CIFS. Likewise, the caller must provide the same additional information on writes of
relocatable or executable elements, following the last byte of element text.
See the following table for the format of the appended data.
Type Bytes Contents
.rel 4
1
3
.abs 4
File Packing
1
1
1
1
Not used
Flags (least significant 9 bits)
Preamble length, broken into three 6-bit fields
Element table entry word 6
Flags (least significant 9 bits)
Sub-type
Sub-sub-type
ZOOM header offset
If the element Table of Contents (TOC) of the program file or the text area fills up while
writing a CIFS file stored as an element, CIFS attempts to automatically pack the
underlying OS 2200 program file. (This includes user-cataloged program files.) Packing
recovers unused TOC space and file text space taken up by deleted elements in the
program file. The action is directly analogous to a FURPUR @PACK. Any existing
relocatable and PROC entry point tables are preserved.
Note: The pack operation requires CIFS to have exclusive use (@ASG, AX) of the
program file while it is being packed. Therefore, the program file must not be assigned to
any run or name section or the pack cannot be done. This includes the run doing the
write that triggers the pack. If exclusive use is not obtained then the pack operation is
not performed.
The CIFS pack is a safe pack, even if the system goes down or an X-keyin to the run is
done during the pack; the contents of the program file are preserved, except in
extremely rare circumstances. If the program file’s TOC is actually full of active (not
deleted) elements and is about to overflow, the program file can also be converted
during the pack operation to a Large Program File (LPF). This program file has the
capacity to hold a maximum of 26,146 elements. A program file can also be packed by
use of the -p option of the CIFSUT touch command, or by calling the pack or CIFS$PACK
APIs. A CIFSUT “touch -pr directory-name” command packs all the underlying program
files of a whole directory tree.
7859 6137–009 1–9

Introduction
Security Considerations
CIFS uses standard OS 2200 security mechanisms, but extends them where necessary
to match standard POSIX usage. For example, CIFS maintains access controls for
elements, whereas standard OS 2200 does not.
CIFS grants access to a given file or directory based on a combination of the effective
user ID of the requester, access permissions, and file attributes. For owned files, the
effective user ID is the actual user ID of the requesting run. For unowned files, the
effective user ID is the project or account of the requesting run, determined by the Exec
configuration tag PRIBYACCNT. Any read or write keys needed to access an unowned
file must be specified by the CIFS$KEYS environment variable (see Section 4).
CIFS supports the following access permissions.
read Allows reading of the file data or directory contents
write Allows writing of the file data or updating of the directory, and deletion of
the file or directory
execute Allows the file data to be loaded for execution, but not necessarily read
(however, there is no mechanism for the Exec to utilize the CIFS capability
to open just for execute); allows a directory to be used in the reference to a
lower level directory or file
1–10 7859 6137–009

Communications Interface
Introduction
CIFS allows network access to its file system, and therefore to all OS 2200 files, by
means of Communications Application Program Interface and either CMS 1100 or
Communications Platform, or both. By default, CIFS uses only installation mode A of
Communications Application Program Interface; however, the site administrator can
select other or multiple installation modes by setting a value for the CIFS$COMAPI
environment variable. CIFS listens for connection requests on TCP ports 139 and 445 of
all communications interfaces configured in all specified Communications Application
Program Interface installation modes. File system connection requests are honored only
for previously established connection points, also known as shares. OS 2200 users can
create shares with the CIFSUT share command, or by means of the _cifs_share() API.
CIFS utilizes the Server Message Block (SMB) protocol, which has been used in
networking since the early 1980s. The protocol is widely used and has evolved to meet
the needs and demands of growing communication environments. Vendor support for
the full SMB specification (other than by Microsoft) is limited since much of the original
protocol is referred to as obsolete. These obsolete portions have been replaced by
alternate and more robust client/server SMB exchange definitions. Although the protocol
allows for device function control, pipes, print control, and mail slot access, the
implementation of SMB on OS 2200 is limited to data storage (disk share) access.
Applications running on Windows workstations have access to data maintained on
OS 2200 systems through standard Microsoft or Linux networking redirectors on the
workstation or server. These redirectors make network requests to known access points
on file servers, referred to as shares. The share names are maintained by CIFS as
reference names associated with a directory. By using a share reference, an SMB client
can access a point in the CIFS controlled data storage. Only authenticated access is
permitted; CIFS supports NT LAN Manager (NTLM), NTLMv2, and Kerberos
authentication. Data access privileges are the same as those the user has through
demand or batch access to the OS 2200 system.
Similarly, CIFS provides the means for OS 2200 programs to directly access files on any
remote host that implements an SMB server. Such remote hosts include OS 2200, MCP,
Windows (all versions), UNIX, Linux, z/OS, and so on. This SMB client capability, in many
cases, eliminates the need to transfer files between systems.
Normal network transmissions use only 8 bits out of each OS 2200 quarter word, which
is adequate for all character-based data. However, when relocatable or absolute
elements, or omnibus elements with an extension of .omn, are transmitted over a
network connection, CIFS uses a 6-bit format to ensure that all bits of such elements are
sent or received. Consequently, these binary elements appear 50 percent larger on the
network than they do on the OS 2200 host, and 50 percent more data is transferred on
the connection than on an internal file copy.
7859 6137–009 1–11

Introduction
TIP Considerations
Transaction processing (TIP) transactions do not normally use any file system other than
TIP File Control or Universal Data System (UDS). Using other file systems generally
involves more overhead than is acceptable for a transaction environment. Consequently,
not all CIFS capabilities can be used by TIP transactions. In particular, the Exec imposes
significant restrictions on the use of environment variables by TIP transactions, so any
CIFS operations that are dependent on environment variable settings results in the
default action being taken.
TIP transactions that access CIFS files must execute with a user ID that has access to
CIFS files. A TIP security user ID (TIP_SECURITY_USERID) must be configured on
systems that are not under TIP session control. All systems that execute Resident
Transaction Program System (RTPS) Java transactions must have a TIP security user ID
configured.
1–12 7859 6137–009

Section 2
Managing Files from the Workstation
This section provides information about how to access CIFS files from Windows and
provides examples of how the information is displayed in Windows and OS 2200
demand sessions. Refer to subsequent sections and the Glossary for definitions and
descriptions of CIFS utilities and commands.
To access CIFS files on an OS 2200 system from Windows, you must
• Have access to the OS 2200 system (provided by the system administrator).
• Create a share directory or have access to a previously created share directory.
• Map a drive to the share directory or access the resource with the Universal Naming
Convention (UNC).
Networking CIFS with Windows
NT4/2000/XP/2003/Vista and Windows 95/98/Me
When considering client configurations for connecting CIFS, be aware that both
Windows NT4/2000/XP/2003/Vista and Windows 95/98/Me provide network support for
the following:
• Client services for NetWare
• Remote networking
• TCP/IP, including PPP, SLIP, DHCP, and WINS
• NetBEUI Protocol
• NWLink IPX/SPX Compatible Transport
• Windows Sockets Standard used by popular Internet applications
• OSF, DCE, and RPC available for advanced client-server applications and used
extensively by Windows NT4/2000/XP/2003/Vista
• Peer-to-peer networking
• Internet connectivity
7859 6137–009 2–1

Managing Files from the Workstation
The networking implementation for Windows 95/98/Me is slightly different from that for
Windows NT4/2000/XP/2003/Vista. To support all Microsoft networking products that
use the server message block (SMB) protocol, the client for Microsoft networks
redirector (Vredir.vxd) is required. This allows Windows 95/98/Me computers to connect
to computers running any of the following networking software:
• Windows 95/98/Me
• Windows NT4/2000/XP/2003/Vista
• LAN Manager
• Workgroup Add-on for MS-DOS
As is apparent from the above description, there is a significant variability in established
Microsoft networks; however, if you can currently connect to other network resources,
you have the redirectors required to access CIFS.
Generally, Windows NT4/2000/XP/2003/Vista configurations need a host name with
domain name or direct IP address to identify a share name (for example,
\\rs99.rsvl.unisys.com\share_this or \\123.123.123.123 \share_that), whereas Windows
95/98/Me configurations need only a host name provided with the share name (for
example, \\rs99\share_this or \\123.123.123.123\share_that). However, if the host name
(for example, rs99) is configured in WINS, then Windows NT4/2000/XP/2003/Vista can
also use a host name with the share name (for example, \\rs99\share_this). Users of NT
4.0 service pack 5 have reported problems when using IP addresses. To avoid potential
problems, NT 4.0 service pack 4, 6a, or higher must be used.
Note: The above discussion assumes that share_this and share_that have been made
available for network access using @CIFSUT.
To prevent network connections from compromising the OS 2200 data access security
measures that were established prior to the introduction of CIFS, permission bits for
directories and files must be set to allow access, as well as OS 2200 access and
OS 2200 ownership, since these are strictly enforced. This can affect how and if your
data is shared with others.
Note: CIFS uses only TCP ports 139 and 445. That means that CIFS does not use WINS
or NetBEUI traffic to ports 137 and 138 in establishing or maintaining connections. CIFS
does not advertise to the network, nor does it request information from the network in
establishing and maintaining sessions with clients. The CIFS server does not belong to or
participate in any particular Microsoft domain concept, although it can connect with
established domains. When a domain name is required, a response of “?” is given, as
required by the protocol for any unknown domain.
How host names are resolved in the client computer is key to determining how CIFS
resources can be accessed. Client computers have control of how network names are
resolved. The necessary TCP/IP properties for DNS, LMHOSTS, and WINS can only be
determined by the local network administrator. If a network connection is not possible
using the above information, it may be necessary to change some client network
configurations to access CIFS resources. Remember, your current networking capability
depends on present settings and on your established network.
2–2 7859 6137–009

Managing Files from the Workstation
The Map Network Drive dialog box maintains a list of the most recently connected
shares. Once a connection is established, it can be easily reestablished by using the
pull-down selection menu to review previously used resources.
The following applies to all Microsoft client connections and applies also to CIFS network
resource connections.
Network Connections
In Windows NT4/2000/XP/2003/Vista, users can connect to any network resource they
have permission to access. If the current logon session is for a different account, users
can fill in their user name in the Connect As text box of the Map Network Drive
dialog box.
In Windows 95/98/Me, the Connect As dialog is not available. To connect to a network
resource from Windows 95/98/Me, users must log on to Windows 95/98/Me with a user
ID that has access to the specific network resource.
In either operating system, the net use command can also be used to map a network
drive. For syntax and usage, use the information available through the net help
command.
Persistent Connections
In Windows NT4/2000/XP/2003/Vista, persistent network connections are enabled by
default. To disable persistent connections, clear the Reconnect at Logon check box
in the Connect Network Drive dialog box.
In Windows 95/98/Me, Quick Logon is enabled by default. This network logon option
restores the mapping of drive letters to network resources without actually establishing
a session for each persistent network connection. If you want to establish sessions for
persistent connections during logon, enable Logon and Restore Network Connections.
For information on how to do so, refer to information provided by Microsoft (such as the
Windows 95 Resource Kit).
Creating a Share Directory
To create a share directory:
1. Start a demand session on the OS 2200 system.
2. Call the CIFS utility processor, @CIFSUT.
When you first execute this command, CIFS places you in the CIFS file structure at
your default working directory. Your default working directory is based on your
project ID. For example, if your project ID is MXM3, your default working directory is
/os2200/mxm3.
3. Use the mkdir (or md) command to create a directory. If you have already created a
directory, you can skip this step. (To view files and directories, use the ls or dir
command.)
7859 6137–009 2–3

Managing Files from the Workstation
4. Make the directory network-visible using the share command.
For example, to make the directory “investments” visible on the network as
“mxm3invest,” enter the command:
share investments mxm3invest
Refer to Section 4 and Section 5 for other share options.
Mapping a Drive to a Share Directory
To map a drive to a share directory from Windows
1. Start Windows Explorer.
2. From the Tools menu, select Map Network Drive.
3. Select the drive letter you want to use for the share directory.
4. Type in the path name to the share directory. You cannot browse for the directory.
The path name has the form \\OS-2200-hostname\sharename.
5. You need to provide a valid OS 2200 user ID that is known to CIFS in the Connect
As field or with the Connect using a different user name option if your site
does not have Network Authentication configured. See “Network Authentication” in
Section 9.
Notes:
• You will be prompted for your password if this is the first connection to the host.
• If you are using Windows 95/98/Me, your Windows user ID must match the
OS 2200 user ID provided by the system administrator. There is no Connect As field
for Windows 95/98/Me.
6. Click OK. The drive is mapped and appears in the list of drives in Explorer.
You can view the files in the share directory, double-click them, and drag and drop
them to and from the directory as you would any other files on your workstation.
2–4 7859 6137–009

Opening Share Files Using UNC
Managing Files from the Workstation
You can access CIFS files directly in most Windows applications, without mapping a
share directory to a drive, by providing the Universal Naming Convention (UNC) network
path, sharename, and file name to the application.
The following example illustrates this:
1. Start the application you want to call, for example, Notepad.
2. Type in the UNC network path, sharename, and file name in the File name field.
3. Click Open.
Note: When you click Open, a session is opened to OS 2200 to retrieve the file. You
might have to provide your user ID and password before the opening the document on
your workstation.
7859 6137–009 2–5

Managing Files from the Workstation
2–6 7859 6137–009

Viewing CIFS Directories
Managing Files from the Workstation
The following examples show how CIFS directories can be viewed.
This example illustrates how the share directory “CRCTEST” appears in Windows
Explorer (after mapping the share directory to drive F).
This example illustrates how the same directory ‘CRCTEST’ displays when issued from
an OS 2200 demand session using the @CIFSUT ls -lr command.
@cifsut
CIFSUT 1R1Q2 (1999/Aug/17 10:31:39) 1999 Oct 12 Tue 15:31:04
ls -lr /crctest
drwxrwxrwx 3 17 420 Sep 29 15:23 2nd level dir
-rwxrwxrwx 1 17 6836 Aug 17 10:25 TestingOne.txt
-rwxrwxrwx 1 17 394800 Aug 11 22:08 dumpdir..abs
/crctest/2nd level dir:
drwxrwxrwx 4 17 700 Sep 29 16:26 3rd level dir
/crctest/2nd level dir/3rd level dir:
drwxrwxrwx 3 17 420 Sep 29 16:25 4th level dir
-rwxrwxrwx 1 17 6836 Sep 29 16:23 Not So Long.txt
-rwxrwxrwx 1 17 6836 Sep 29 16:26 Testing Long Names in CIFS Directories.txt
/crctest/2nd level dir/3rd level dir/4th level dir:
-rwxrwxrwx 1 17 6836 Sep 29 16:25 Short Name.txt
7859 6137–009 2–7

Managing Files from the Workstation
This example illustrates how program files and data files might appear in Windows
Explorer for an OS 2200 project.
This example illustrates the same listing of the OS 2200 project files with the @CIFSUT
ls command:
@cifsut
CIFSUT 1R1Q2 (1999/Aug/17 10:31:39) 1999 Oct 12 Tue 15:34:29
ls /os2200/caldarale
$cshellsave$ code full$list pcf37-38 timetest
call-cull comus-cull gen randio timetesti
call-test cts$crc high$list rbcomp xfer
callt-cull dgt-call kernel$list save
cat$tpf$ dump-dir lf4r2 savestack$
cbpfl$crc ert-tools mfd-code testfile
2–8 7859 6137–009

Managing Files from the Workstation
This example illustrates a Windows Explorer view of OS 2200 program file contents,
including Word documents, 2200 executables, C source files, and new text documents
created with Windows by right-clicking the mouse.
7859 6137–009 2–9

Managing Files from the Workstation
This example illustrates how the program file contents would be listed with the FURPUR
@prt, tlb command.
@prt,tlb caldarale*xfer.
FURPUR 31R4Q1 (990309 1451:50) 1999 Oct 12 Tue 1605:30
SHARED#CALDARALE*XFER(1) ELEMENT TABLE
D NAME VERSION TYPE DATE TIME SEQ # SIZE-PRE,TEXT (CYCLE WORD) PSRMODE LOCATION
UNIXPROC-MD C ELT SYMB-Q 05 OCT 99 10:23:11 20 118 5 0 1 17526
TSCRDUMP ZOOM 18 AUG 99 15:23:27 19 1856 15670
NEWTEXTDOC-1 TXT SYMBOLIC 30 SEP 99 10:01:47 18 0 0 0 0 15670
NEWTEXTDOCUM TXT SYMBOLIC 30 SEP 99 08:56:30 17 0 0 0 0 15670
SQUEEZEPATH C ELT SYMB-Q 20 AUG 99 08:46:18 16 13 5 0 1 15657
DUMPDIR C SYMB-Q 11 AUG 99 22:07:57 15 58 5 0 1 15599
DUMPDIR ZOOM 11 AUG 99 22:08:12 14 3525 12074
CIFS-FS RTF ELT SYMB-Q 21 JUL 99 10:03:24 13 1374 5 0 1 10700
CIFS-FS DOC DOC SYMB 19 JUL 99 16:58:39 12 1158 0 0 0 9542
HVTIP$CALLS MSD SYMB-Q 03 MAY 96 14:50:25 11 397 5 0 1 9145
CIFSIO H C SYMB-Q 09 FEB 99 13:21:04 10 306 5 0 1 8839
LSTEST C SYMB-Q 12 FEB 99 10:52:16 9 14 5 0 1 8825
PCNSVRBUF TXT SYMBOLIC -Q 04 FEB 99 17:10:41 8 36 5 0 1 8789
EM-TCF ELT SYMB-Q 16 APR 98 15:01:30 7 1776 5 0 1 7013
EM-PCF NEW ELT SYMB-Q 16 APR 98 15:01:08 6 1789 5 0 1 5224
EM-PCF ORIG ELT SYMB-Q 16 APR 98 15:00:19 5 1439 5 0 1 3785
MAPELTS ELT SYMB-Q 16 APR 98 13:58:54 4 9 5 0 1 3776
ELTLIST ELT SYMB-Q 15 APR 98 16:59:09 3 21 5 0 1 3755
UAL-UCS PCF ELT SYMB-Q 16 MAR 98 14:42:43 2 1724 5 0 1 2031
UAL-EM PCF ELT SYMB-Q 13 NOV 97 15:25:12 1 239 5 0 1 1792
NEXT AVAILABLE LOCATION- 17644
2–10 7859 6137–009

Section 3
File Concepts
This section includes the following topics:
• Definitions and descriptions pertaining to files, file names, and directories
File hierarchies
• Path names and path name resolution
• Open file descriptions
• File descriptors and file permissions
• Time information for files and directories
• Concepts of file management and file input/output (I/O) operations
• Environment variables
File Definition and File Types
A file is a logical data container. CIFS supports directories, regular files, character files,
pipes, and First-In First-Out (FIFO) files. Each of these file types is described below.
Internally, CIFS uses an inode structure to manage each file in the system. An inode
contains a file’s serial number, type, ownership, access permissions, size, OS 2200 alias,
and creation, modification, and access times, among other information. The ls and dir
commands (described in Section 4) or the stat() and istat() functions (Section 5) retrieve
information about a file from its inode.
A directory is a very specialized kind of file that contains links to other files (including
directories). Directories are used to organize files into hierarchical structures. More
detailed information about directories appears in the following subsections.
A regular file is a randomly accessible sequence of bytes with no further structure
imposed by CIFS. All OS 2200 files are accessible through CIFS interfaces. Likewise, all
regular CIFS files are accessible through traditional OS 2200 mechanisms.
A character file is a virtual file that is used as a caller's terminal (or batch read/print
streams), or as a dummy file, or as a source of random data. Only four character files
exist: /dev/tty (terminal access), /dev/null (dummy file), /dev/random and /dev/urandom
(random byte streams). CIFS directs read and write requests for /dev/tty to the
requester's READ$ and PRINT$ streams.
7859 6137–009 3–1

File Concepts
File Names
Read requests for /dev/null always return zero bytes, while write requests always appear
to transfer all data (although the bytes are actually discarded). Reads from /dev/random
and /dev/urandom return a random byte sequence; writes are not allowed. Character
files are not accessible from the network.
A pipe allows processes to transfer data and synchronize execution. A pipe has the
following characteristics:
• A pipe provides a data stream between two processes.
• Pipe data is read in the same order in which it is written; that is, in FIFO sequence.
• A pipe is temporary; it vanishes when closed by all processes using it.
• A pipe does not have a name and therefore, is not part of the file hierarchy.
This diagram illustrates a pipe:
A FIFO file is a pipe that has a name and permanently resides in the file hierarchy.
A file name identifies a named file. All CIFS files other than pipes are associated with at
least one file name. The following rules apply to file names:
• A file name can consist of 1 to 4095 characters, plus a terminating nul character.
• A file name can contain any characters except the following:
− Slash (/)
− Nul character ('\0')
− Any character with a value greater than 8 bits (>255)
− All periods
Process A
write ( )
The slash and nul characters do not cause errors. They are used to delimit path name
components and, therefore, cannot be part of any file name. See examples below.
• Although CIFS allows nearly all characters in file names, many nonalphanumeric
characters have special meaning to some applications or can cause erratic displays
when sent to a terminal. Consequently, nonprinting characters should be avoided.
These characters include the ranges 1 through 31 and 127 through 255.
3–2 7859 6137–009
Data
Process B
read ( )

File Concepts
Generally, file names with such characters cannot be safely displayed without
special handling in the output medium. Also, file names beginning or ending with
spaces tend to be confusing.
Examples
The following are valid file names:
p
program_name
15digits_first
doc.22
policy,12:b
1234560
thisnameisnottoolongthisnameisnottoolongthisnameisnottool
For the reasons given above, the following are either invalid or not the intended file
name:
my/name
Contains a slash. (CIFS interprets “name” as the file name and “my” as a directory
name.)
my\0name
Contains a nul character. (CIFS interprets “my” as the file name and ignores
“name.”)
7859 6137–009 3–3

File Concepts
Directory Definition and Rules for Directories
A directory is a file that contains directory entries. A directory entry, or link, is an object
that associates a file name with a named file; pipes do not have directory entries.
(Directory entry and link are synonymous terms.) A subordinate directory is a directory
whose name is an entry in another directory. A file’s link count is the total number of
directory entries associated with that file.
The following diagram shows the directory main_dir containing regular files (represented
by cylinders) and subordinate directories (represented by circles):
The contents of main_dir are represented by the following list of file names. This list is
also an example of a directory stream.
48.1234
minutes.mtg
myfile.1
myfile.2
outlines
tempjunk
See below for a detailed description of file hierarchies.
Rules for Creating Directory Entries
The following rules apply to creating entries in directories:
• Each file name must be unique within a directory. However, the same file name can
appear in different directories and can be associated with different files.
• The same file can be associated with several different file names through multiple
links. These links can be in the same directory or in different directories.
3–4 7859 6137–009

File Concepts
For examples of creating and removing links, see the link() and unlink() functions in
Section 5.
Diagram of Directories, Files, and Links
The following diagram illustrates how links associate file names with files:
In the diagram, the following path names refer to the same file:
• A/Entry_A3
• A/Sub_A/Entry_SA1
• B/Entry_B2
• B/Entry_B3
Because four links exist for this file, its link count is 4.
7859 6137–009 3–5

File Concepts
File Hierarchies
The file hierarchy is a relationship among all CIFS files. The hierarchy is an inverted
tree-like structure with branches from the system root directory to each named file in the
system. The system root directory is the top of the file hierarchy. All other directories
branch from it. A node is any file on any branch of the file hierarchy.
The following diagram illustrates the structure of the file hierarchy:
Characteristics of a file hierarchy include these:
• The last node on a branch can be a file of any type except a pipe (since pipes are not
part of the file hierarchy).
• All nodes that are not the last nodes on a branch are directories.
• The top of the hierarchy is the system root directory.
3–6 7859 6137–009

Path Names
File Concepts
A path name identifies a file; it is the ordered list of file names that locates a file. A path
name component is a file name in the list.
The following rules apply to path names:
• A path name consists of one of the following combinations:
− One or more file names, separated by slash characters
− An initial slash (/) followed by zero or more file names, separated by slashes
• Each path name component except the last must name a directory.
• The last path name component can name any kind of file other than a pipe, including
a directory.
• If the path name refers to a directory, it can optionally end in one or more trailing
slashes.
• Multiple successive slashes are the same as one slash, except at the beginning of a
path.
• A null path name (that is, “”, the empty string) is invalid.
Examples
The following examples are valid path names:
file1
dir1/dir2/file1
/main_dir/appl_dir/pgm_dir/file1
/
dir_1////sub_dir/
Assuming “dir” means a directory name and “file” means a regular file name, the
following examples are not the intended path names, for the reasons given:
dir1/dir2/file1/file2
Third component is not a directory.
dir_1dir_sub
Components are not separated by a slash. CIFS interprets this as a single file name
rather than a directory and a subdirectory.
7859 6137–009 3–7

File Concepts
Special Path Name Components
The current working directory is used to resolve relative path names for a process. Its
value is either
• The result of the last call to chdir(), if one occurred.
• The initial directory of the first process for the user if chdir() has not been called.
A parent directory of any file is a directory that contains a link to that file.
Notes:
• A file can have multiple parent directories because more than one directory can
contain a link to the file. See the link() function in Section 5 for more information.
• A directory can have one parent directory in the /os2200 hierarchy and one in the
non-/os2200 hierarchy.
A child of a directory is one of the files listed in the directory. Dot (.) is a file name that
refers to the directory itself. Dot-dot (..) is a file name that refers to the parent of the
directory.
Notes:
• Both . and .. count as directory entries.
• A component consisting solely of one or more dots is valid in path names. One dot
refers to the current directory, two dots refers to the parent directory, three dots
refers to the parent’s parent directory, and so on. For example, /a/b/../c/. resolves to
/a/c.
• With respect to the system root directory, both . and .. refer to the system root
directory itself.
3–8 7859 6137–009

Path Name Resolution
File Concepts
The process of finding a file from a given path name is called path name resolution. Path
name components are interpreted from left to right according to one of two procedures,
as determined by the following decision table:
If the first character of the path
name is ...
Then use ...
A slash (/) Absolute path name resolution
Not a slash Relative path name resolution
In both procedures, each path name component is located in the directory specified by
the preceding path name component.
Absolute Path Name Resolution
Absolute path name resolution starts from the system root directory. It consists of the
following steps:
1. If the path name consists of a single slash, it resolves to the system root directory.
2. Read the next file name, moving from left to right.
3. Associate this file name with a file (possibly a directory) on the next level of the
hierarchy.
4. Repeat steps 2 and 3 for each path name component.
Example
In the path name /main_dir/appl_dir/pgm_dir/file_1
• Directory main_dir is located in the system root directory.
• Directory appl_dir is located in directory main_dir.
• Directory pgm_dir is located in directory appl_dir.
• Regular file file_1 is located in directory pgm_dir.
7859 6137–009 3–9

File Concepts
Path Name Component Parent of Child of
main_dir appl_dir System root directory
appl_dir pgm_dir main_dir
pgm_dir file_1 appl_dir
file_1 pgm_dir
Relative Path Name Resolution
Relative path name resolution starts from the current working directory of the process. It
consists of the following steps:
1. Read the next file name, moving from left to right.
2. Associate this file name with a file (possibly a directory) on the next level of the
hierarchy.
3. Repeat steps 1 and 2 for each path name component.
For example, in the path name
dir_1/dir_2/file_1
Directory dir_1 is located in the current working directory. Directory dir_2 is located in
directory dir_1. Regular file file_1 is located in directory dir_2.
3–10 7859 6137–009

Path Name Component Parent of Child of
dir_1 dir_2 Current working directory
dir_2 file_1 dir_1
file_1 dir_2
Open File Descriptions
File Concepts
An open file description is a CIFS record of how a process is accessing a file. Many CIFS
functions access files only indirectly, through open file descriptions. An open file
description corresponds to one and only one instance of an open file. Each file open()
request creates a new open file description. An open file description has the following
attributes:
• Read/write offset
• File status flags
• File access specification
The values of the preceding attributes in each open file description are independent of
the values in other open file descriptions, even for the same file.
Read/Write Offset
The read/write offset is the byte position in a file where the next I/O operation starts.
The offset is not meaningful for character files, pipes, or FIFO files.
File Status Flags
The file status flags specify how the file was opened, such as opened to append data.
Each of the following functions sets the file status flags (see Section 5 for information on
the functions):
• The open() function
• The fcntl() function with the F_SETFL command specified
7859 6137–009 3–11

File Concepts
File Access Specification
The file access specification identifies the type of permission requested by a process for
accessing a file: read-only, write-only, or read/write access. The file access specification
is one of the following values, specified with the open() function (see Section 5):
• O_RDONLY Open the file for reading only.
• O_WRONLY Open the file for writing only.
• O_RDWR Open the file for reading and writing.
Using Open File Descriptions
A process accesses an open file description through a file descriptor (see below), which
CIFS creates when the process opens a file. A process can create several open file
descriptions that all refer to the same file, where each open file description
• Is created by a call to open() or creat()
• Is identified by a file descriptor
• Operates independently of all other open file descriptions
For example, an application may need to read, write, and update a file at three distinct
locations within the file. The application can open the file once for read-only access, once
for write-only access, and once for read/write access. The resulting open file descriptions
for the three instances of the open file are independent and have unique offsets,
allowing the application to access the file in the appropriate way at each location.
The following diagram shows a process accessing a single file through several
independent open file descriptions:
Process
CIFS Subsystem
File
Descriptors
Open File
Descriptions
3–12 7859 6137–009
File

File Descriptors
Restrictions
File Concepts
A file descriptor is a nonnegative integer that identifies an open file description for file
access. Standard input is an input stream usually intended to be used for primary data
input. By convention, the C name for standard input is stdin and the file descriptor is 0,
which you access using the constant STDIN_FILENO. Standard output is an output
stream usually intended to be used for primary data output. By convention, the C name
for standard output is stdout and the file descriptor is 1, which you access using the
constant STDOUT_FILENO. Standard error is an output stream usually intended to be
used for diagnostic messages. By convention, the C name for standard error is stderr
and the file descriptor is 2, which you access using the constant STDERR_FILENO.
A file descriptor allows CIFS to find the open file description that corresponds to an
instance of the open file. The following functions can return file descriptors for use in
other system calls (see Section 5 for function descriptions):
• creat() function
• dup() function
• dup2() function
• fcntl() with the F_DUPFD command request
• open() function
• pipe() function
The following restrictions apply to file descriptors:
• A process can have up to 2048 file descriptors.
• Each file descriptor refers to only one open file description. However, one open file
description can have more than one file descriptor referring to it; see “Using File
Descriptors” in this subsection.
Using File Descriptors
Any call to open() creates a new open file description and assigns the lowest available
file descriptor. The process can later associate additional file descriptors with this open
file description.
For example, you might want to use standard input STDIN_FILENO and standard output
STDOUT_FILENO for passing data between processes that access a pipe. You can
redirect STDIN_FILENO and STDOUT_FILENO to the pipe by duplicating the appropriate
file descriptors; see the example for the pipe() function in Section 5.
7859 6137–009 3–13

File Concepts
The following functions can associate more than one file descriptor with an open file
description:
• dup()
• dup2()
• fcntl()
The following diagram shows a process accessing a file through a single open file
description associated with several file descriptors:
File Permissions
CIFS Subsystem
File
Descriptors
Open File
Description
Process File
File permissions are attributes of a file that determine whether a process can read,
write, or search/execute the file or change the file's characteristics. There are three
types of file permissions:
• Read permission allows the process to obtain the contents of a file (including a
directory).
• Write permission allows the process to create entries in a directory or modify the
contents of other types of files.
• Search/execute permission allows a process to search a directory or execute a file.
Search permission applies only to directories; execute permission applies only to
regular files.
Permissions are determined by OS 2200 security policies, and augmented by
CIFS-maintained permission bits.
CIFS maintains separate access permission sets for references by three classes of
requesters: file owner, group, and others. The owner set is used when the effective user
ID matches the effective owner of the file; the other set is used for all mismatches.
(Currently, named groups are not implemented in OS 2200 CIFS. Therefore, group
access permissions have no effect. CIFS keeps track of group access permission
settings but does not use them to grant or deny access.) The file attributes supported by
CIFS are read-only and write-only (they cannot be set concurrently).
3–14 7859 6137–009

File Concepts
These attributes only restrict any access granted by the permissions. CIFS honors
settings established by other mechanisms (for example, @CHG,V) and changes any
underlying OS 2200 file state to match when all read or write permissions are removed.
At sites where access control records (ACRs) are in use, CIFS maintains permissions for
a file or directory based on any ACR attached to the underlying OS 2200 file. An ACR can
be attached to new files by setting the CIFS$ACR environment variable (see Section 4)
prior to invoking a CIFS file creation mechanism. The CIFS$ACR setting is also applied to
existing files when ownership is changed through the chown command in CIFSUT or the
chown( ) API. ACRs must be used to insure that access permissions set inside CIFS are
effective when files are referenced by native OS 2200 mechanisms.
CIFS sets the initial access permission values for files in the /os2200 directory hierarchy
based on the security state of each file. For private files, the effective owner is given full
access while group and other access is set to none. For public files, full access is given
to all classes. When a file has an ACR attached, access is based on the contents of the
ACR.
Permission Bits
The permission bits set in the CIFS environment are used only as additional restrictions
on the access rights granted by the Exec through public, private, ACR, and key settings.
CIFS never gives more I/O access than the Exec allows, unless the user is considered
privileged. For CIFS, privileged means having write access to the CIFS subsystem
program file (ignoring any read-only attribute). Drive mapping does not involve any actual
I/O, so CIFS only uses the permission bits to decide whether or not the connection must
be allowed. This is analogous to doing a cd in @CIFSUT, which is also based solely on
the permission bits, and can be performed without regard to the Exec access checks.
After the connection or the cd, however, the “unprivileged” user must still go through
the Exec checks to actually look inside a file.
7859 6137–009 3–15

File Concepts
Permission Masks
Each permission class has a permission mask attribute that controls the types of
permissions for that class. The following diagram shows the concept of read (r), write
(w), and search/execute (x) permission within the permission mask for each class:
If all bits are set in a permission mask for a file, each class can read, write, and
search/execute the file; no permissions are denied.
The default permission bits for new files and directories are shown in the following table.
Permissions that are not allowed are shown as a dash (–).
Method of Creating a New File
or Directory
Default Permission Bits
COPY or MOVE command Same bits as those for source file or directory
MKDIR command rwxrwxrwx (full access for owner, group, and
other users)
Creation through network
connections
rwxr–xr–x (full access for owner, but only read
and execute access for group and other users)
CIFS APIs Caller-specified bits in the mode parameter
(required for new files)
Examples
The following table shows some common permission assignments for each class.
Permissions that are not allowed are shown as a dash (–).
If the file
permission bits
are...
Then the process has permission to...
Owner Group Other
rw-rw-rw- Read and write Read and write Read and write
rw-r-r- Read and write Read only Read only
rwxr-r- Read, write, and
execute
rwxr-xr- Read, write, and
execute
r w x r w x r w x
Owner Group Other
Read only Read only
Read and execute Read only
3–16 7859 6137–009

Using File Permissions
File Concepts
Each time a process tries to open a file or modify its characteristics, CIFS takes the
following actions:
1. Determines the class of the process with regard to the file.
2. Uses the appropriate mask (set of permission bits) to determine which permissions
the process has for the file.
3. Compares the permitted permissions to the permissions requested by the process
(that is, the file access specification).
4. Continues or terminates the process request, depending on the result of the
comparison.
Time Information for Files
The directory entry for a file contains time information in addition to file ownership,
permissions, and type. The following time information for a file is maintained and
available to appropriate functions:
Field Description
Last read or
write access
Last
modification
(write access)
Time of
creation
Updating Time Fields
The time of the last read or write
access to the data in the file.
The time of the last modification
(write access) to the data in the
file.
Field in
struct stat
Examples of
Functions
st_atime read() readdir()
st_mtime mkdir() write()
The time the file was created. st_ctime creat()
Each function that references file data or changes the file's characteristics updates the
appropriate time field.
When a file is no longer open by any process (that is, the last open file description for a
file is closed) the last access time is updated.
The functions fstat() and stat() do not update any time information for the selected file.
Time Information for Open File Descriptions
Time information, along with the file mode and other status information, belongs to a
file. All open file descriptions for the file share that information.
7859 6137–009 3–17

File Concepts
File Attributes
CIFS maintains certain information about each named file in the file system, including
• File mode, including file permissions
• Security attributes
− Owner's user ID
− Owner’s numeric user ID
− Privacy Setting
• Identifiers
File Mode
− File serial number
• Size in bytes
• Number of links to the file or directory
• Time information (see above)
− Last access to file data
− Time of file creation
− Last data modification
• OS 2200 file container name (an empty string if container is not allocated)
The file mode contains information about the following attributes:
• File permissions, which control file access.
• File format, which identifies System Data Format (SDF) and binary files.
• File type, which identifies regular, directory, character, pipe, and FIFO files.
Each of these attributes is described in the following subsections.
3–18 7859 6137–009

File Mode Creation Mask
File Concepts
The file mode creation mask is a process attribute that limits the permissions the
process can attach to a file. The value of the mask is controlled by the umask() function
(see Section 5). The mask is a set of attributes corresponding to read, write, and
search/execute permissions for each of the permission classes (owner, group, and other;
see above). If an attribute is set in the mask, that permission is denied when files are
created. For example, to prohibit anyone in the group and other permission classes from
writing to a file, set the corresponding attributes in the file mode creation mask before
creating the file.
Functions that create files request file permissions through a mode argument in the call
statement. However, they first apply the file mode creation mask to turn off
corresponding permissions that are set in the mode argument. For example, if the
attributes for group and other write permissions are set in the file mode creation mask,
those permissions are not set for files created subsequently.
Note: To apply the file mode creation mask, functions perform a bitwise AND operation
between the value of mode and the complement of the file mode creation mask.
Inheriting the File Mode Creation Mask
New processes created by the _cifs_new_process() function inherit the file mode
creation mask of the previous process.
Using the File Mode
The fstat() and stat() functions make the file mode available in a numeric field.
The chmod() function references the file mode through a mode argument, using mode to
modify the permissions in the file mode. The following functions reference the file mode
through a mode argument, using the file mode creation mask to modify the permissions
in mode:
• creat()
• mkdir()
• mkfifo()
• open()
See Section 5 for function descriptions.
File Permissions
File permissions control read, write, and search/execute access to the file (see above for
a description of permission classes and illustrations of common permission attribute
settings).
7859 6137–009 3–19

File Concepts
The following table identifies symbolic names for permissions for each permission class:
Permission Class
Symbolic Names for Permissions
Read Write Search/Execute
Owner S_IRUSR S_IWUSR S_IXUSR
Group S_IRGRP S_IWGRP S_IXGRP
Other S_IROTH S_IWOTH S_IXOTH
To set permissions for a regular file, for example, you can create the file with the open()
function. The mode argument in the call includes all the individual permissions you want
the file to have, separated by the bitwise inclusive OR operator (|). For example, the
following mode argument sets read, write, and execute permissions for the user:
S_IRUSR | S_IWUSR | S_IXUSR
Note: The search/execute permission attributes (S_IXUSR, S_IXGRP, and S_IXOTH)
have dual meaning. They signify search permission for directories and execute
permission for regular files. They have no meaning for any other type of file.
Example
Suppose you want to create a regular file that anyone can read. You assign all
permissions for yourself as owner, and you allow read permission for the group and
other classes. The following example illustrates these permissions.
rwxr--r--
The following code sets the correct permissions when open() creates the file:
open("/main_dir/my_dir/my_file", O_CREAT | O_RDWR,
S_IRUSR | S_IWUSR | S_IXUSR | S_IRGRP | S_IROTH)
Class Permission Values
The following values assign read, write, and search/execute permission for a class. Use
them instead of the individual permissions if you want all three permissions for a class:
• S_IRWXU—Set rwx for the owner class
S_IRWXU is the read, write, and search/execute permission value for the file's
owner class. It means that S_IRUSR, S_IWUSR, and S_IXUSR are all in effect.
• S_IRWXG—Set rwx for the group class
S_IRWXG is the read, write, and search/execute permission value for the file's group
class. It means that S_IRGRP, S_IWGRP, and S_IXGRP are all in effect.
3–20 7859 6137–009

• S_IRWXO—Set rwx for the other class
File Concepts
S_IRWXO is the read, write, and search/execute permission value for the file's other
class. It means that S_IROTH, S_IWOTH, and S_IXOTH are all in effect.
Example
File Format
Binary Format
You can use the owner class permission value to code the previous example, as follows:
open("/main_dir/my_dir/my_file", O_CREAT | O_RDWR,
S_IRWXU | S_IRGRP | S_IROTH)
The file mode contains information about the data format of files, which can be either
• Binary format—The S_1100BIN attribute is set in the file mode.
• System data format (SDF)—The S_1100SDF attribute is set in the file mode.
The format is important for files used with other OS 2200 software. Choose the format
that is appropriate for the file’s purpose.
If S_1100BIN is set, the file is an OS 2200 binary file. CIFS performs read and write
operations to the file without special formatting.
System Data Format
Restrictions
File Type
If S_1100SDF is set, the file is an OS 2200 system data format (SDF) file. CIFS uses
special SDF formatting to perform read and write operations to the file.
The following restrictions apply to the file format attributes:
• A file can have at most one of the S_1100BIN and S_1100SDF attributes. An open()
request fails when it tries to set both of them.
• When S_1100BIN is not set, the file defaults to S_1100SDF.
• Format cannot be changed once the file is created.
The file mode contains information about the file type, which identifies the file as a
directory, a character file, a pipe or First-In-First-Out (FIFO) file, or a regular file.
7859 6137–009 3–21

File Concepts
Testing for File Type
The macros in the following table test for the file type. Each macro returns one of the
following values:
• Nonzero, if the test is true
• Zero if the test is false
Macro Name File Type Determined by the Macro
S_ISNET(m) Network file
S_ISDIR(m) Directory
S_ISCHR(m) Character (terminal, null, or random) file
S_ISBLK(m) Block-oriented file (always FALSE for CIFS)
S_ISREG(m) Regular file
S_ISFIFO(m) Pipe or FIFO file
S_ISELT(m) An element
S_IS_1100(m) 2200 format (SDF or binary)
S_ISBINELT(m) Binary element (relocatable, absolute, omnibus)
S_ISSDFELT(m) SDF element
S_ISUNKN(m) Type not yet known
S_ISDIRECT(m) File mapped directly to an OS 2200 file or element
S_ISSDF(m) SDF format
S_ISBINARY(m) Binary format
m is the st_mode field obtained through stat() or fstat().
CIFS does not implement block special files. Therefore, the S_ISBLK(m) test is always
false.
3–22 7859 6137–009

Related Functions
File Concepts
The following table identifies the tasks involved in managing files and the functions that
perform them. See Section 5 for detailed information about each function.
Topic Task Function
Opening and
closing files
and links
Open a file, optionally creating the file if it does not
exist.
open(),
fopen(),
freopen()
Create and open a new file. creat()
Close a file, deallocating its file descriptor. close(),
fclose()
Create a link (new directory entry) to a file. link()
Remove a link from a file, possibly deleting the file. unlink(),
remove()
Accessing files Determine if a process has permission to access a
file or if the file exists.
access()
Change the file permissions in the file mode. chmod()
Change the security attributes of a file. chown()
Directories Determine the current working directory. getcwd()
Change the current working directory. chdir()
Create a new directory. mkdir()
Remove (delete) a directory. rmdir()
File information Change the path name of a file or directory. rename()
Determine information about a file. fstat(), stat()
Change access or modification time of a file or
directory.
utime()
FIFO files Create a new First-In-First-Out (FIFO) file. mkfifo()
7859 6137–009 3–23

File Concepts
File I/O Operations
This subsection describes reading and writing files and using directory entries and
streams, along with additional concepts related to I/O operations.
Reading and Writing to Files
Before reading or writing data to CIFS files other than directories, read and write
operations require a file descriptor, which is made available when a process does one of
the following:
• Opens the file by calling the open() or creat() function, establishing an open file
description with a corresponding file descriptor.
• Inherits a file descriptor for an open file description from its parent process.
A process can open a directory for reading (and read it) but not for writing.
File Access by Multiple Processes
An OS 2200 program can assign a file exclusively before writing to it. CIFS has no
feature corresponding to exclusive assignment. Therefore, you cannot prevent another
process from writing to a file that is being used if the process has write permission for
the file.
As an alternative, CIFS provides advisory record locks, which allow cooperating
processes to coordinate access to part or all of a file. Advisory record locks do not
prevent other processes with permission from writing to the file; any process can still
read from or write to any portion of a file for which advisory record locks exist.
But cooperating processes can check whether advisory locks exist and avoid writing to
that segment until the lock is released. See below for an explanation of how advisory
record locks work.
Exclusive assignment of a file by any entity in the system prevents CIFS from accessing
the file. This is true even if the file is exclusively assigned to the run making the CIFS
request.
Making Sure Your Data Is Written to Disk
The CIFS subsystem uses a buffering system in volatile storage for file data. Buffering
increases the speed of input and output (I/O) operations, but it also increases the risk of
lost data. CIFS provides the following mechanisms for securing data to disk storage (see
Section 5 for details of how each mechanism works):
• The O_DSYNC and O_SYNC flags for the open() function.
• The fdatasync() and fsync() functions for individual files.
3–24 7859 6137–009

Directory Entries and Streams
File Concepts
A directory entry is a file name or a subdirectory name within a directory (see above). A
directory stream is a sequence of all the directory entries in a particular directory.
Using Directory Streams
Loosely, a directory stream is the list of names found in a particular directory. You might
want to print a directory stream to have a record of the directory's contents or you might
want to archive the file associated with each entry in the directory stream. The following
functions process a directory stream:
• The opendir() function opens the directory stream.
• The closedir() function closes the directory stream.
• The readdir() function reads the next entry in the directory stream.
• The rewinddir() function repositions the directory stream to its beginning.
Information on Directory Streams
For each open directory stream, CIFS maintains a list of file names in the directory and
their corresponding file serial numbers; for each named file in a file system, the serial
number is unique.
Data Translation
Automatic translation of data to and from Unicode may be enabled for SDF files stored in
designated directories. For example, a directory can be set up to translate LETS-J data to
Unicode when written to a file in the directory, and Unicode to Shift-JIS when read.
The following character sets are supported:
• UNICODE
• Shift-JIS
• LETS-J
• JIS-X0201 (Katakana)
• JIS-X0208 (Kanji)
• JIS-X0212 (supplemental Kanji)
• ISO8859-n (Latin variants 1 through 10 and 13 through 15)
Use the CIFSUT xlate command (see Section 4) or the _cifs_xlate() API (Section 5) to
establish translation modes for a directory.
7859 6137–009 3–25

File Concepts
Since a file can appear in more than one directory (using the CIFSUT ln command or the
link() API) (Section 5), a given file can be read in multiple formats once it is written in
Unicode.
Advisory Record Locks
The advisory record locking mechanism provides a way for cooperating processes to
coordinate the way they use a file. Cooperating processes can synchronize their behavior
to avoid conflicting input and output (I/O) operations to the file.
However, advisory record locks do not deny I/O access to a file. Any process with
proper permissions can read from or write to the file regardless of the existence of
advisory record locks.
Processes use the fcntl() function to set, release, and check for advisory record locks.
See Section 5 for a detailed description of the fcntl() function and its services. The
following paragraphs provide a general description of how advisory record locks work.
An advisory record lock is a mechanism by which a process alerts other cooperating
processes of its I/O activity on some portion of a file. An exclusive advisory record lock
prevents other processes from creating advisory record locks on that byte range. A
process generally uses an exclusive lock when updating a file. A shared advisory record
lock prevents other processes from creating exclusive advisory record locks on that byte
range. A shared lock allows other shared locks, however. A process generally uses a
shared lock when reading a file. Cooperating processes use the fcntl() function to
request advisory locks for coordinating read and write operations on a file.
Noncooperating processes do not use fcntl() or try to coordinate file access. They receive
no information about advisory locks that exist for a file.
CIFS manages all advisory record locks set on a file. The list of locks is independent of
other file attributes. When one process sets an advisory record lock on a portion of an
open file and another process requests a lock on some or all of those bytes, CIFS takes
one of the following actions, depending on the locking service specified in the call to
fcntl():
• Suspends the calling process until it can grant the lock request without conflict
• Returns an error status to advise the calling process that a conflict exists
The Status of Advisory Record Locks on a File
For each byte in an open file, one of the following is true:
• The byte is unlocked (no advisory record lock exists).
• An exclusive advisory record lock exists.
• One or more shared advisory record locks exist.
3–26 7859 6137–009

The following diagram shows some bytes in an open file and their lock status
(U=unlocked, E=exclusive lock, S=shared lock):
E S S S U U U U U U E E E U U S S S S U U U U U
1 2 3 4 5 6 7 8 9 10
Characteristics of Locks
Locks have the following characteristics:
File Concepts
• Locks can exist beyond the end of a file but cannot start before the beginning of a
file.
• If the requested lock length is 0, the fcntl() function extends the lock to the largest
possible read/write offset.
• Locks are associated with the file itself and not with the file descriptor or open file
description.
• Locks are not inherited by a child process.
Shared and Exclusive Locks
Existing shared locks owned by other processes allow the calling process to create a
shared lock on any portion of the locked segment, but they deny requests for exclusive
locks. Processes generally use shared locks when reading a file to avoid having other
processes change the file's contents during the read operation.
Existing exclusive locks deny all requests for shared or exclusive locks. Processes
generally use exclusive locks when updating a file to avoid having other processes read
or change the file's contents during the update operation.
Lock Request Versus File Access Specification
The lock request fails when it conflicts with the file access specification, as in the
following cases:
• A process requests a shared lock when the file is not open with read access.
• A process requests an exclusive lock when the file is not open with write access.
Locking and Unlocking Whole Files
A process locks or unlocks an entire file if it specifies a lock of zero length and zero
offset from the beginning of a file.
7859 6137–009 3–27

File Concepts
Removing Locks
CIFS removes all file locks owned by a given process when the process
• Closes any file descriptor for that file, whether or not the lock was created through
that file descriptor
• Terminates
A process can remove a lock with the fcntl() function.
Replacing and Merging Locks
Deadlocks
When a process successfully places a lock on a portion of a file that is adjacent to a lock
of the same type that the process owns, CIFS merges the locks. For example, suppose a
process owns shared locks on bytes 0 through 5 and bytes 7 through 9 in a file. The
process requests a shared lock on byte 6 (or on a range including byte 6). The result is a
single shared lock on bytes 0 through 9.
A deadlock occurs when two or more processes try to access the same file in conflicting
or restricted ways, resulting in one or more processes being suspended indefinitely.
Deadlocks from Advisory Record Locks
Deadlocks can occur as a result of conflicting requests for advisory record locks. The
fcntl() function detects these conditions and prevents the deadlock by returning an error
condition to the process requesting the conflicting lock.
Deadlocks from Other Sources
CIFS does not necessarily detect deadlocks that arise from services of the operating
system or other software. Therefore, CIFS cannot prevent deadlocks between processes
that use advisory record locking in combination with other services that can cause
suspension.
For example, Transaction Processing (TIP) has a locking mechanism that can suspend a
process. CIFS cannot detect this condition, however, and a deadlock can occur if
another process tries to use a conflicting advisory record lock.
Try to avoid potential deadlock situations when it is necessary to use other services that
can cause suspension in conjunction with advisory record locking.
3–28 7859 6137–009

Using Pipes
File Concepts
A pipe is a temporary mechanism for transferring data. Two processes can use a pipe,
where one process calls the pipe() function to create a pipe and the other process
accesses it. Both processes must know the pipe's file descriptors, so they must be
either
• Parent and child processes
• Sibling processes (descended from the same parent)
Alternatively, one process can use a pipe by itself.
Example
A common use for pipes is to pass data between two processes running different
programs, as shown in the following diagram. Process A creates a pipe and writes data
to it. Process B is a child of process A and inherits A's file descriptors. In particular,
fildes[0] is the pipe's file descriptor for reading and fildes[1] is the pipe's file descriptor
for writing. Therefore, process B can read the data in the pipe and use it as necessary.
All read and write operations are done on a First-In-First-Out (FIFO) basis.
0
1
fildes[0]
fildes[1]
Process
A
_CIFS_NEW_PROCESS ( )
fildes[0]
fildes[1]
File Descriptors File Descriptors
7859 6137–009 3–29
0
1
Process
B

File Concepts
Example Code
The following code shows a simple example of a parent writing a message to a pipe and
creating a child process. The child reads the message and prints it. For simplicity, error
checking is omitted.
#include
#include
void child = thread(int read = fd) {
}
char msg[16];
int count;
/* Loop to insure we get all of the input until write end closes. */
while ((count = read(readfd, msg, sizeof msg - 1)) > 0) {
msg[count] = '\0';
printf("Child: read %d byte message from pipe end %d\n",
count, msg, read = fd);
}
/* Closing read end is not strictly necessary. */
close(read = fd);
return;
int main() {
int fd = pipe[2];
}
= task_array new = task = { 2, 0 };
char message[] = "This is a piped string.";
/* Create the pipe. */
pipe(fd_pipe);
/* Start child, passing pipe read end. */
tskstart(new_task, child_thread, fd_pipe[0]);
printf("Parent: writing to pipe end %d\n",
message, fd_pipe[1]);
write(fd_pipe[1], message, sizeof message);
/* Child won't terminate until write end is closed. */
close(fd_pipe[1]);
return 0;
3–30 7859 6137–009

This program produces the following output:
Parent: writing to pipe end 4
Child: read 15 byte message from pipe end 3
Child: read 9 byte message < string.> from pipe end 3
Related Functions
File Concepts
The following table identifies the tasks involved in file input and output (I/O) operations
and the functions that perform them. See Section 5 for detailed information about each
function.
Topic Task Function
Reading and
writing
operations
File descriptors,
advisory locks,
and the
read/write offset
Read a file. read()
Write to a file. write()
Write all data from buffer to a file, synchronizing
data.
Write all data from buffer to a file, synchronizing
the file’s state (access times).
fdatasync()
fsync()
Write all data from buffer, synchronizing data. sync()
Create file descriptor for existing open file
description.
Associate a specific file descriptor with an existing
open file description.
Access and set the read/write offset, file descriptor
flags, file status flags, and advisory record locking
information.
Create a stream and associate it with a file
descriptor.
7859 6137–009 3–31
dup()
dup2()
fcntl()
fdopen()
Retrieve a file descriptor for a specific data stream. fileno()
Set the read/write offset for an open file. lseek()
Pipes Create a pipe. pipe()
Directories Open a directory stream. opendir()
Close an open directory stream. closedir()
Read a directory stream. readdir()
Reposition a directory stream at its beginning. rewinddir()

File Concepts
Environment Variables
Environment variables control various aspects of CIFS operation, through both
application program and utility interfaces. If a variable does not exist, CIFS assumes its
value is blank, except as noted. Variables can be accessed through the set and setsys
commands of the CIFS utility, or through the PUT$ENV and GET$ENV interfaces, as
documented in the System Services Programming Reference Manual.
Environment variables cannot be set by transaction processing (TIP) programs. However,
TIP programs uses any environment variable settings established in the system or an
appropriate user profile.
Variable names are case sensitive; all CIFS variables must be specified in upper case.
Lower case or mixed case names can be set by @CIFSUT for other purposes, but will
not be recognized by the CIFS subsystem. The values are not case sensitive.
Variable Legal Values Description
CIFS$ACR PUBLIC,
PRIVATE, or any
valid ACR name
useable by the
caller.
CIFS$CACHE Any numeric
value. A k, m, or
g suffix applies a
multiplier of
1024, 1024k, or
1024m,
respectively
CIFS$CAT Valid @CAT
parameters
starting with the
type field; if
blank, the system
default type is
used in
conjunction with
a maximum size
of 262,143
tracks.
CIFS$CD Any valid CIFS
directory name.
Specifies the OS 2200 security attributes to
set for any new files created through CIFS
or for existing files undergoing ownership
change. Default is PRIVATE.
Specifies the size of the CIFS file cache.
The default size is 64 MW, and the
minimum is 16 MW. Using a value smaller
than the minimum results in CIFS using the
minimum.
Specifies the parameters to use on any
mkdir() or open() with O_CREAT that
creates an OS 2200 file associated with the
specified CIFS directory or file.
Specifies the current working directory.
Defaults to /os2200/
Changed by CIFS on any successful chdir()
call.
3–32 7859 6137–009

Variable Legal Values Description
CIFS$COMAPI Communications
Application
Program
Interface
installation
modes (letters A
through Z, in any
combination).
CIFS$KEYS Valid OS 2200
read/write keys in
the form
/, or blank; the
separating slash
may be omitted if
the write key is
blank or not
needed.
File Concepts
Specifies the Communications Application
Program Interface installation modes that
CIFS must use for network access. Used
only by the CIFS background run. Defaults
to mode A if not specified.
Specifies the read and write keys used to
access or create a file on the next [f]open(),
mkdir(), opendir(), or stat() request. Cleared
on any successful [f]open(), mkdir(), or
opendir() call.
CIFS$MFD STD, SHARED Specifies which 2200 master file directory
to use for file lookup and creation. If this
value is not present, CIFS uses the caller’s
default MFD setting.
CIFS$NEXTFILE Any valid
OS 2200 file
name.
Specifies what 2200 file to associate with
the CIFS file created on the next mkdir() or
[f]open() that creates a new file. This value
is ignored if the CIFS file name uses the
/os2200 path. Cleared on any successful
mkdir() or [f]open() call, regardless of
whether a file was created or the /os2200
structure was used.
CIFS$PW Password Specifies the authorization password to be
used by the CIFS client to connect with
remote hosts.
CIFS$RAW TRUE, FALSE Specifies whether or not data must be
written exactly as received by CIFS (TRUE)
or converted to SDF format (FALSE). The
default is FALSE. Applies only to the next
open() that creates a new file, and is
cleared on any successful open() or fopen().
CIFS$SUBTYPE Standard element
subtypes.
Specifies what symbolic or omnibus
element subtype CIFS must attach to an
element created on the next [f]open().
Cleared on any successful [f]open().
Defaults to the file name extension, if it is
one of the standard subtype mnemonics.
7859 6137–009 3–33

File Concepts
Variable Legal Values Description
CIFS$USER User ID and
optional domain.
CIFS$WAITROLBAK Any numeric
value. A k, m, or
g suffix applies a
multiplier of
1024, 1024k, or
1024m,
respectively.
CIFS$WAITXUSE Any numeric
value. A k, m, or
g suffix applies a
multiplier of
1024, 1024k, or
1024m,
respectively.
Specifies authorization credentials to be
used by the CIFS client to connect with
remote hosts.
Specifies the amount of time, in seconds,
that a caller must wait for a rolled-out file
when O_NONBLOCK is not set on an
open() request. The default value is 600 (10
minutes).
Specifies the amount of time, in seconds,
that a caller must wait for an exclusively
assigned file when O_NONBLOCK is not
set on an open() request. The default value
is 0.
3–34 7859 6137–009

Section 4
Utility Interfaces
CIFS includes a text-based utility, @CIFSUT that provides a command line interface to
manipulate entities within the CIFS file system. The utility accepts commands modeled
after those typically available in Windows 95/98/Me, Windows NT4/2000/XP/2003/Vista,
and POSIX systems. Generally, the Windows commands are aliases for the POSIX
commands with either a one-to-one correspondence or a subset of the POSIX options.
@CIFSUT automatically determines the syntax being requested (POSIX or Windows), so
the syntax for commands shown in the following tables and descriptions can be freely
intermixed in any utility session.
Note: The syntax for directory and file names is given in Section 1. However, the
Windows commands use a back slash (\) rather than the standard forward slash (/) as a
directory delimiter. The standard forward slash (/) indicates option values for the
Windows commands. Any directory or file name that includes embedded spaces or
other special characters (both Windows and POSIX versions) must be bracketed by a
quotation mark (“) at each end. Otherwise, one or more spaces function as field
separators.
Each command input to @CIFSUT consists of one or more lines of ASCII text. Any
command that spans more than one line must use a vertical line (|) at the end of each
continued line.
The format of the processor call line is
@CIFSUT[,opt] [command_set,...]
CIFSUT sequentially processes commands contained in the command_set files or
elements (if any), and then reads commands from the input stream. Display of command
lines processed by CIFSUT is controlled by the processor call options L, N, and S, as well
as the echo command. By default, CIFSUT displays commands from any command_set
files or elements, but not from the input stream. Specifying the L or S options causes
CIFSUT to display all commands; specifying the N option inhibits display of any lines.
7859 6137–009 4–1

Masking with @CIFSUT
Commands include
POSIX Syntax Windows Syntax Description
backup backup Save CIFS directory structure.
binjar [-r]
new_ext
[pathname
[old_ext]...]
binjar
new_ext
[pathname
[old_ext]...] [/s]
Convert files from SDF to binary format.
cat cat (type) Copy one or more files to the standard output
stream.
cd cd (chdir) Change current working directory.
chmod — Change file permissions.
chown — Change the owner of a file.
cp copy Copy one or more files to a target.
date — Display local date, UTC/GMT date, or local offset
from UTC/GMT.
— deltree Delete directory and all files and subdirectories.
echo echo Control display of input command lines.
help help Gives a CIFSUT command list or command syntax.
ln — Insert a link for a regular or FIFO file into a directory.
ls dir Display file information on standard output.
keys keys Set and clear environmental variables.
mkdir md (mkdir) Create directory.
mkfifo — Create fifo file.
mv move Move or rename file.
pwd cd (chdir) Write absolute path name of working directory to
standard output.
rm del Remove file entries in a directory.
rmdir rd (rmdir) Remove empty directory.
set set Display, initialize or update environment variables.
setsys setsys Display, initialize, or update system environment
variables.
share share Create network-visible name for directory.
size size Change logical length of a regular file.
touch — Change access and/or modification time/date of files
and optionally pack the underlying OS 2200 program
files of directories.
unshare unshare Remove network-visible name for directory.
4–2 7859 6137–009

POSIX Syntax Windows Syntax Description
Masking with @CIFSUT
use use Attach an OS 2200 internal name to a CIFS
directory.
version version Display CIFS subsystem version information.
xlate xlate Set or display translation modes for a directory.
Masking with @CIFSUT
You can use masks when providing file names to the @CIFSUT commands. The two
mask characters * and ? can be used in any combination.
Use ∗ to match zero or more characters.
Use ? to match any single character.
Masking can be used only in the cd, chmod, chown, copy, cp, del, deltree, dir, ln, ls,
move, mv, rd, rm, and rmdir commands; it is not available with any of the others.
Masking cannot be specified in any command target; for example, “cp t∗ x∗ “ is not
allowed. Also, masking characters only apply to @CIFSUT; they cannot be used in the
program interfaces other than _cifs_mask().
Examples
ls file∗abc
Displays all files that begin with “file” and end with “abc.” The file can have
anything in between. Valid values include “fileabc.”
ls file?
Displays all 5-character file names that begin with “file” and have another character
at the end of the file name; plain “file” cannot be matched.
ls ∗jan??
Displays all file names that end with “jan” followed by two more characters.
7859 6137–009 4–3

ackup
backup
Application
Use the backup command to save the CIFS directory structure by generating the
necessary CIFSUT or FAS commands to rebuild the structure.
Note: This command is intended for administrator use, and must be done whenever a
system-wide file save is performed. Individual users can use the backup command on
specific directories to obtain a snapshot of that specific part of the file system.
POSIX Syntax
backup [-f] savefile [start_directory]
Windows Syntax
backup savefile [start_directory] [/f]
Arguments
savefile
specifies where to store the generated commands. This file must be used as input
to CIFSUT (no f-option) or FAS (f-option) to restore the CIFS directory structure if it is
necessary to reinitialize it.
start_directory
-f or /f
specifies the directory within the CIFS file system where scanning must start. If not
specified, start_directory defaults to the system root directory.
generates FAS backup commands for the specified starting directory and
subdirectories. If no starting directory is given, FAS backup commands for only CIFS
system files are generated. (This requires that the run is CIFS-privileged.)
4–4 7859 6137–009

injar
Application
binjar
Use the binjar command to convert files from SDF to binary format, renaming the original
to avoid losing it. By default, binjar operates on .jar files, but other extensions may also
be specified.
POSIX or Windows Syntax
binjar [-r] new_ext [pathname [old_ext]...]
Windows Syntax
binjar new_ext [pathname [old_ext]...] [/s]
Arguments
-r
indicates to recursively process all files in the specified directory and its
subdirectories.
new_ext
specifies the additional extension used to rename all files converted to binary format.
pathname
specifies the name of the file or directory on which to operate. Masking is not
permitted. Must be a directory if either the -r or /s option is used.
old_ext
/s
specifies the extensions for the files to convert, if other than the default value (jar).
May be used only if pathname is a directory.
indicates to recursively process all files in the specified directory and its
subdirectories.
7859 6137–009 4–5

cat (type)
cat (type)
Application
Use the cat (type) command to copy one or more files to the standard output
stream.
POSIX Syntax
cat [-estv] source [source ...]
Windows Syntax
type source [source ...]
Arguments
-e
-s
-t
-v
source
Causes a $ character to be printed at the end of each line before the newline;
ignored if the -v option is not present.
Forces the command to be silent about nonexistent files.
Causes tabs to be printed as ^I and formfeeds as ^L; ignored if the ---v option is not
present.
Causes nonprinting characters (other than tabs, formfeeds, newlines) to be displayed
as ^n, M-x, M+x, or M*x. For control characters, n is the uppercase ASCII character
obtained by adding 0100 to the character value; for DEL, n is a question mark. For
characters outside of the ASCII range, M-, M+, and M* indicate the ranges
0200-0377, 0400-0577, and 0600-0777 respectively; x is the ASCII character defined
by the seven low-order bits of the character value.
Specifies the names of the file to be copied.
4–6 7859 6137–009

cd (chdir)
Application
cd (chdir)
Use the cd (chdir) command to change the current working directory. The new working
directory may be specified with either an absolute or relative path name.
POSIX or Windows Syntax
cd [dirname]
Windows Syntax
chdir [dirname]
Arguments
dirname specifies the path name of the directory to which you want to change.
Note: cd without any parameters functions as pwd, displaying the current working
directory.
7859 6137–009 4–7

chmod
chmod
Application
Use the chmod command to change file permissions (read, write, or search/execute) for
a file, as appropriate for the file type. If the target of the command refers to a file in the
OS 2200 Master File Directory, the read-only and write-only attributes of that file are also
changed to correspond to the CIFS file permissions.
POSIX Syntax
chmod [-r] {mode |[ugoa]{{+|-|=}[rwxugo]}...[,[ugoa]{{+|-=}[rwxugo]}...]...}
file ...
Arguments
-r
mode
ugoa
recursively changes the file modes of all files (including directories) subordinate to
the specified directory, except for the following cases:
• Some files might not be accessible, such as a file within a directory that does
not have search permission; chmod cannot operate on such a file.
• chmod changes the mode of the directory before changing the modes of the
directory's files. If the specified change turns off the directory's search or read
permission, chmod cannot access the directory and is prevented from changing
any of its files.
specifies the permission values as a 3-digit number, with one digit for the user,
group, and other classes, respectively. The permission values are:
4 read
2 write
1 execute
These values must be added together to give the desired permission for each class.
For example, the value 754 gives full access to the owning user, read and execute
access to the group, and only read access to other users.
specifies the who value, which identifies the permission classes to change. It
contains zero or more of the following values:
u User (owner) class
g Group class
o Other class
a All classes (default)
4–8 7859 6137–009

+-=
specifies the operator value, which identifies how to change the permissions. It
contains one of the following values:
rwxugo
file
chmod
+ Add permission
- Subtract permission
= Assign permission; that is, clear all the bits in the who value and then add
the permission.
specifies the permission value, which identifies the permissions to change. It
contains zero or more of the following values:
r Read permission
w Write permission
x Search/execute permission
u Read, write, and execute as currently set for user class
g Read, write, and execute as currently set for group class
o Read, write, and execute as currently set for other class
identifies the file whose file mode is changed by this chmod request.
7859 6137–009 4–9

chown
chown
Application
Use the chown command to change the owner of a file. Only the owner of the file or a
privileged user can change the owner. If the value of the CIFS$ACR environment variable
is not blank, that value (public, private, or ACR name) is applied to the specified files.
POSIX and Windows Syntax
chown [-r] owner file ...
Arguments
-r
owner
file
indicates recursive traversal of directories. When this option is specified, chown acts
on all files in the named directory, all subordinate directories, and all files in the
subordinate directories, except where read or search permission is lacking.
specifies the user name or numeric user ID of the new owner. A user name can
appear numeric (for example, 765). If you specify a numeric value, chown assumes it
is a user name unless no user with that name exists. In that case, chown treats the
value as a user ID.
identifies the file whose owner is changed by this chown request.
Examples
Change the file owner for a single file using a user name:
chown jdoe my_file
Change the file owner for multiple files:
chown jdoe my_file my_file2 memo.bob
Change the file owner using a numeric user ID:
chown 123 my_file
Change the owner for all files in a directory and all subordinate directories and files:
chown -R jdoe my_dir
4–10 7859 6137–009

cp (copy)
Application
cp (copy)
Use the cp (copy) command to copy one or more files (including directories) to a target.
POSIX Syntax
cp [-firpbsw] source [source ...] target
Windows Syntax
copy source [source ...] target [/w]
Arguments
-c
When FTP Services (formerly cpFTP) copies a file to an OS 2200 system in mode C
format (two OS 2200 words placed in 9 consecutive bytes), the resulting data cannot
be used without first being reformatted. The -c option implements conversions
between binary and SDF, as follows:
Without the -c option:
Binary input – Each quarter word written to one character
SDF input – each character written to one quarter word
With the -c option:
-f
-i
-r
Binary input – 8 quarter words written to 9 characters
SDF input – 9 characters written to 8 quarter words
This permits relatively easy correction of files mangled by FTP.
force the copy if target is read only.
prompts for confirmation whenever the copy would overwrite an existing target.
must be specified when the source is a directory. If the directory named by target
does not exist, cp creates a directory named target and copies all the files, including
any subdirectories and their files, in source to target. If the directory named by target
exists, a copy of source (with its attendant file structure) becomes a subdirectory of
target. In either case, all files retain their file types.
7859 6137–009 4–11

cp (copy)
-p
-b
-s
source
target
sets the following attributes of target to the same values as in source:
Last modification and access times
File mode settings
force copy of source to binary format.
force copy of source to SDF format.
specifies the name of the file to be copied. If target is a directory, you can specify
more than one file; otherwise, only one file is permitted.
specifies the destination file name (might be a directory); target must be different
from source.
-w and /w
removes carriage returns from the ends of lines.
4–12 7859 6137–009

date
Application
Use the date command to display the local time/date, UTC/GMT time/date, or local time
offset from UTC/GMT time.
POSIX Syntax
date [-o] [-u]
Arguments
-o
-u
displays the local time offset from UTC/GMT time in the format hh:mm.
displays UTC/GMT time.
Note: Not specifying any options displays the local system time.
date
7859 6137–009 4–13

deltree
deltree
Application
Use the deltree command to delete a specific directory and all files and subdirectories.
The rm –r command is the POSIX equivalent.
Windows Syntax
deltree dirname
Arguments
dirname
is the location and name of the directory you want to delete.
4–14 7859 6137–009

echo
Application
Use the echo command to control display of input command lines.
POSIX and Windows Syntax
echo [on³off]
Arguments
on
off
enables display of input command lines.
disables display of input command lines.
On is assumed if neither on nor off is specified.
echo
7859 6137–009 4–15

help
help
Application
Use the help command to display a list of CIFSUT commands or to display the syntax of
a list of CIFSUT commands.
POSIX and Windows Syntax
help [cmd ...]
Arguments
cmd
A CIFSUT command name, such as cat or ls. Multiple command names can be listed
and are separated by blanks.
4–16 7859 6137–009

keys
Application
Use the keys command to have CIFSUT set and clear the environment variable
CIFS$KEYS before manipulating OS 2200 files that have read or write keys. Read/write
keys can be used for unowned files and for owned files if the
owned_file_read_write_keys dynamic configuration parameter is set to true. Using the
set command to establish a CIFS$KEYS value also sets both the source and target
values for the keys command.
keys
Note: CIFSUT uses the source or target keys settings only in subsequent commands,
such as cp, mv, rm, and so on; it does not change CIFS$KEYS immediately. The source
value is used for dir, ls, share, use, and the “from” side of copy, cp, ln, move, and mv.
The target value is used for chmod, chown, del, deltree, md, mkdir, rd, rm, and rmdir,
and the “to” side of backup, copy, cp, ln, move, and mv. The difference between source
and target is whether the file or directory is just being read or it is being changed.
POSIX and Windows Syntax
keys [source=[rkey][/wkey]] [target=[rkey][/wkey]]
Formats/Arguments
keys
clears both the source and target keys settings.
keys source=[rkey][/wkey]
sets the CIFS$KEYS value for the source file keys and clears the CIFS$KEYS setting
for target file keys (since no target argument is specified).
keys target=[rkey][/wkey]
sets the CIFS$KEYS value for the target file keys and clears the CIFS$KEYS setting
for source file keys (since no source argument is specified).
keys source=[rkey][/wkey] target=[rkey][/wkey]
sets the CIFS$KEYS value for both the source and target file keys.
[rkey][/wkey]
specifies the values of the source or target file read and write keys.
7859 6137–009 4–17

ln
ln
Application
Use the ln command to create additional directory entries for a specified set of regular or
FIFO files. When linked, different file names (typically in different directories) refer to the
same file contents. There is no Windows equivalent.
POSIX Syntax
ln [-f] source [source...] target
Arguments
-f
source
target
is required when the file named by target already exists.
specifies the name of an existing file to which target is linked. You can specify more
than one source if target names a directory (other than the directory containing the
source files).
specifies the name of the file to be linked to source-file or the name of the directory
where the new linked file name is to be created:
• If target does not exist, file name target is created and linked to source-file.
• If a file named target already exists, its contents are removed and target is linked
to source-file (subject to the conditions described under the -f option).
• If target names a directory, the file name source-file is created in that directory
and linked to the original source-file.
4–18 7859 6137–009

ls (dir)
Application
Use the ls (dir) command to write information about files to the standard output.
Note: File types are identified by a question mark (?) when CIFS has not yet
determined whether the object is a file or a directory.
POSIX Syntax
ls [-agilmortuvx12] [filename ...]
Windows Syntax
dir [filename...] [/a[[:]attributes]] [/o[[:]sortorder]] [/t[[:]timefield]]
[/s] [/2]
Arguments
-a
-g
-i
-l
-m
-o
-r
-t
displays all directory entries.
displays the same information as -l, except for owner user ID.
displays the inode number of the directory entry.
ls (dir)
displays additional file information: file type, file permissions, number of links, owner
user ID, group (ACR) ID, file size in bytes, and last modification time.
displays entry names in a stream, separated by commas.
displays the same information as -l, except for group (ACR) ID.
displays directories recursively (subdirectories and their contents).
sorts entries by time of last modification instead of by name.
7859 6137–009 4–19

ls (dir)
-u
-v
-x
-1
-2
uses time of last access instead of last modification for displaying (-l) or sorting (-t).
displays entries in reverse order.
displays entries sorted in rows rather than columns.
displays entries for each line, instead of in columns.
displays the underlying OS 2200 directory, file name, and f-cycle.
filename
specifies the name of a file or group of files for which information is requested.
/a[[:]attributes]
displays only the names of those files with the attributes you specify. The colon (":")
is optional. Use any combination of these values, and do not separate the values
with spaces:
/o[[:]sortorder]
d directories
r read-only files
-d nondirectory files only
-r files that are not read-only
controls the order in which dir sorts and displays file names. The colon (“:”) is
optional. Use any combination of these values, and do not separate these values
with spaces:
n in alphabetic order by name
e in alphabetic order by extension
d by date and time, earliest first
s by size, smallest first
g with directories grouped before nondirectory files
-n in reverse alphabetic order by name (Z through A)
-e in reverse alphabetic order by extension (Z through A)
-d by date and time, latest first
-s by size, largest first
-g with directories grouped after nondirectory files
4–20 7859 6137–009

t[[:]timefield]
ls (dir)
controls which time field is displayed or used for sorting. The following list describes
each of the values you can use for timefield:
c creation
a last access
w last written
/s lists every occurrence, in the specified directory and all subdirectories, of the
specified file name.
/2 displays 2200 file name format.
7859 6137–009 4–21

mkdir (md)
mkdir (md)
Application
Use the mkdir (md) command to create one or more directories and, optionally, to create
components of the path name that do not exist.
POSIX Syntax
mkdir [-enp] [-m mode] dirname...
Windows Syntax
mkdir dirname
md dirname
Arguments
-p
creates any component of the path name that does not exist.
-m mode
specifies the access permission for the created directory. Mode settings are the
same as for chmod.
dirname
-e
-n
specifies the directory name and can include slash (/), dot (.), and dot-dot (..) in all
valid path names.
creates a Large Element Program File (LEPF). If the file already exists, it converts a
normal program file to an LEPF.
creates a normal Program File (PF). If the file already exists, it converts an LEPF to
a PF if no elements are found greater than 262,143 sectors long.
4–22 7859 6137–009

mkfifo
Application
mkfifo
Use the mkfifo command to create one or more new First-In-First-Out (FIFO) files, and
optionally, to create components of the path name that do not exist. The new FIFO is
empty.
POSIX Syntax
mkfifo [-p] [-m mode] fifoname ...
Arguments
-p
creates any component of the path name that does not exist.
-m mode
specifies the access permission for the created FIFO file. Mode settings are the
same as for chmod. The default mode bits are 0644.
fifoname
specifies the FIFO file name and can include slash (/), dot (.), and dot-dot (..) in valid
path names
7859 6137–009 4–23

mv (move)
mv (move)
Application
Use the mv (move) command to move or rename a file. You can also use the mv (move)
command to move a directory along with any subordinate files and directories.
POSIX Syntax
mv [-fi] source [source ...] target
Windows Syntax
move source target
Arguments
-f
-i
source
target
moves the specified file without prompting for confirmation even in circumstances
that would otherwise cause a confirmation prompt.
prompts for confirmation whenever the move would overwrite an existing file.
specifies the name of the file (may be a directory) to be moved. If target is a
directory, you can specify more than one file; otherwise, only one file is permitted.
specifies the destination file name (may be a directory); target must be different than
source.
4–24 7859 6137–009

pwd (cd)
Application
pwd (cd)
Use the pwd (cd) command to write the absolute path name of the working directory to
the standard output.
POSIX Syntax
pwd
Windows Syntax
cd
Arguments
None
7859 6137–009 4–25

m (del)
rm (del)
Application
Use the rm (del) command to remove one or more entries from a directory.
POSIX Syntax
rm [-cfir] filename [filename ...]
Windows Syntax
del filename [filename ...] [/c] [/f] [/p] [/q] [/s]
Arguments
-c
-f
-i
-r
removes all cycles of a directory entry rather than the current one.
removes files without asking you whether to remove the file, even when the file is
write-protected.
removes files but asks you first whether to remove each file.
recursively removes all files, including subdirectories, without asking you whether to
remove them.
filename
/c
/f
/p
/q
specifies one or more file names to remove.
removes all cycles of a directory entry rather than the current one.
forces deletion of read-only files.
prompts you for confirmation before deleting the specified files.
inhibits prompt if mask of “*” is requested.
4–26 7859 6137–009

s
deletes specified files from the current directory and all subdirectories.
Recursive Removal of Files
rm (del)
The following figure shows regular files and directories removed recursively using rm -r
or del /s:
SALADS
3
COLD
6
2
11
7
SANDWICHES
BAKE
4
LETTUCE
5
SPINACH
8
CHEESE
9
PEANUT_
BUTTER
Explanation:
7859 6137–009 4–27
10
1
12
RECIPE
SHOPPING_
LIST
1. Remove contents of RECIPE?
2. Remove contents of COLD?
3. Remove contents of SALADS?
4. Remove file of LETTUCE?
5. Remove file of SPINACH?
6. Remove directory SALADS?
7. Remove contents of SANDWICHES?
8. Remove file CHEESE?
9. Remove file PEANUT_BUTTER?
10. Remove directory SANDWICHES?
11. Remove directory COLD?
12. Remove file SHOPPING_LIST?
13. Continue in the same manner through the HOT directory
13
HOT
FRY
MACARONI_
AND_CHEESE
EGG PANCAKE

mdir (rd)
rmdir (rd)
Application
Use the rmdir (rd) command to remove empty directories.
POSIX Syntax
rmdir [-p] dirname ...
Windows Syntax
rmdir dirname
rd dirname
Arguments
-p
removes all empty directories in path name dirname.
dirname
specifies the path name of a directory to remove.
4–28 7859 6137–009

set
Application
Use the set command to display, initialize, or update environment variables for the
current run (see Environment Variables, Section 3). Using the set command to establish
a CIFS$KEYS value also sets the source and target values for the keys command.
POSIX and Windows Syntax
set [variable[=[string]]]
Arguments
Blank/None
displays the current environment settings.
variable[=]
string
if followed by an equal sign (=), it specifies the variable you want to set or modify. If
not followed by an equal sign, displays the current value of the variable.
specifies the string you want associated with the specified variable. If you omit the
string, variable is cleared. All characters are valid for the string, so values containing
embedded spaces must not be enclosed in quotation marks unless the quotation
marks are part of the value.
7859 6137–009 4–29
set

setsys
setsys
Application
Use the setsys command to display, initialize, or update environment variables in the
active system profile (see “Environment Variables,” Section 3).
Notes:
• Only callers with write access to the passive system profile file can update the active
system profile. In addition, the caller must be system-low (clearance level 0) for
secure systems beyond Fundamental Security (Security Options 1, 2, and 3).
The active system profile settings exist only for the life of the system and are
discarded at system termination. Use the security management product to designate
the passive system profile location to be used for future sessions.
• Also see “security management product” in the glossary.
POSIX and Windows Syntax
setsys [variable[=[string]]]
Arguments
Blank/None
displays the current system environment settings.
variable[=]
string
if followed by an equal sign (=), it specifies the variable you want to set or modify. If
not followed by an equal sign, displays the current value of the variable.
specifies the string you want associated with the specified variable. If you omit the
string, variable is cleared. All characters are valid for the string, so values containing
embedded spaces must not be enclosed in quotation marks unless the quotation
marks are part of the value.
4–30 7859 6137–009

share
Application
Use the share command to create a network-visible name for the specified directory.
POSIX and Windows Syntax
share dirname [netname]
Arguments
dirname
specifies the location and name of the directory to be made network visible.
netname
specifies the name of the directory as seen from network connections. If not
specified, the command displays the current share name for the directory. The
netname cannot be more than 31 characters long.
share
Note: Many network clients cannot access names that have more than 12 characters.
7859 6137–009 4–31

size
size
Application
Use the size command to change the logical length of a regular file.
POSIX and Windows Syntax
size filename nnnn
Arguments
filename
nnnn
specifies the location and name of the file to be resized.
specifies the new size of the file. It may be larger or smaller than the existing size.
For files stored in SDF format, the nnnn value of 34359738367 has special meaning.
CIFS treats this as an indication that it must recalculate the actual size of the file on
the next read of the file that encounters the EOF record.
4–32 7859 6137–009

touch
Application
touch
Use the touch command to change the access or modification time or date of files, or to
pack the underlying OS 2200 program files of the specified CIFS directories. The CIFS
pack operation (touch -p ...) is directly analogous to a FURPUR @PACK. Any existing
relocatable and PROC entry point tables in the program file are preserved.
Note: The CIFS pack is a safe pack, in that if the system goes down or an X-keyin to the
run is done during the pack, the contents of the program files are preserved, except in
rare circumstances.
POSIX Syntax
touch [-afmpr] [-d ref_file | -t date] [filename | dirname ...]
Arguments
-a
-f
-m
-p
-r
update only the access time.
a file is created if it does not exist.
update only the modification time. If neither -a nor -m nor -p is specified, the effect is
the same as -am.
pack the underlying OS 2200 program files of the CIFS directories. A pack of a
program file is needed when there are many deleted element entries and either the
text area reaches or is closed to the maximum size of the file, or the TOC area
fills-up.
Note: CIFS requires exclusive use of a program file while it is being packed. It must
not be assigned to any run or name section, including the run doing the touch
command. Using the -r option with the -p option gives the ability to pack the
underlying program files of a whole tree of directories with one command.
recur through any directories encountered.
-d ref_file
use the corresponding time of ref_file instead of the current time.
7859 6137–009 4–33

touch
-t date
CC
YY
MM
DD
hh
mm
ss
where date is of the format
[[CC]YY]MMDDhhmm[:ss]
where each pair of digits represents the following:
(optional) specifies the first two digits of the year (the century).
If neither CC nor YY is specified, the current year is assumed.
If YY is specified but CC is not specified, CC is derived as follows:
If YY is CC becomes
69–99 19
00–68 20
(optional) specifies the last two digits of the year.
If neither CC nor YY is specified, the current year is assumed.
specifies the month of the year (01 through 12).
specifies the day of the month (01 through 31).
specifies the hour of the day (00 through 23).
specifies the minute of the hour (00 through 59).
(optional) specifies the second of the minute (00 through 61).
Note: The -r and -t options are mutually exclusive.
filename
specifies one or more files, including directories, to modify. Masking may be used.
4–34 7859 6137–009

unshare
Application
unshare
Use the unshare command to remove a network-visible name for the specified directory.
POSIX and Windows Syntax
unshare dirname
Arguments
dirname
specifies the location and name of the directory to be removed from network
visibility.
7859 6137–009 4–35

use
use
Application
Use the use command to temporarily associate an OS 2200 internal file name with the
OS 2200 file associated with a CIFS file, typically a CIFS directory. This allows 2200
programs that are not CIFS-aware to access files in the CIFS hierarchy. The association
lasts until the run terminates or is removed with the OS 2200 ECL command @FREE.
POSIX and Windows Syntax
use int_name cifs_path
Arguments
int_name
specifies the OS 2200 internal name to associate with the CIFS file. The name must
conform to OS 2200 ECL syntax rules (maximum of 12 characters from the set of
alphanumerics, dollar sign, and dash).
cifs_path
specifies the path name of the CIFS file to expose to non-CIFS-aware programs.
This must not be a CIFS file that is stored as an OS 2200 element, so cifs_path
usually refers to a directory.
4–36 7859 6137–009

version
Application
Use the version command to display the CIFS subsystem name, build date, build
number, and gate bank BDI.
POSIX and Windows Syntax
version
Arguments
None
version
7859 6137–009 4–37

xlate
xlate
Application
Use the xlate command to set or display the translation attributes for a directory.
POSIX and Windows Syntax
Xlate dirname [in=[ccsname]] [out=[ccsname]]
Arguments
dirname
specifies the directory to manipulate.
ccsname
specifies the coded character set name for the desired translation. SDF files written
into the directory use the in= setting to convert the data from the specified ccsname
format into Unicode. Likewise, files read out of a translation–enabled directory use
the out= setting to convert Unicode to the specified ccsname format. A blank
ccsname turns off translation for that direction. Case is ignored for ccsname.
If neither argument is specified, CIFSUT displays the current translate settings for
the directory. If only one argument is specified, only that one is changed for the
directory.
Valid values for ccsname are UNICODE, Shift-JIS, LETS-J, JIS-X0201, JIS–X0208,
JIS-X0212, ISO8859-1, ISO8859-2, ISO8859-3, ISO8859-4, ISO8859-5, ISO8859-6,
ISO8859-7, ISO8859-8, ISO8859-9, ISO8859-10, ISO8859-13, ISO8859-14, and
ISO8859-15. Character mappings are available from the Unicode Web site,
http://www.unicode.org.
4–38 7859 6137–009

Section 5
C Program Interfaces
The following table lists the C application program interfaces (APIs) supplied by the
CIFSLIB component. Each API has a POSIX-like name and a CIFS name (unless no
equivalent POSIX-like name exists). The POSIX-like names are provided first because
their syntax allows them to be more easily alphabetized. The CIFS name is the same
except for the “_cifs_” prefix.
A description of each API follows the table, again alphabetized by the POSIX-like name
for convenience.
Note: The error codes that are described with each API are the most common error
codes for that function. Appendix B includes a complete list of error codes.
User programs written in UC can use the CIFS API name directly by including the
following function definition statement:
#include
With cifsio.h, programs can also access files using the standard UC libraries. When they
do so, the #include of stdio.h must appear before the cifsio.h include.
UC programs can access the CIFS interfaces through the POSIX names with this
statement:
#include
This technique precludes simultaneous use of the UC I/O library, but allows programs to
be much more portable.
Notes:
• All interfaces and structures are defined by the above #include header files.
• In addition to stdio.h, other files can be affected by the order in which cifsio.h or
cifspsxio.h is included. To avoid unexpected redefinitions, place the #include
statement for cifsio.h or cifspsxio.h after any #include statements for standard library
header files.
• Masking of characters applies only to @CIFSUT and the program interface
_cifs_mask(). Masking cannot be used in other program interfaces.
7859 6137–009 5–1

Table of C APIs
Table of C APIs
POSIX API
Name
CIFS API Name
Description
access _cifs_access Determines existence and accessibility
chdir _cifs_chdir Changes current working directory
chmod _cifs_chmod Changes access permissions for a file
chown _cifs_chown Changes the owner and, optionally, the group of
a file
clearerr _cifs_clearerr Clears end-of-file and error indications
close _cifs_close Terminates access to an open file
closedir _cifs_closedir Terminates access to an open directory
creat _cifs_creat Creates and opens a new file
dup _cifs_dup Creates an additional file descriptor for an open
file
dup2 _cifs_dup2 Associates a specific file descriptor with an open
file
(none) _cifs_end_process Terminates a CIFS process
fclose _cifs_fclose Terminates access to an open stream
fcntl _cifs_fcntl Manipulates file attributes and status
fdatasync _cifs_fdatasync Forces writing of all buffered data for an open
file
fdopen _cifs_fdopen Associates a stream with an open file
feof _cifs_feof Checks end-of-file condition for a stream
ferror _cifs_ferror Checks read/write errors for a stream
fflush _cifs_fflush Forces writing of stream buffers
fgetc _cifs_fgetc Gets next character from a stream
fgetpos _cifs_fgetpos Gets current position of a stream
fgets _cifs_fgets Gets multiple characters from stream
fileno _cifs_fileno Retrieves file association of a stream
fopen _cifs_fopen Opens a stream
fprintf _cifs_fprintf Writes formatted output to a stream
fputc _cifs_fputc Writes a character to a stream
fputs _cifs_fputs Writes multiple characters to a stream
fread _cifs_fread Reads multiple byte strings from a stream
freopen _cifs_freopen Changes the file association of a stream
5–2 7859 6137–009

POSIX API
Name
CIFS API Name
Description
fscanf _cifs_fscanf Reads formatted input from a stream
fseek _cifs_fseek Sets the current position of a stream
fsetpos _cifs_fsetpos Sets the current position of a stream
fstat _cifs_fstat Retrieves information about an open file
Table of C APIs
*fsync _cifs_fsync Forces writing of all buffered data for an open
file
ftell _cifs_ftell Retrieves current position of a stream
*ftruncate _cifs_ftruncate Sets the length of a stream
fwrite _cifs_fwrite Writes multiple byte strings to a stream
getc _cifs_getc Gets next character from a stream
getchar _cifs_getchar Gets next character from the standard input
stream
getcwd _cifs_getcwd Retrieves the current working directory
getpwnam _cifs_getpwnam Determines the current state of a user in the
database using the user's name
getpwuid _cifs_getpwuid Determines the current state of a user in the
database using the user's numeric identifier
gets _cifs_gets Gets multiple characters from the standard input
stream
getuid _cifs_getuid Returns the numeric user ID value of the calling
process
istat _cifs_istat Retrieves information about an inode
link _cifs_link Associates a path name with an existing file
lseek _cifs_lseek Sets current position of an open file
(none) _cifs_mask Checks a string for matching a wild card
specification
mkdir _cifs_mkdir Creates a new directory
mkfifo _cifs_mkfifo Creates a new first-in, first-out (FIFO) file
(none) _cifs_new_process Initiates a new process environment within CIFS
open _cifs_open Opens a named file
opendir _cifs_opendir Opens a directory
**pack _cifs_pack Packs the underlying program file of a CIFS file
or directory
perror _cifs_perror Writes an error message to the standard error
stream
pipe _cifs_pipe Creates a pipe
7859 6137–009 5–3

Table of C APIs
POSIX API
Name
CIFS API Name
Description
printf _cifs_printf Writes formatted data to the standard output
stream
putc _cifs_putc Writes a single character to a stream
putchar _cifs_putchar Writes a character to the standard output stream
puts _cifs_puts Writes multiple characters to the standard
output stream
read _cifs_read Reads data from an open file
readdir _cifs_readdir Reads an entry from a directory
*realpath _cifs_realpath Returns the fully resolved path for a specified
file
remove _cifs_remove Deletes an existing file
rename _cifs_rename Renames an existing file
rewind _cifs_rewind Sets the current position of a stream to zero
rewinddir _cifs_rewinddir Repositions an open directory to the first entry
rmdir _cifs_rmdir Deletes an empty directory
scanf _cifs_scanf Reads formatted data from the standard input
stream
(none) _cifs_share Specifies the network-visible name for a
directory
sprintf _cifs_sprintf Writes formatted data to a string
sscanf _cifs_sscanf Reads formatted data from a string
stat _cifs_stat Retrieves information about an existing named
file
strerror _cifs_strerror Returns the ELMS error message text for the
specified error code
tmpfile _cifs_tmpfile Creates a temporary stream
tmpnam _cifs_tmpnam Retrieves a unique file name string
*truncate _cifs_truncate Sets the length of a regular file
umask _cifs_umask Sets the file mode creation mask inhibit bits
ungetc _cifs_ungetc Returns a character to an input stream
unlink _cifs_unlink Disassociates a path name from a file
5–4 7859 6137–009

POSIX API
Name
CIFS API Name
Description
Table of C APIs
(none) _cifs_uname Returns CIFS subsystem version information
utime _cifs_utime Changes access and modification times
vfprintf _cifs_vfprintf Writes formatted data to a stream
vprintf _cifs_vprintf Writes formatted data to the standard output
stream
vsprintf _cifs_vsprintf Writes formatted data to a string
write _cifs_write Writes data to an open file
(none) _cifs_xlate Sets or retrieves translation modes for a
directory
Notes:
• Interfaces flagged with an asterisk (*) are not part of the POSIX standard, but are
commonly available on most UNIX platforms.
• Interfaces flagged with a double asterisk (**) are not part of the POSIX standard but
are part of OS 2200 CIFS.
7859 6137–009 5–5

access()
access()
Application
Use the access() function to determine if either of the following is true:
• A file exists.
• The calling process has permission to access a file.
Synopsis
int access(const char * path, int amode);
Description
The access() function checks file permissions or existence, where:
path
amode
is a pointer to the path name of the file.
determines what to check, which is either of the following:
• File permissions
The value is the bitwise inclusive OR of any of the following constants:
− R_OK (Check for read permission)
− W_OK (Check for write permission)
− X_OK (Check for search/execute permission)
• File existence
The value is F_OK; that is, check whether the file or directory exists.
Checking File Permissions
The access() function checks each permission requested in amode. access() uses the
real user ID and real group ID of the calling process to decide which file permission class
(owner, group, or other) to check. In addition, to the permission bits maintained by CIFS,
the access() function also verifies that the requested permission is allowed by OS 2200
security.
Return Values
If all the specified access permissions are allowed or if the file exists (whichever was
requested), the access() function returns 0. Otherwise, access() sets errno to identify the
specific error and returns -1.
5–6 7859 6137–009

Error Codes
access()
If any of the following conditions occurs, the access() function returns -1 and sets errno
to the corresponding value:
EACCES Either of the following errors occurred:
• One or more permissions specified by amode are denied.
• The calling process is denied search permission on a directory in
the path name.
EFAULT The pointer specified by path is invalid.
EINVAL An invalid value was specified for amode.
ENOENT Either of the following errors occurred:
• The file does not exist.
• path points to an empty string
ENOTDIR A component of the path prefix is not a directory.
7859 6137–009 5–7

chdir()
chdir()
Application
Use the chdir() function to change to a different current working directory.
Synopsis
int chdir(const char * path);
Description
The chdir() function changes the current working directory of the calling process, where
path identifies the new directory.
Return Values
If the chdir() function completes successfully, it returns 0. Otherwise, chdir() sets errno
to identify the specific error and returns -1.
Error Codes
If any of the following conditions occurs, the chdir() function returns -1 and sets errno to
the corresponding value:
EACCES The calling process is denied search permission to a directory in the
path name.
EFAULT The pointer specified by path is invalid.
ENOENT Either of the following errors occurred:
• The directory does not exist.
• path points to an empty string.
ENOTDIR A component of the path name is not a directory.
5–8 7859 6137–009

chmod()
Application
Use the chmod() function to change the file permissions of the mode for a file.
Privilege Requirement
chmod()
For a process to change the file permissions or type of a program file, the user ID of the
process must be equal to the user ID of the file.
Synopsis
int chmod(const char * path, mode_t mode);
Description
The chmod() function changes the file permission bits and program file type, where:
path
mode
is a pointer to the path name of the file.
contains the new settings for the file permissions.
Open Files and Directory Streams
Any process with an open directory stream or a file descriptor to an open file can
continue accessing the stream or file, even if the chmod() function changes the
permission bits.
Changing File Permissions and Special File Attributes
If the process is allowed to change the file permissions of a file (see “Privilege
Requirement” in this subsection), chmod() sets the file permissions in the file mode to
the values specified in mode. If the target of chmod() refers to a file in the OS 2200
Master File Directory, the read-only and write-only attributes of that file are also changed
to correspond to the CIFS file permissions.
Return Values
If the chmod() function completes successfully, it updates the st_atime field of the file or
directory and returns 0. Otherwise, chmod() sets errno to identify the specific error and
returns -1.
7859 6137–009 5–9

chmod()
Error Codes
If any of the following conditions occurs, the chmod() function returns -1 and sets errno
to the corresponding value:
EACCES The calling process is denied search permission to a directory in
the path name.
EFAULT The pointer specified by path is invalid.
EINVAL Any of the following errors occurred:
• mode has undefined bits set.
• mode has bits set that chmod() cannot change.
• A path name component is longer than 4095 characters.
ENOENT Either of the following errors occurred:
• The file does not exist.
• path points to an empty string.
ENOTDIR A component of the path name is not a directory.
EPERM Both of the following conditions are true:
• The effective user ID does not match the owner of the file or
directory.
• The process is privileged.
5–10 7859 6137–009

chown()
Application
chown()
Use the chown() function to change the security attributes (user ID and group ID) of a
file, assigning the file to a different owner and group. If the value of the CIFS$ACR
environment variable is not blank, that value (public, private, or ACR name) is also applied
to the specified file.
For a process to change the security attributes of a file, one of the following must be
true:
• The user ID of the process is equal to the user ID of the file.
• The process is privileged.
Synopsis
int chown(const char * path, uid_t owner, gid_t group);
Description
The chown() function changes the user ID and group ID of a file, where:
path
owner
group
identifies the file.
contains the new user ID for the file. If owner = -1, the user ID is unchanged.
contains the new group ID for the file. If group = -1, the group ID is unchanged. If
both owner = -1 and group = -1, both the user ID and group ID are unchanged;
therefore, chown() changes neither the st_atime field nor the file mode.
Return Values
If the chown() function completes successfully, it does the following:
• Updates the st_atime field of the file
• Returns 0
Otherwise, chown() sets errno to identify the specific error and returns -1.
7859 6137–009 5–11

chown()
Error Codes
If any of the following conditions occurs, the chown() function returns -1 and sets errno
to the corresponding value:
EACCES The calling process is denied search permission to a
directory in the path name.
EFAULT The pointer specified by path is invalid.
EINVAL owner or group is a value that can never possibly be a
valid user ID or group ID.
ENAMETOOLONG A path name component is longer than 4095 characters.
ENOENT Either of the following errors occurred:
• The file does not exist.
• path points to an empty string.
ENOTDIR A component of the path name is not a directory.
EPERM Both of the following conditions exist:
• The effective user ID does not match the owner of
the file or directory.
• The process is not privileged.
5–12 7859 6137–009

clearerr()
Application
clearerr()
Use the clearerr() function to clear the end-of-file and error indicators for the stream.
Synopsis
void clearerr(FILE * stream);
Description
The clearerr() function clears the end-of-file and error indicators for a stream, where:
FILE
stream
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object.
The end-of-file and error indicators are cleared only at the following times:
• When the file is opened
• By an explicit call to one of the following functions:
− clearerr()
− fseek()
− rewind()
Return Values
The clearerr() function returns no value.
7859 6137–009 5–13

close()
close()
Application
Use the close() function to release certain file attributes and prevent further access to a
file through a specific file descriptor. Closing a file does the following:
• Deallocates the specified file descriptor and makes it available for reuse by
subsequent calls to other functions, such as open() and dup(). Reusing file
descriptors is important for redirecting the standard files (standard input, standard
output, and standard error) to a pipe, for example.
• Removes all record locks the calling process holds on the file. You might want to
close a file to clear all locks you set on it, then open the file again to access a
different segment. This reduces lock conflicts for cooperating processes trying to
access the same file.
Synopsis
int close(int fildes);
Description
The close() function removes access to an open file description through a certain file
descriptor, where fildes identifies the file descriptor. That is, the calling process can no
longer use that file descriptor for input and output operations to the original file.
Additional Processing for the Last File Descriptor
When fildes identifies the last file descriptor for the following file types, close() does the
additional processing specified:
• Pipe or FIFO file
close() discards any data remaining in the pipe or FIFO file.
• Open file description
close() discards the open file description.
• File whose link count is 0
close() deletes the file and frees its space.
Return Values
If the close() function completes successfully, it returns 0. Otherwise, close() sets errno
to identify the specific error and returns -1.
Error Codes
If the following condition occurs, the close() function returns -1 and sets errno to this
value:
EBADF fildes is not a valid file descriptor.
EIO I/O error occurred while writing the file.
5–14 7859 6137–009

closedir()
Application
closedir()
Use the closedir() function to close an open directory stream and make it inaccessible to
the calling process. If no other processes share this directory stream, access to the
stream is closed.
If a process terminates, all effects of closedir() occur for each directory stream open to
the process.
See opendir() for opening directory, readdir() for reading the next directory entry, and
rewinddir() for repositioning the stream at its beginning.
Synopsis
int closedir(DIR * dirp);
Description
The closedir() function closes access to the directory stream by the calling process,
where dirp designates the directory stream to close. The directory stream must have
been opened previously by the opendir() function.
Return Values
If the closedir() function completes successfully, it does the following:
• Updates the st_atime field of the directory
• Returns 0
Otherwise, closedir() sets errno to identify the specific error and returns -1.
Error Codes
If any of the following conditions occurs, the closedir() function returns -1 and sets errno
to the corresponding value:
EBADF dirp is not a valid directory stream
EFAULT dirp is not a valid pointer.
7859 6137–009 5–15

creat()
creat()
Application
Use the creat() function to create and open a new regular file, specifying how you can
access it and setting its file permissions.
Synopsis
int creat(const char * path, mode_t mode);
Description
The creat() function call is the same as a special case of open(), as follows:
open(path, O_WRONLY | O_CREAT | O_TRUNC, mode)
See the open() function for details of the path and mode arguments.
Caution
Using creat() when a file of the same name exists truncates the file's length
to 0.
Return Values
If the creat() function completes successfully, it returns the file descriptor for the new
file. Otherwise, creat() sets errno to identify the specific error and returns -1.
Error Codes
If any of the following conditions occurs, the creat() function returns -1 and sets errno to
the corresponding value:
E1100FILE The system could not assign the OS 2200 file that contains the
file's data space.
EACCES Either of the following errors occurred:
• The calling process is denied search permission on a directory
in the path name.
• The calling process is denied write permission for the file or the
parent directory of the file.
EAGAIN An attempt to create and open an imported file failed because the
corresponding OS 2200 file existed but was rolled out or otherwise
unavailable. This is a temporary condition; a subsequent attempt
might succeed.
EFAULT The pointer specified by path is invalid.
EINTR The create operation was interrupted by a signal.
5–16 7859 6137–009

EINVAL mode has undefined bits set.
EIO An input/output error prevented completion of the request.
EISDIR The path name resolves to a directory.
EMFILE The calling process cannot create the file because the limit on the
maximum number of open file descriptors for a process would be
exceeded.
ENOENT Either of the following errors occurred:
• A directory in the path name does not exist.
• path points to an empty string.
ENOSPC The directory or file system that is to contain the new file is out of
available space.
ENOTDIR A component of the path name prefix is not a directory.
creat()
7859 6137–009 5–17

dup()
dup()
Application
Use the dup() function to create an additional file descriptor for an existing open file
description. This capability is important for redirecting standard files to a pipe, for
example. The new file descriptor has the following properties:
• Its value is the lowest number available for the process.
• It shares the same open file description and file locks with the original file descriptor.
You can also duplicate a file descriptor with the F_DUPFD option to the fcntl() function.
See dup2() for associating a specific file descriptor with an open file description.
Synopsis
int dup(int fildes);
Description
The dup() function duplicates the file descriptor designated by fildes. The duplicated file
descriptor occurs in the first available file descriptor location.
Diagram
The following diagram shows a duplicated file descriptor for an open file description:
Process
Return Values
If the dup() function completes successfully, it returns the index of the newly created file
descriptor. Otherwise, dup() sets errno to identify the specific error and returns -1.
Error Codes
dup( )
File
Descriptor
fildes
Open File
Description
If any of the following conditions occurs, the dup() function returns -1 and sets errno to
the corresponding value:
EBADF fildes is not a valid open file descriptor.
EMFILE The calling process would exceed the maximum number of file
descriptors allowed.
5–18 7859 6137–009
File

dup2()
Application
dup2()
Use the dup2() function to associate a specific file descriptor index with an existing open
file description. The new file descriptor shares the same open file description and file
locks with the original file descriptor. See dup() for creating an additional file descriptor
for the open file description.
Synopsis
int dup2(int fildes1, int fildes2);
Description
The dup2() function causes the file descriptor fildes2 to identify the same open file
description as fildes1.
If fildes2 exists and corresponds to an open file other than fildes1, dup2() first closes
fildes2 (which can remove locks and the file itself; see the close() function). If fildes1 and
fildes2 are equal, dup2() does not duplicate or close any file descriptors.
Diagram
The following diagram shows a specific file descriptor associated with an open file
description:
Return Values
If the dup2() function completes successfully, it returns the value of fildes2, a file
descriptor. Otherwise, dup2() sets errno to identify the specific error and returns -1.
Error Codes
File
Descriptor
fildes1
fildes2
dup2( )
Open File
Description
If the following condition occurs, the dup2() function returns -1 and sets errno to the
corresponding value:
EBADF One of the following errors occurred:
• fildes1 is not a file descriptor.
• fildes2 is either negative or greater than the maximum number of
file descriptors allowed.
7859 6137–009 5–19
File

end_process()
end_process()
Application
Use _cifs_end_process (and _cifs_new_process) to group activities into logical
processes, where all activities (threads) of a process share a set of open files.
Note: There is no POSIX equivalent to _cifs_end_process.
Synopsis
int _cifs_end_process();
Description
See new_process(), later in this section.
5–20 7859 6137–009

fclose()
Application
fclose()
Use the fclose() function to write all remaining data in the buffer to a file and close the
file.
Synopsis
int fclose(FILE * stream);
Description
The fclose() function flushes any output buffer for a stream and closes the associated
file, where:
FILE
stream
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object. If this object was automatically allocated, fclose()
deallocates it.
Return Values
The fclose() function returns 0 if it successfully closes the stream. Otherwise, if it
detects errors or if the stream was already closed, fclose() returns a nonzero value.
7859 6137–009 5–21

fcntl()
fcntl()
Application
Use the fcntl() function to manage an open file in the following ways, which are
described in following subsections:
• Duplicate a file descriptor; see “File Descriptor Services.”
• Retrieve information about or change the values of the file status flags and access
specification; see “File Status Flags and Access Specification Services.”
• Manage advisory record locking services; see “Record Locking Services.”
Synopsis
int fcntl(int fildes, int cmd, ...);
Description
The fcntl() function performs file services, where:
fildes
cmd
is a file descriptor for an open file.
indicates which service to perform. It can have any value in the following table.
Service
Duplicate file
descriptor
Get flags and
information
Set flags and
information
*Wait if blocked
File
Descriptor
File Status and
Access
Specification
F_DUPFD – –
– F_GETFL
F_GETFD
– F_SETFL
F_SETFD
Advisory Record
Locking
F_GETLK
F_SETLK,
F_SETLKW*
See the following subsections for detailed information about each type of service.
parm-3
is an optional argument of varying type whose value depends on cmd, as shown in
the following table (see the following descriptions of the symbolic names for more
information about parm-3):
5–22 7859 6137–009

If cmd is ... Then parm-3 is ...
fcntl()
F_DUPFD An integer giving the smallest desired value for the new file descriptor
F_GETFD,
F_GETFL
F_SETFD,
F_SETFL
F_GETLK,
F_SETLK,
F_SETLKW
Incorrect Third Argument
Not required; ignored if supplied
An integer giving the new setting for the close_on_exec or status flags
for the specified file descriptor
A pointer to the flock structure that describes the locking request (can
be used to unlock or change an existing lock)
The fcntl function fails if parm-3 is required (that is, if cmd is F_DUPFD, F_GETLK,
F_SETFD, F_SETFL, F_SETLK, or F_SETLKW) but does not exist.
Caution
fcntl() cannot determine if the third argument has the wrong type. Even if the
type is incorrect, fcntl() interprets the storage as the correct type, resulting in
undefined and unpredictable behavior.
Return Values
If the fcntl() function completes successfully, its return value depends on cmd, as
follows:
If cmd is ... Then fcntl() returns ...
F_DUPFD A new file descriptor
F_GETFD,
F_GETFL
Any other value 0
The values of the file status flags and file access
specifications
Otherwise, fcntl() sets errno to identify the specific error and returns -1.
7859 6137–009 5–23

fcntl()
Error Codes
If any of the following conditions occurs, the fcntl() function returns -1 and sets errno to
the corresponding value:
EAGAIN cmd is F_SETLK and one of the following is true:
• l_type is F_WRLCK and another process owns a lock on some
portion of the segment to be locked.
• l_type is F_RDLCK and another process owns an exclusive lock
on some portion of the segment to be locked.
EBADF Any of the following errors occurred:
• fildes is not a valid file descriptor.
• The following conditions are all true:
− cmd is F_SETLK or F_SETLKW.
− l_type is F_RDLCK.
− fildes is not a file descriptor open for reading.
• The following conditions are all true:
− cmd is F_SETLK or F_SETLKW.
− l_type is F_WRLCK.
− fildes is not a file descriptor open for writing.
EDEADLK Both of the following conditions occurred:
• cmd is F_SETLKW.
• Suspending the process because of a conflict with the request
would cause a deadlock.
EFAULT Both of the following conditions occurred:
• cmd is F_GETLK, F_SETLK, or F_SETLKW.
• parm-3 is not a valid pointer.
EINTR Both of the following conditions occurred:
• cmd is F_SETLKW.
• The process received a signal before the locking request was
granted.
5–24 7859 6137–009

EINVAL Any of the following errors occurred:
• cmd is not one of the valid values listed.
• cmd is F_DUPFD and parm-3 is less than 0 or greater than or
equal to the maximum number of open files.
fcntl()
• cmd is F_GETLK, F_SETLK, or F_SETLKW, and the flock structure
to which parm-3 points is invalid.
• cmd is F_SETFD, and the value of parm-3 is not 0 or
FD_CLOEXEC.
• cmd is F_DUPFD, F_SETFL, F_GETLK, F_SETLK, or F_SETLKW
and parm-3 is not specified.
• cmd is F_SETFL, and the value of parm-3 has undefined bits set.
EMFILE Both of the following conditions occurred:
• cmd is F_DUPFD.
• No file descriptors greater than or equal to parm-3 are available.
ENOLCK Both of the following conditions occurred:
The flock Structure
• cmd is either F_SETLK or F_SETLKW.
• Satisfying the lock or unlock request results in the number of
locked regions for the process exceeding the maximum number
of locks allowed for a process.
The flock structure provides information to the kernel about the locking request. It also
gives the process information about existing locks. The following table describes the
flock structure, which is defined in :
Member
Name
Member
Type Description Values
l_len off_t Number of consecutive
bytes to be locked or
unlocked
l_pid pid_t Process ID of process
owning a conflicting lock
l_start off_t Distance to the first byte
in the lock from the
address specified by
l_whence
If positive, l_len bytes; if 0,
to the end of the file
(cannot be negative)
Returned by F_GETLK
Any integer (positive,
negative, or 0) A,B
7859 6137–009 5–25

fcntl()
Member
Name
Member
Type Description Values
l_type short int Request type, one of
• Exclusive lock
• Shared lock
• Unlock
l_whence short int File address at which to
add l_start to find the first
byte in the lock; either
• Current position
• End of file
• Beginning of file
F_WRLCK, F_RDLCK,
F_UNLCK C
SEEK_CUR, SEEK_END,
SEEK_SET D
A – The result of applying l_start to l_whence must be ≥0. That is, the starting position of the lock
cannot be before the beginning of the file.
B – If an F_GETLK request finds a conflicting lock, the value of l_start identifies the first byte of
the conflicting lock relative to the beginning of the file.
C – If an F_GETLK request does not find a conflicting lock, the kernel changes the value of l_type
to F_UNLCK.
D – If an F_GETLK request finds a conflicting lock, the value of l_whence is SEEK_SET.
Illustration
Values in the flock structure determine how and where a lock is created on a file. Given
specific values for the starting offset position (l_start) and length (l_len) of a desired lock,
the value of l_whence determines whether the lock occurs at the beginning, current
position, or end of a file, as shown in the following diagram:
5–26 7859 6137–009

Locking and Unlocking Whole Files
fcntl()
A process can lock or unlock an entire file if it sets a lock of zero length and zero offset
that starts at the beginning of the file, as shown by the following values:
• l_len = 0
• l_start = 0
• l_whence = SEEK_SET
Replacing and Merging Locks
A successful F_SETLK or F_SETLKW request replaces the previous lock type for each
byte in the specified region with the new lock type. Before returning, fcntl() merges
adjacent locks of the same type that are owned by the requesting process.
For example, suppose a process owns shared locks on bytes 0 through 5 and bytes 7
through 9 in a file. The process requests a shared lock on byte 6 (or on a range including
byte 6). The result is a single shared lock on bytes 0 through 9.
File Descriptor Services
The symbolic names in this subsection are the values for cmd that allow fcntl() to
duplicate a file descriptor (F_DUPFD)
F_DUPFD—Duplicate File Descriptor
This service requires an integer type for parm-3. The fcntl() function creates and returns a
new file descriptor with the following characteristics:
• It is greater than or equal to parm-3.
• It refers to the same open file description as fildes.
File Descriptor Closure Mode Services
The cmd settings in this subsection allow a program to control the disposition of open
file descriptors when _cifs_new_process() creates a child process.
F_GETFD—Get File Descriptor Closure Mode
This service of the fcntl() function returns the setting of the close_on_exec field of the
specified file descriptor. The return value is either 0 (file descriptor is copied to the new
process) or FD_CLOEXEC (file descriptor is not copied to the new process).
F_SETFD—Set File Descriptor Closure Mode
This service of the fcntl() function requires an integer type for parm-3 containing either 0
or FD_CLOEXEC. No other values are permitted.
File Status Flags and Access Specification Services
The symbolic names in this subsection are the values for cmd that allow fcntl() to
• Retrieve the file status flags and file access specification (F_GETFL)
• Set the file status flags (F_SETFL)
7859 6137–009 5–27

fcntl()
File status flags and the file access specification are associated with an open file
description. They do not indicate anything about other open file descriptions that
reference the same file.
F_GETFL—Get File Status Flags and Access Specification
The fcntl() function returns the following values associated with fildes (see the open()
function for descriptions of its symbolic names):
File Attribute Value Description
File status flags O_APPEND
O_DSYNC
File access
specification
O_NONBLOCK
O_SYNC
O_RDONLY
O_RDWR
O_WRONLY
Append mode
Synchronize file data on read and write
operations
No delay
Synchronize file data and access times on read
and write operations
Open for reading
Open for reading and writing
Open for writing
parm-3 is not required for this service and is ignored if supplied.
O_ACCMODE, which is defined in , is a mask that references all of the file
access flags. By using O_ACCMODE to mask portions of the fcntl() result, you can
determine the file access specification and file status flags from the fcntl() result. See
the examples in this subsection for coding details.
F_SETFL—Set File Status Flags
This service requires an integer type for parm-3 containing the new settings for the file
status flags in the open file description associated with fildes. For this service, fcntl()
ignores other bits in parm-3.
If the result of an AND operation between parm-3 and a file status constant is zero,
fcntl() clears the corresponding file status flag in the open file description; otherwise,
fcntl() sets the flag. In other words, you must set the flag in parm-3 if you want it set in
the open file description; if the flag is not set in parm-3, it is cleared in the open file
description. The following constants set the corresponding file status flag:
• O_APPEND
• O_DSYNC
• O_NONBLOCK
• O_SYNC
If both the O_DSYNC and O_SYNC flags are set (see the open() function), the effect is
the same as if only O_SYNC is set.
Calling fcntl() with F_GETFL
The following code shows how to call fcntl() to get the file status flags and file mode,
where fd_a is an existing file descriptor:
5–28 7859 6137–009

int fd_a;
int result_a;
result_a = fcntl(fd_a, F_GETFL);
Interpreting the Results of Calling fcntl() with F_GETFL
fcntl()
To extract the file access specification from the result of F_GETFL, do an AND operation
between the result and O_ACCMODE:
int access_bits;
access_bits = result_a & O_ACCMODE
To extract the file status flags from the result of F_GETFL, do an AND operation
between the result and the complement of O_ACCMODE:
int status_bits;
status_bits = result_a & ~O_ACCMODE;
To determine if the file is open for reading from the result of F_GETFL, do an AND
operation between the result and O_RDONLY:
if (result_a & O_RDONLY)
{ .
. /* Code for readable file */
}
.
To determine if the file is open for appending data from the result of F_GETFL, do an
AND operation between the result and O_APPEND:
if (result_a & O_APPEND)
{ .
. /* Code for appending data */
.
}
7859 6137–009 5–29

fcntl()
Calling fcntl() with F_SETFL
The following code shows how to call fcntl() to set the O_APPEND, O_NONBLOCK, and
O_SYNC file status flags and clear the O_DSYNC flag, where fd_a is an existing file
descriptor:
int status_flags = O_APPEND | O_NONBLOCK | O_SYNC;
fcntl(fd_a, F_SETFL, status_flags);
Record Locking Services
The symbolic names in this subsection are the values for cmd that allow fcntl() to
retrieve (F_GETLK) or set (F_SETLK and F_SETLKW) advisory record locks on any file or
directory. They require parm-3 to point to a flock structure.
F_GETLK—Get Record-Locking Information
The fcntl() function searches for a lock owned by another process that conflicts with the
lock description (shared or exclusive) in the flock structure indicated by parm-3. That is,
the type and location of an existing lock would prevent the requested lock from being
created. The behavior of fcntl() depends on whether a conflicting lock exists, as follows:
• A conflicting lock exists; fcntl() does the following:
− Overwrites the flock structure with the information retrieved about the
conflicting lock
− Sets l_start to the first byte of the conflicting lock, relative to the beginning of
the file
− Sets l_whence to SEEK_SET
• No conflicting lock exists; fcntl() does the following:
− Sets l_type to F_UNLCK
− Leaves the rest of the flock structure unchanged
If parm-3 points to a structure whose l_type field is F_UNLCK, it is not possible for a lock
conflict to arise. Therefore, fcntl() behaves the same as the second case.
Conclusions About Using F_GETLK
You can draw the following conclusions about using F_GETLK:
• If you request an exclusive or shared lock and fcntl() returns a structure whose l_type
field is F_UNLCK, then no conflicting lock existed at the time of the call. However,
this does not guarantee that no conflicting lock exists if you try to set the same lock
using F_SETLK, because another process can establish a conflicting lock in the
interim.
• An appropriate use for F_GETLK is to determine more information about a lock that
conflicts with your request to set a lock with F_SETLK. In particular, the process ID
of the owner of the conflicting lock might be useful, depending on the application.
• If your request has lock type F_UNLCK, using F_GETLK is meaningless.
5–30 7859 6137–009

F_SETLK—Set Record-Locking Information
fcntl()
The fcntl() function sets or clears a lock on a file segment according to the description in
the flock structure indicated by parm-3, as shown in the following table (the symbolic
names are defined in ):
If l_type is ... Then fcntl() uses l_whence, l_start, and l_len to ...
F_RDLCK Establish a shared lock.
F_WRLCK Establish an exclusive lock.
F_UNLCK Remove any locks in the indicated range.
If fcntl() cannot set the requested lock because of conflicts with existing locks, it fails.
F_SETLKW—Set Record-Locking Information; Wait If Blocked
This service is the same as F_SETLK, except that the process waits until the request can
be satisfied or is interrupted. If the process is interrupted while waiting for a region to be
unlocked, fcntl() fails and the lock is not created.
Calling fcntl() with F_SETLK
The following code shows how to call fcntl() to set an exclusive lock at the current
read/write position in the file, where fd_a is an existing file descriptor:
struct flock lock_to set;
lock_to_set.l_len = 12;
lock_to_set.l_start = 0;
lock_to_set.l_type = F_WRLCK;
lock_to_set.l_whence = SEEK_CUR;
fcntl(fd_a, F_SETLK, &lock_to_set);
Modifying Existing Locks
If the calling process already has locks covering part of the segment indicated by the lock
description, fcntl() modifies these locks as necessary. For example, if the process owns
an exclusive lock on the first 10 bytes of the file and requests a shared lock on byte 5
(l_start = 5), it then owns 3 distinct locks, as follows:
• An exclusive lock on bytes 0 through 4
• A shared lock on byte 5
• An exclusive lock on bytes 6 through 9
7859 6137–009 5–31

fcntl()
Clearing Existing Locks
You can clear all 3 locks in the previous example by unlocking the first 10 bytes of the
file, as follows:
struct flock lock_to_set;
lock_to_set.l_len = 10;
lock_to_set.l_start = 0;_
lock_to_set.l_type = F_UNLCK;
lock_to_set.l_whence = SEEK_SET;
fcntl(fd_a, F_SETLK, &lock_to_set);
5–32 7859 6137–009

fdatasync()
Application
fdatasync()
Use the fdatasync() function to write to the device all data currently in a portion of the
buffer cache for a file, thus protecting the data against loss due to a system outage. With
fdatasync(), an application can synchronize all file updates at one time, instead of on
every read or write operation. However, fdatasync() does not synchronize file access
times.
For a similar function that does synchronize file access times, see the fsync() function.
For alternate methods of synchronizing disk data, see the discussions of the O_SYNC
and O_DSYNC flags under the open() and fcntl() functions.
Synopsis
int fdatasync(int fildes);
Description
The fdatasync() function writes from the buffer cache to the device all data belonging to
the specified file, where fildes specifies a regular file open for writing. The data written is
that portion of the buffer cache associated with the file referenced by fildes.
Return Values
If the fdatasync() function completes successfully, it returns 0. Otherwise, fdatasync()
sets errno to identify the specific error and returns -1.
Error Codes
If any of the following conditions occurs, the fdatasync() function returns -1 and sets
errno to the corresponding value:
EBADF fildes is not a valid file descriptor open for writing.
EINVAL Data synchronization is not supported for the type of file
described by fildes.
EIO The file could not be fully synchronized because of an I/O error.
7859 6137–009 5–33

fdopen()
fdopen()
Application
Use the fdopen() function to create a stream and associate a file descriptor with it.
Synopsis
FILE * fdopen(int fildes, const char * type);
Description
The fdopen() function creates a stream and associates a file descriptor with the stream,
where:
FILE
fildes
type
is an opaque data type that describes an open instance of a file.
is the file descriptor to associate with the stream.
is a character string specifying the access mode for the file. It is the same as the
type argument for the fopen() function. It must be a subset of the access mode of
the initial open() function.
The access mode prefixes “w” and “w+” do not cause truncation of the file. The file
position indicator is set to the position indicated by the file offset associated with the file
descriptor. Error and end-of-file indicators are cleared.
Return Values
If the fdopen() function completes successfully, it does the following:
• Does not change the st_atime field
• Returns a pointer to a stream
Otherwise, fdopen() sets errno to identify the specific error and returns a null pointer.
Error Codes
If the following condition occurs, the fdopen() function returns -1 and sets errno to the
corresponding value:
EINVAL type is not a subset of the access mode of the initial open() function.
5–34 7859 6137–009

feof()
Application
Use the feof() function to test whether a stream is at end of file.
Synopsis
int feof(FILE * stream);
Description
The feof() function tests the end-of-file indicator for a stream, where:
FILE
stream
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object.
Return Values
The feof() function returns a nonzero value if the end-of-file indicator is set.
feof()
7859 6137–009 5–35

ferror()
ferror()
Application
Use the ferror() function to test whether a read/write error occurred.
Synopsis
int ferror(FILE * stream);
Description
The ferror() function tests the read/write error indicator for a stream, where:
FILE
stream
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object.
Return Values
The ferror() function returns a nonzero value if the read/write error indicator is set.
5–36 7859 6137–009

fflush()
Application
fflush()
Use the fflush() function to write all remaining data in the buffer to a file without closing
the file.
Synopsis
int fflush(FILE * stream);
Description
The fflush() function causes any unwritten data for an output stream to be written to the
file, where:
FILE
stream
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object.
Return Values
The fflush() function returns a nonzero value if a write error occurs.
7859 6137–009 5–37

fgetc()
fgetc()
Application
Use the fgetc() function to obtain the next character from an input stream.
Synopsis
int fgetc(FILE * stream);
Description
The fgetc() function obtains the next character (if present) from an input stream, where:
FILE
stream
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object that fgetc() reads as unsigned char characters.
The fgetc() function converts the character to an int and advances the associated file
position indicator, if defined. The fgetc() function is not implemented as a macro.
Return Values
The fgetc() function returns the next character from the specified input stream. If the
stream is at end of file, fgetc() sets the end-of-file indicator and returns EOF. If a read
error occurs, fgetc() sets the error indicator and returns EOF.
5–38 7859 6137–009

fgetpos()
Application
Use the fgetpos() function to obtain the current value of the file position indicator.
Synopsis
int fgetpos(FILE * stream, fpos_t * pos);
Description
The fgetpos() function obtains the current value of the file position indicator, where:
FILE
stream
pos
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object.
is a pointer to a structure in which the value is returned.
The fsetpos() function can use this structure.
Return Values
fgetpos()
If it completes successfully, the fgetpos() function returns 0. Otherwise, fgetpos() sets
errno to indicate the error and returns a nonzero value.
7859 6137–009 5–39

fgets()
fgets()
Application
Use the fgets() function to read the next characters from an input stream into an array.
Synopsis
char * fgets(char * s, int n, FILE * stream);
Description
The fgets() function reads the next n-1 characters from an input stream into an array,
where:
s
n
FILE
stream
is a pointer to the array that stores the characters read. A nul character is written
immediately after the last character read into the array.
specifies one more than the number of characters to read. That is, fgets() reads at
most n-1 characters.
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object to read. No additional characters are read after a new line
indicator (that is retained) or after end of file.
Return Values
If it completes successfully, the fgets() function returns s. If end of file is encountered
and no characters have been read into the array, the contents of the array remain
unchanged and fgets() returns a null pointer. If a read error occurs during the operation,
the array contents are indeterminate and fgets() returns a null pointer.
5–40 7859 6137–009

fileno()
Application
Use the fileno() function to retrieve a file descriptor for a specific data stream.
Synopsis
int fileno(FILE * stream);
Description
The fileno() function retrieves a file descriptor, where:
FILE
stream
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object associated with the file descriptor.
Return Values
If the fileno() function completes successfully, it returns a file descriptor. Otherwise,
fileno() sets errno to identify the specific error and returns -1.
Error Codes
fileno()
If any of the following conditions occurs, the fileno() function returns -1 and sets errno to
the corresponding value:
EFAULT The pointer specified by stream is invalid.
EINVAL The stream to which stream points is invalid.
7859 6137–009 5–41

fopen()
fopen()
Application
Use the fopen() function to open a path name and associate a stream with it.
Synopsis
FILE * fopen(const char * pathname, const char * type);
Description
The fopen() function opens a path name and associates a stream with it, where:
FILE
is an opaque data type that describes an open instance of a file.
pathname
type
is a pointer to the path name to open.
is a pointer to a string that begins with one of the sequences in the following table.
Additional characters, separated from the given sequences by a comma, may follow
these, but fopen() ignores them. The sequences may be in upper or lower case,
although upper case might not be portable to other platforms.
Sequence Description
r Open existing text file for reading.
w Create file for writing or truncate to 0 length.
a Append; open file or create for writing at end-of-file.
rb Open existing binary file for reading.
wb Create binary file for writing or truncate to 0 length.
ab Append; open binary file or create for writing at end-of-file.
r+ Open existing file for update (reading and writing).
w+ Create file for update or truncate to 0 length.
a+ Append; open file or create for update, writing at end-of-file.
r+b or rb+ Open existing binary file for update (reading and writing).
w+b or wb+ Create binary file for update or truncate to 0 length.
a+b or ab+ Append; open binary file or create for update, writing at endof-file.
5–42 7859 6137–009

fopen()
Note: The letter b in the type sequence is effective only when a file is created. In all
other cases, the file retains its existing type (SDF or binary), and b, if present, is ignored.
Appending Data to a File
Opening a file with append mode (a, ab, a+, or a+b) forces all subsequent writes to the
file to the current end of file, regardless of previous calls to the fseek() function.
Updating a File
When you open a file for update, you can perform both input and output operations on
the associated stream. However, an output operation cannot be directly followed by an
input operation without an intervening call to fseek(), rewind(), or fflush(). Similarly, an
input operation cannot be directly followed by an output operation without an intervening
call to fseek() or rewind(), unless the input operation encounters the end of the file.
Default Permissions When Creating a File
If the fopen() function creates a file, it assigns read and write permissions to the owner,
group, and other permission classes by default. The following file mode specification for
the open() function is equivalent:
S_IRUSR | S_IWUSR | S_IWGRP | S_IROTH | S_IWOTH
Return Values
If it completes successfully, the fopen() function returns a pointer to the object
controlling the stream. Otherwise, fopen() returns a null pointer.
7859 6137–009 5–43

fprintf()
fprintf()
Application
Use the fprintf() function to write formatted output.
Synopsis
int fprintf(FILE * stream, const char * format, ...);
Description
The fprintf() function writes formatted output, where:
FILE
stream
format
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object for the output. A formatted output string can have a
maximum of 32,767 characters.
is a pointer that controls the output by specifying how subsequent arguments are
converted before being output.
Format Strings
A format string contains two types of objects:
• Plain characters
Plain characters are copied unchanged to the output stream.
• Conversion specifications
Each conversion specification results in fetching 0 or more subsequent arguments.
If the format is exhausted while arguments remain, the excess arguments are evaluated
but otherwise ignored. The fprintf() function returns when it encounters the end of the
format string.
Conversion Specifications
Each conversion specification is introduced by the percent (%) character. After the %
character, the following characters appear in sequence:
1. An optional field, integer$, where integer is a decimal integer value specifying the
next argument to be converted for output.
2. Zero or more flags that modify the meaning of the conversion specification.
5–44 7859 6137–009

fprintf()
3. An optional decimal integer, other than 0, specifying a minimum field width. If the
converted value has fewer characters than the field width, it is padded with spaces
on the left to the field width (or on the right if the left adjustment flag is specified).
Note: If the first character after the percent (%) sign is 0, then it is a flag character,
not a field width.
4. An optional precision, in the form of a period (.) followed by an optional decimal
integer. If the integer is omitted, it is treated as 0. The padding specified by the
precision overrides the padding specified by the field width. The precision specifies
the following number:
a. For d, i, o, u, x, and X conversions, the minimum number of digits to appear
b. For e, E, and f conversions, the number of digits to appear after the decimal
point
c. For g and G conversions, the maximum number of significant digits
d. For s conversions, the maximum number of characters to be printed from a
string
5. An optional h, l, L, or ll (lowercase double L) format character, which must appear as
follows:
a. h
b. l
c. L
d. ll
This letter specifies that a following d, i, o, u, x, or X conversion specifier applies
to a short int or an unsigned short int argument. It means the argument has
been promoted according to the integral promotions and its value is cast to short
or unsigned short before printing.
This letter specifies that a following d, i, o, u, x, or X conversion specifier applies
to a long int or an unsigned long int argument. This letter specifies that a
following n conversion specifier applies to a pointer to a long int argument.
This letter specifies that a following e, E, f, g, or G conversion specifier applies to
a long double argument.
If h, l, or L appears with any other conversion specifier, it is ignored.
These letters (lowercase double L) specify that a following d, I, o, x, or X
conversion specifier applies to a long long int argument.
6. A character that specifies the type of conversion to be applied.
A field width or precision, or both, can be indicated by an asterisk (*) instead of a digit
string. In this case, an int argument supplies the field width or precision. The arguments
specifying field width or precision must appear before the argument (if any) to be
converted. A negative field width argument is read as a - flag followed by a positive field
width. A negative precision argument is the same as if it were omitted.
7859 6137–009 5–45

fprintf()
Precision and width can also be indicated by an asterisk (* ) followed by a decimal
integer and the $ character, where the decimal integer specifies the position in the
argument list of the integer argument containing the field width or precision.
The following table lists the flag characters and their meanings.
Flag
Character Description
- The result of the conversion is left justified within the field.
+ The result of a signed conversion always begins with a plus or minus sign.
Space If the first character of a signed conversion is not a sign, a space is placed before
the result. If the space and + flags both appear, the space flag is ignored.
# The result is converted to an alternate form. For c, d, i, s, and u conversions, the
flag has no effect.
For o conversion, it increases the precision to force the first digit of the result to
be 0.
For x and X conversions, a nonzero result has 0x or 0X placed before it. For e, E,
f, g, and G conversions, the result always contains a decimal point, even if no
digits follow the decimal point (normally, a decimal point appears in the result of
these conversions only if a digit follows it). For g and G conversions, trailing 0s
are not removed from the result, as they normally are.
Note: Other compilers that conform to American National Standard C might not
ignore the # flag with c, d, i, s, or u conversions. For maximum portability, do not
use the # flag with these conversions.
0 For numeric conversions (d, i, o, u, x, X, e, E, f, g, G), the field width is padded
with leading zeros following any indication of sign or base; the field is not padded
with spaces.
If the 0 and - flags both appear, the 0 flag is ignored. For d, i, o, u, x, and X
conversions, the 0 flag is ignored if a precision is specified. For other conversions,
the behavior is undefined if a precision is specified.
Note: If the first character after the percent (%) sign is 0, then this character is a
zero flag, not a field width.
5–46 7859 6137–009

The following table lists the conversion specifiers and their meanings.
Specifier Description
c The least significant byte of the int argument is converted to a character
and printed.
d, i, o, u, x,
X
fprintf()
The int argument is converted to signed decimal (d or i), unsigned octal
(o), unsigned decimal (u), or unsigned hexadecimal notation (x or X). The
letters abcdef are used for x conversion and the letters ABCDEF for X
conversion. The precision specifies the minimum number of digits to
appear. If the value being converted can be represented in fewer digits, it
is expanded with leading 0s. The default precision is 1. The result of
converting a 0 value with a precision of 0 is no characters.
e, E The double argument is converted in the style [-]d.ddde+dd, where one
digit occurs before the decimal point and the number of digits after the
decimal point is equal to the precision.
When the precision is missing, 6 digits are produced. If the precision is 0,
no decimal point appears. The value is rounded to the appropriate number
of digits.
The E format code produces a number with E instead of e introducing the
exponent. The exponent always contains at least 2 digits. However, if the
magnitude to print is greater than or equal to 1E+100, additional exponent
digits are printed as necessary.
f The double argument is converted to decimal notation in the style
[-]ddd.ddd, where the number of digits after the decimal point is equal to
the precision specification.
If the precision is missing, it is taken as 6; if the precision is explicitly 0, no
decimal point appears. If a decimal point appears, at least one digit
appears before it. The value is rounded to the appropriate number of
digits.
g, G For the g format code, the double argument is printed in style f or e. For a
G format code, it is printed in style E. In each style, the precision specifies
the number of significant digits.
The style used depends on the value converted. Style e is used only if the
exponent resulting from the conversion is less than -4 or greater than the
precision. Trailing zeros are removed from the result. A decimal point
appears only if it is followed by a digit.
n The argument is taken to be an (int *) pointer to an integer into which is
written the number of characters written to the output stream so far by
this call to fprintf. No argument is converted.
p The argument is taken to be a (void *) pointer to an object. The value of
the pointer is printed as 24 octal digits.
7859 6137–009 5–47

fprintf()
Specifier Description
s The argument is taken to be a (char *) pointer to a string. Characters from
the string are written up to but not including the terminating NUL, or until
the number of characters indicated by the precision is written. If the
precision is missing, it is taken to be arbitrarily large so that all characters
before the first NUL are printed.
The maximum number of characters that can be printed for one %s
conversion is 6999.
% The character % is printed. No argument is converted.
Considerations for Conversion Specifications
If the conversion specifier is not one of the characters in the above table, character is
printed and no argument is converted.
If any argument is or points to an aggregate (except for an array of characters using %s
conversion or any pointer using %p conversion), the behavior is undefined.
A nonexistent or small field width does not cause truncation of a field. If the conversion
result is wider than the field width, the field is expanded to contain the conversion result.
Return Values
If it completes successfully, the fprintf() function returns the number of characters
transmitted. Otherwise, fprintf() returns a negative value.
Examples
Print a date and time in the form “Tuesday, July 3, 10:02,” where weekday and month
are pointers to strings:
fprintf(stdout, "%s, %s %d, %.2d:%.2d\n", weekday, month, day, hour, min);
Print pi to five decimal places:
fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));
5–48 7859 6137–009

fputc()
Application
Use the fputc() function to write a character to an output stream.
Synopsis
int fputc(int c, FILE * stream);
Description
The fputc() function writes a character to an output stream, where:
c
FILE
stream
specifies the character to write, after conversion to an unsigned char.
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object for output.
fputc()
The fputc() function writes the character at the position indicated by the associated file
position indicator (if defined), advancing the indicator appropriately. If the file position
indicator is not defined, the character is appended to the output stream.
The fputc() function is not implemented as a macro.
Return Values
If it completes successfully, the fputc() function returns the character written. If a write
error occurs, fputc() sets the error indicator and returns EOF.
7859 6137–009 5–49

fputs()
fputs()
Application
Use the fputs() function to write a string to an output stream.
Synopsis
int fputs(const char * s, FILE * stream);
Description
The fputs() function writes a string to an output stream, where:
s
FILE
stream
is a pointer to the string to write. The terminating nul character is not written.
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object for output.
Return Values
If it completes successfully, the fputs() function returns the number of characters
written. Otherwise, fputs() returns EOF.
5–50 7859 6137–009

fread()
Application
Use the fread() function to read elements from an input stream into an array.
Synopsis
size_t fread(void * ptr, size_t size, size_t nelem, FILE * stream);
Description
The fread() function reads elements from an input stream into an array, where:
ptr
size
nelem
FILE
stream
is a pointer to the array.
specifies the size of an element in the array.
specifies the number of elements to attempt to read.
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object for input.
fread()
The fread() function advances the file position indicator (if defined) by the number of
bytes successfully read. If an error occurs, the resulting value of the file position indicator
is indeterminate. If a partial element is read, its value is indeterminate. Use either the
ferror() or feof() function to distinguish between a read error and end of file.
Return Values
If it completes successfully, the fread() function returns the number of elements read;
this number can be less than nelem if a read error or end of file occurs. If either size or
nelem is 0, fread() returns 0 and both the contents of the array and the state of the input
stream remain unchanged.
7859 6137–009 5–51

freopen()
freopen()
Application
Use the freopen() function to open a path name and associate a stream with it. This
function first attempts to close a file associated with the stream.
The primary use of freopen() is to change the file associated with a standard text stream
(stderr, stdin, or stdout) since those identifiers are not values that may be modified by
the fopen() function.
Synopsis
FILE * freopen(const char * path, const char * type, FILE * stream);
Description
The freopen() function opens a path and associates a stream with it, where:
FILE
path
type
stream
is an opaque data type that describes an open instance of a file.
is a pointer to the path name to open.
is a pointer to a string that begins with one of the sequences in the table in fopen().
Additional characters can follow these sequences, but freopen() ignores them.
is a pointer to a FILE object to associate with the path name.
The freopen() function first attempts to close any file associated with the specified
stream, ignoring any failure to close the file successfully.
Default Permissions When Creating a File
If the freopen() function creates a file, it assigns read and write permissions to the
owner, group, and other permission classes by default. The following file mode
specification for the open() function is equivalent:
S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH
Return Values
If it completes successfully, the freopen() function returns the value of stream.
Otherwise, freopen() returns a null pointer.
5–52 7859 6137–009

fscanf()
Application
Use the fscanf() function to read formatted input.
Synopsis
int fscanf(FILE * stream, const char * format, ...);
Description
The fscanf() function reads formatted input, where:
FILE
stream
format
is an opaque data type that describes an open instance of a file.
fscanf()
is a pointer to a FILE object for input. A formatted input string can have a maximum
of 32,767 characters.
controls the input by specifying how input text is converted for assignment.
Subsequent arguments are pointers to the objects that receive the converted input.
If there are insufficient argument pointers for the format, a signal is generated. If the
program recovers from the signal, it treats it as if an asterisk flag were specified. If
the format is exhausted while arguments remain, fscanf() evaluates the excess
arguments but otherwise ignores them.
Format Strings
The format can contain the following code:
• Any number of spaces, horizontal tabs, or newline characters that cause input to be
read up to the next nonwhite-space character
• An ordinary character (not %) that must match the next character of the input stream
• Conversion specifications, consisting of the following sequence:
− The character % or the character sequence % digit $ decimal-integer
− An optional assignment-suppressing character *
− An optional decimal integer that specifies the maximum field width
− An optional h, l, L, or ll (lowercase double L) indicating the size of the receiving
object
See “Conversion Specifications” below.
7859 6137–009 5–53

fscanf()
Conversion Specifications
A conversion specification directs the conversion of the next input field. Except for the
conversion specifiers c and [, an input field is defined as a sequence of nonspace
characters. It starts at the first character in the input that is not a white-space character
(as specified by the isspace() function) and extends to the first conflicting character or
until the field width, if specified, is exhausted.
When the form % decimal-integer $ is used, the decimal integer indicates to which
argument in the argument list to assign the results of the conversion. If decimal-integer
is n, the conversion results are assigned to the nth argument.
The function places the result in the object pointed to by the subsequent argument,
unless assignment suppression was indicated by an asterisk (*). The conversion specifier
indicates the interpretation of the input field. The corresponding argument must be a
pointer to an appropriate type.
The following table lists the valid fscanf conversion specifiers.
Specifier Description
c A character is expected. The subsequent argument must be a pointer to
a char. The normal skip over white space characters is suppressed in this
case. To read the next nonspace character, use %1s. If a field width is
given, the corresponding argument must refer to a character array. The
indicated number of characters is read.
d A decimal integer is expected. The subsequent argument must be a
pointer to an integer.
e, E, f, g, G A floating-point number is expected. The corresponding argument must
be a pointer to a floating-point type. The input format is as described for
the strtod function.
i An integer is expected. The corresponding argument must be a pointer to
an integer. The input format is as described for the strtol function, with
the value of 0 for the base argument.
n No input is consumed. The subsequent argument must be a pointer to an
integer into which is written the number of characters read from the
input stream so far by this call to fscanf. This is not counted as a match
input item.
o An octal integer is expected. The subsequent argument must be a
pointer to an integer.
p A pointer is expected. The subsequent argument must be a pointer to a
pointer to void. The format of the input field is an octal number of up to
24 digits. It is the same as that produced by the %p conversion of
fprintf().
s A character string is expected. The subsequent argument must be a
pointer to char that points to an array large enough to accept the string
and a terminating NUL, which is added automatically. A space, a
horizontal tab, or a newline character terminates the input field but is not
part of the field.
5–54 7859 6137–009

Specifier Description
u An unsigned decimal integer is expected. The subsequent argument
must be a pointer to an integer.
x, X A hexadecimal integer is expected. The subsequent argument must be a
pointer to an integer.
fscanf()
[ A string that is not to be delimited by spaces is expected. The normal
skip over white-space characters is suppressed in this case. The
subsequent argument must be a pointer to char just as for %s. The left
bracket is followed by a set of characters followed by a right bracket. The
characters between the brackets define the set that determines the input
field string.
If the first character after the left bracket is not a circumflex (^), the input
field consists entirely of characters in the defining set. The first input
character not in the defining set signals the end of the input field.
If the first character after the left bracket is a circumflex (^), the input
field consists entirely of characters not in the defining set. The first input
character in the defining set signals the end of the input field.
If the first character is a right bracket (possibly following a circumflex), it
is assumed to be part of the set. A second right bracket is necessary to
delimit the set. This means the set of characters cannot be empty.
A NUL character is appended to the input.
% A single % is expected in the input at this point. No assignment occurs.
Considerations for Conversion Specifications
Only the characters in the table above can be used as conversion specifiers. If you use
any other character as a conversion specifier, the C compiler does not recognize it.
Scanning terminates and the function returns the number of input items successfully
read.
The conversion specifiers d, i, o, u, and x can be preceded by l to indicate that the
subsequent argument is a pointer to a long int rather than a pointer to an int, or by h to
indicate a pointer to a short int, or by ll (lowercase double L) to indicate a pointer to a
long long int.
Similarly, the conversion specifiers e and f can be preceded by l to indicate that the
subsequent argument is a pointer to a double rather than a pointer to a float, or by L to
indicate a pointer to a long double.
If fscanf() encounters the end of the file during a conversion, the conversion terminates.
If conversion terminates on a conflicting input character, the offending character is left
unread in the input stream. Trailing white-space characters (including a newline
character) are unread unless matched in the control string. The compiler cannot directly
determine the success of literal matches and suppressed assignments other than
through the %n conversion.
If a format does not have a corresponding argument, the format is treated as if an
asterisk (*) flag were specified.
7859 6137–009 5–55

fscanf()
Return Values
If it completes successfully, the fscanf() function returns the number of assigned input
items (which can be fewer than provided for, or even 0, in the event of an early conflict
between an input character and the format), or EOF if end of file is encountered before
the first conflict or conversion. Otherwise, fscanf() returns when it encounters the end of
the format string.
5–56 7859 6137–009

fseek()
Application
Use the fseek() function to set the file position indicator for a stream.
Synopsis
int fseek(FILE * stream, long offset, int whence);
Description
The fseek() function sets the file position indicator for a stream, where:
FILE
stream
offset
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object.
fseek()
is a signed number specifying the number of characters to move the indicator from
the starting position.
whence
specifies the starting position in the file, which can be one of the following values:
SEEK_CUR The current position
SEEK_END The end of the file
SEEK_SET The beginning of the file
The fseek() function clears the end-of-file indicator and undoes any effects of ungetc().
After a call to fseek() for an update file, the next operation can be either input or output.
Return Values
The fseek() function returns a nonzero value for an improper request.
7859 6137–009 5–57

fsetpos()
fsetpos()
Application
Use the fsetpos() function to set the file position indicator for a stream.
Synopsis
int fsetpos(FILE * stream, const fpos_t * pos);
Description
The fsetpos() function sets the file position indicator for a stream, where:
FILE
stream
pos
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object.
is a pointer to a structure containing the new value for the file position indicator. This
structure must be obtained by a call to the fgetpos() function.
Return Values
If it completes successfully, the fsetpos() function returns 0. Otherwise, fsetpos() sets
errno to indicate the error and returns a nonzero value.
5–58 7859 6137–009

fstat()
Application
fstat()
Use the fstat() function to retrieve information about an open file. In particular, you can
get information about the file mode, security attributes, file size, and access times.
The fstat() function uses a file descriptor to identify the file or directory. See the stat()
function for a similar function that uses a path name.
Synopsis
int fstat(int fildes, struct stat * buf);
Description
The fstat() function returns information about an open file in a stat structure, where:
fildes
buf
is a file descriptor associated with an open file description.
is a pointer to a stat structure in which fstat() returns the file information.
The stat Structure
The stat structure identifies certain information about a file or directory. The following
table describes the stat structure, which is defined in . The size of struct stat is
44 bytes.
Field Name Type Offset Description
st_mode mode_t 0 File mode.
st_ino ino_t 4 File serial number.
st_dev dev_t 8 Numeric identifier for the file system in which the
file resides.
st_nlink nlink_t 12 Number of links to the file or directory.
st_uid uid_t 16 Owner user ID of file or directory.
st_gid gid_t 20 Group group ID of file or directory.
st_size off_t 24 Size, in bytes, for directories or regular files; bytes
available to be read for pipe or FIFO files.
st_rdev rdev_t 28 If the inode represents a device file, this value
identifies the specific type of device that the inode
controls. The values are
1 = /dev/tty
2 = standard input, output, or error device
3 = /dev/null;
4 = /dev/random or /dev/urandom
7859 6137–009 5–59

fstat()
Field Name Type Offset Description
st_atime time_t 32 Time of last access to file data.
st_mtime time_t 36 Time of last data modification.
st_ctime time_t 40 Time of file creation.
Return Values
If the fstat() function completes successfully, it returns 0. Otherwise, fstat() sets errno to
identify the specific error and returns -1.
Error Codes
If any of the following conditions occurs, the fstat() function returns -1 and sets errno to
the corresponding value:
EBADF fildes is not a valid file descriptor.
EFAULT The address stored in path or buf is invalid.
5–60 7859 6137–009

fsync()
Application
fsync()
Use the fsync() function to write to the device all data currently in the buffer cache for a
file, thus protecting the data against loss due to a system outage. With fsync(), an
application can synchronize all file updates at one time, instead of on every read or write
operation. The fsync() function also synchronizes file access times.
For a similar function that does not synchronize file access times, see fdatasync(). For
alternate methods of synchronizing disk data, see the discussions of the O_SYNC and
O_DSYNC flags under the open() and fcntl() functions.
Synopsis
int fsync(int fildes);
Description
The fsync() function writes from the buffer cache to the mass storage device all data
belonging to the specified file, where fildes specifies a regular file open for writing.
Return Values
If the fsync() function completes successfully, it returns 0. Otherwise, fsync() sets errno
to identify the specific error and returns -1.
Error Codes
If any of the following conditions occurs, the fsync() function returns -1 and sets errno to
the corresponding value:
EBADF fildes is not a valid file descriptor open for writing.
EINVAL Data synchronization is not supported for the type of file
described by fildes.
EIO The file could not be fully synchronized because of an I/O
error.
7859 6137–009 5–61

ftell()
ftell()
Application
Use the ftell() function to obtain the current value of the file position indicator for a
stream.
Synopsis
long ftell(FILE * stream);
Description
The ftell() function obtains the current value in bytes of the file position indicator for a
stream, relative to the beginning of the file, where:
FILE
stream
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object.
Return Values
The ftell() function returns the current value of the file position indicator for the stream,
relative to the beginning of the file.
5–62 7859 6137–009

ftruncate()
Application
The ftruncate() function sets the end-of-file position for an open file.
Synopsis
int ftruncate(int fildes, off_t length);
Description
ftruncate()
A file referenced by the descriptor fildes has its size (in bytes) set to length. If the file
was previously longer than the length specified, those bytes are no longer accessible. If
the file was previously shorter than the length specified, bytes between the old
end-of-file and the specified length are read as zeroes. For ftruncate(), the calling
program must have the file open for writing.
For files stored in SDF format, the length value of 34359738367 (defined as INT_MAX in
the limits.h header file) has special meaning. CIFS treats this as an indication that it must
recalculate the actual size of the file when it is next read based on the position of the
EOF record, rather than pad the file with zeroes.
Return Values
Upon successful completion, the function returns a value of 0. If unsuccessful, it returns
a value of -1 and sets errno to the appropriate value.
7859 6137–009 5–63

fwrite()
fwrite()
Application
Use the fwrite() function to write elements from an array to an output stream.
Synopsis
size_t fwrite(const void * ptr, size_t size, size_t nelem, FILE * stream);
Description
The fwrite() function writes elements from an array to an output stream, where:
ptr
size
nelem
FILE
stream
is a pointer to the array.
specifies the size of an element in the array.
specifies the number of elements to write.
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object for output.
The fwrite() function advances the file position indicator by the number of bytes
successfully written. If an error occurs, the resulting value of the file position indicator is
indeterminate.
Return Values
If it completes successfully, the fwrite() function returns the number of elements
written; this number is less than nelem only if a write error occurs.
5–64 7859 6137–009

getc()
Application
Use the getc() function to obtain the next character from an input stream.
Synopsis
int getc(FILE * stream);
Description
The getc() function is equivalent to fgetc().
Return Values
The getc() function returns the next character from the specified input stream. If the
stream is at end of file, getc() sets the end-of-file indicator and returns EOF. If a read
error occurs, getc() sets the error indicator and returns EOF.
getc()
7859 6137–009 5–65

getchar()
getchar()
Application
Use the getchar() function to obtain the next character from standard input.
Synopsis
int getchar();
Description
The getchar() function is equivalent to calling getc() with the argument stdin (standard
input).
Return Values
The getchar() function returns the next character from standard input. If standard input is
at end of file, getchar() sets the end-of-file indicator and returns EOF. If a read error
occurs, getchar() sets the error indicator and returns EOF.
5–66 7859 6137–009

getcwd()
Application
Use the getcwd() function to identify a process' current working directory. You can
specify where the information is returned.
Synopsis
char * getcwd(char * path, size_t size);
Description
getcwd()
The getcwd() function identifies the absolute path name of the current working directory
of the calling process, where:
path
size
is a pointer to the path name; it is one of the following:
• A pointer to a character array of length size
The getcwd() function returns the path name of the current working directory in
path.
• A null pointer
The getcwd() function puts the path name of the current working directory in
allocated storage. getcwd() calls malloc(size) to get the storage. You can use the
free() function to release the storage when it is no longer needed.
is the size in bytes of the character array to which path points. If the path name of
the working directory has more characters in it than size allows, an error occurs.
Return Values
If the getcwd() function completes successfully, it returns a pointer to the absolute path
name for the current working directory. Otherwise, getcwd() sets errno to identify the
specific error and returns a null pointer.
Error Codes
If any of the following conditions occurs, the getcwd() function returns a null pointer and
sets errno to the corresponding value:
EFAULT The pointer specified by path is invalid.
EINVAL size is less than or equal to 0.
ENOMEM The pointer specified by path is null and no
memory space is available to the process.
ERANGE size is greater than 0 but less than the
length of the path name plus 1.
7859 6137–009 5–67

getpwnam()
getpwnam()
Application
Use the getpwnam() function to retrieve the numeric identifier for a user, given the user
name.
Synopsis
struct passwd * getpwname(const char * name);
Description
The getpwnam() function retrieves information about a CIFS user, based on the supplied
user name. The information is returned in a passwd structure located in a static data area
that each call to getpwnam() overwrites.
Note: getpwnam() is not case sensitive.
Return Values
If the getpwnam() function completes successfully, it returns a pointer to the passwd
structure for the specified user name. Otherwise, getpwnam() sets errno to identify the
specific error and returns a null pointer.
Error Codes
If any of the following conditions occurs, the getpwnam() function returns a null pointer
and sets errno to the corresponding value:
EFAULT Detected an invalid address in an argument of a function
call.
EINVAL name contains an invalid character.
EIO An I/O error prevented successful completion.
ENAMETOOLONG name exceeds 12 characters in length, not counting the
trailing nul character.
ENOENT One of the following errors occurred:
• name is a null string.
• The specified user name is not known to CIFS.
5–68 7859 6137–009

getpwuid()
Application
getpwuid()
Use the getpwuid() function to retrieve the symbolic name for a user, given the numeric
user identifier.
Synopsis
struct passwd * getpwuid(uid_t uid);
Description
The getpwuid() function retrieves information about a CIFS user, based on the supplied
numeric identifier. The information is returned in a passwd structure located in a static
data area that each call to getpwuid() overwrites.
The passwd Structure
The passwd structure passes information about CIFS users. Functions that create,
modify, and inspect user information use the passwd structure. The following table
describes struct passwd, which is defined in .
Member
Name
Member
Type Description
pw_name char * A pointer to the user ID name (the OS 2200 user ID). The user
name is one of the following:
• The generic user ID name cifs_generic
• to 12 lowercase characters, excluding the terminating nul
character, where each character is one of the following:
− letter
− digit
− period (.)
− minus sign (-)
− dollar sign ($)
pw_uid uid_t The numeric user ID associated with the user, assigned by CIFS.
Note: Other fields in the password structure are reserved for internal use by CIFS.
Return Values
If the getpwuid() function completes successfully, it returns a pointer to the passwd
structure for the specified user name. Otherwise, getpwuid() sets errno to identify the
specific error and returns a null pointer.
7859 6137–009 5–69

getpwuid()
Error Codes
If any of the following conditions occurs, the getpwuid() function returns a null pointer
and sets errno to the corresponding value:
EINVAL The user ID specified in uid is outside the range known to CIFS.
Valid uid values are greater than zero and less than the current
highest one registered with CIFS.
EIO An I/O error prevented successful completion.
ENOENT A user with the numeric user ID value of uid is not known to
CIFS.
5–70 7859 6137–009

gets()
Application
Use the gets() function to read a string of characters from standard input into an array.
Synopsis
char * gets(char * s);
Description
gets()
The gets() function reads characters from the standard input stream (stdin) into the array
to which s points, until it encounters the end of the file or a newline character. gets()
discards any newline character and writes a nul character immediately after the last
character in the array.
Return Values
If it completes successfully, the gets() function returns the array s. If gets() encounters
end of file before reading any characters into the array, the contents of the array remain
unchanged and gets() returns a null pointer. If a read error occurs, the contents of the
array are indeterminate and gets() returns a null pointer.
7859 6137–009 5–71

getuid()
getuid()
Application
Use the getuid() function to retrieve the numeric user ID of the current process.
Synopsis
uid_t getuid();
Description
The getuid() function retrieves the user ID value for the currently executing process. All
threads of a process share the same numeric user ID.
Return Values
The getuid() function returns –1 and sets errno if the function fails; otherwise, it returns
the CIFS user ID number for the current process.
5–72 7859 6137–009

istat()
Application
Use the istat() function to retrieve CIFS-unique information about a file or directory.
Synopsis
int istat(ino_t ino, struct _istat * ibuf, size_t size);
Description
istat()
If ino corresponds to a valid file serial number, the function places up to size bytes of the
following information into the ibuf area. The ino argument is typically obtained from the
st_ino field of the stat structure returned by a stat() or fstat() function.
Field Name Type Offset Description
st_cycle int 0 OS 2200 absolute F-cycle of this
file.
st_cycle_chain ino_t 4 Inode number of the next OS 2200
F-cycle of this same file name.
st_alt_os_dir_ino ino_t 8 Inode number of the alternate
OS 2200 directory version of this
file name.
st_os2200 int 12 Indicates where a directory inode
appears in the /os2200 hierarchy.
Can contain the following values:
0 Not in the /os2200 hierarchy
1 The /os2200 directory
2 An immediate subdirectory
(qualifier) of /os2200
3 A program or data file in the
/os2200 hierarchy
st_owner[13] char 16 Owner of the file. For owned files,
this is the OS 2200 user ID. For
unowned files, this is the project or
account, depending on the value of
the configuration variable PRIVAC.
st_directory[7] char 29 The OS 2200 MFD containing this
file; either STD or SHARED.
st_contain[38] char 36 For regular files, the name of the
underlying OS 2200 file container.
The field contains a null string for
other file types.
7859 6137–009 5–73

istat()
Field Name Type Offset Description
st_element_name[13] char 74 The element name associated with
the file; null string if the file is not
stored as an OS 2200 element.
st_element_version[1
3]
st_element_type short
int
st_element_sub_type short
int
char 87 The element version associated
with the file; not used if the file is
not stored as an OS 2200 element.
100 The type of the underlying
element, either 1, 5, 6, or 7. Not
used if the file is not stored as an
OS 2200 element.
102 The subtype of the underlying
symbolic or omnibus element; not
used for other element types or if
the file is not stored as an OS 2200
element.
st_share[32] char 104 For directories, the network share
name assigned to it; a null string if
the directory is not shared.
st_acr[8] char 136 The ACR name associated with a
file.
The size of struct_istat is 144 bytes. The data is stored in the order listed; whatever does
not fit in size bytes is discarded.
Return Values
If successful, the function returns zero; if an error is encountered, it returns -1 and sets
errno to an appropriate value.
5–74 7859 6137–009

link()
Application
link()
Use the link() function to create new directory entries for a file, allowing you to reference
one file in multiple ways. The new entries can be in the same directory or in different
directories.
link() increases the link count of the referenced file by 1.
Synopsis
int link(const char * path1, const char * path2);
Description
The link() function creates a new directory entry (link), provided the process has the
necessary permissions (see “Permissions Required” in this subsection), where:
path1
path2
is a pointer to the name of an existing regular or FIFO file.
is a pointer to the path name for the new link for the file named by path1. The
directory in which the new link is created must be in the same file system as path1.
Diagrams
The link() function causes both directory entries to refer to the same physical file. In the
following diagrams, both link_1 and link_2 refer to the same file, whether they are in the
same directory or not.
link ("/dir_1/link_1", "/dir_2/link_2")
dir_1
link_1
7859 6137–009 5–75
file
dir_2
link_2

link()
Permissions Required
The calling process must have all the following permissions to create the link:
• Search permission for all the path1 component directories
• Search permission for all the path2 component directories
• Write permission to the parent directory of the new file
Return Values
If the link() function completes successfully, it does the following:
• Updates the st_atime field of the path1 file
• Updates the st_mtime field of the path2 directory
• Returns 0
Otherwise, link() sets errno to identify the specific error and returns -1.
Error Codes
If any of the following conditions occurs, the link() function returns -1 and sets errno to
the corresponding value:
EACCES Any of the following errors occurred:
• The calling process is denied search permission to a component of
either path name.
• The calling process is denied write permission to the path2 directory.
EEXIST The link named by path2 already exists.
EFAULT The pointer specified by path1 or path2 is invalid.
EIO An I/O error occurred.
link ("/dir_1/link_1", "/dir_1/link_2")
dir_1
link_1
link_2
EMLINK The number of links to the file named by path1 exceeds the C standard
value INT_MAX.
ENOENT Any of the following errors occurred:
• A directory in either path name does not exist.
• The file in path1 does not exist.
• Either path1 or path2 points to an empty string.
5–76 7859 6137–009
file

ENOSPC The path2 directory to contain the link has too many entries.
ENOTDIR A component of either path name prefix is not a directory.
EPERM The file named by path1 is a directory or a character file.
link()
7859 6137–009 5–77

lseek()
lseek()
Application
Use the lseek() function to set the read/write offset for an open file at a specific position
in the file. You can also set the read/write offset beyond the end of existing data in the
file without increasing the file size; however, a write operation at that location increases
the file size.
Definition
The read/write offset is the file address at which the next read() or write() operation
starts.
Synopsis
off_t lseek(int fildes, off_t offset, int whence);
Description
The lseek() function sets the read/write offset for an open file description, where:
fildes
offset
is a file descriptor.
specifies the new location of the read/write offset from the beginning, current
position, or end of a file, as shown in the following table and diagram.
whence
specifies whether the read/write offset is calculated from the beginning, current
position, or end of a file. See the following table and diagram for the valid values for
whence and their relationships to offset.
Value of
whence
How the Read/Write Offset Is
Calculated
SEEK_CUR* Current offset value plus offset bytes
SEEK_END* Size of the file plus offset bytes
SEEK_SET* offset bytes from the beginning of the
file
*Defined in
5–78 7859 6137–009

Illustration
lseek()
Given a value for offset, the value of whence determines whether the read/write offset
occurs at the beginning, current position, or end of a file. The following diagram shows
the possible new positions of the read/write offset:
Beginning
of File
Reading Unwritten Areas
If a file contains unwritten gaps, reading these areas returns bytes with the value 0.
However, files created outside of CIFS can contain unwritten data that is not detectable;
reading these areas returns bytes with indeterminate values.
Function Behavior for Different File Types
All calls to lseek() fail for the following file types:
• Pipes
1
2
3
offset
• FIFO files
For some types of files, a read/write offset is not meaningful; for these files, the
read/write offset returned by lseek() is undefined.
Portability Issue
In other implementations, the return type off_t can be unsigned. To test for an error in a
portable way, compare the result with (off_t)-1.
Return Values
whence = SEEK_END
Current
Position
End
of File
offset offset
1 2 3
whence = SEEK_SET
whence = SEEK_CUR
If the lseek() function completes successfully, it returns the new read/write offset
location in bytes from the beginning of the file. Otherwise, lseek() sets errno to identify
the specific error and returns the cast value (off_t)-1.
7859 6137–009 5–79

lseek()
Error Codes
If any of the following conditions occurs, the lseek() function returns -1 and sets errno to
the corresponding value:
EBADF fildes is not a valid file descriptor.
EINVAL One of the following errors occurred:
• whence is invalid.
• The resulting read/write offset would be
invalid (that is, negative).
ESPIPE fildes is associated with a pipe or FIFO file.
5–80 7859 6137–009

mask()
Application
mask()
Use the _cifs_mask() function to determine whether or not a given string matches a wild
card pattern.
Note: There is no POSIX equivalent to _cifs_mask().
Synopsis
boolean_t _cifs_mask(const char * name, const char * mask);
Description
The _cifs_mask() function checks the name parameter for conformance with the mask
parameter. The mask parameter may contain the wild card characters asterisk (*) and
question mark (?). A question mark matches a single occurrence of any character; an
asterisk matches zero or more occurrences of any character. Other characters in mask
must be a case-insensitive match to ones in the corresponding positions of name in
order for the function to return a TRUE result. For example, the name “abcdef”
conforms to “abc*” and “aBc???”, but not to “abc?” Wild card characters may be mixed
in any order and with any other characters.
Return Values
The _cifs_mask() function returns TRUE if name conforms to mask, FALSE if it does not.
7859 6137–009 5–81

mkdir()
mkdir()
Application
Use the mkdir() function to create a new directory, setting its file permissions and
security attributes. The directory is empty except for its dot and dot-dot entries. Once
the directory is created, you can make directory entries.
Synopsis
int mkdir(const char * path, mode_t mode);
Description
The mkdir() function creates a directory containing only the dot and dot-dot entries,
where:
path
mode
is a pointer to the new directory.
contains the settings for file permissions for the new directory, which are first
modified by the file mode creation mask of the calling process. In addition to the
permission bits, you can specify the creation of a Large Element Program File
(LEPF). The LEPF setting is specified by using the S_LEPF constant, and a normal
program file by S_NPF.
File Mode Attributes
The mkdir() function also sets the following attributes in the file mode for the directory:
• The user ID of the new directory to the effective user ID of the calling process
• The group ID of the new directory, to the effective group ID of the process
Return Values
If the mkdir() function completes successfully, it does the following:
• Sets the file permissions, user ID, and group ID for the new directory, as discussed
in the preceding paragraphs
• Sets the st_atime, st_ctime, and st_mtime fields of the new directory
• Updates the st_atime and st_mtime fields of the parent directory
• Returns 0
Otherwise, mkdir() sets errno to identify the specific error and returns -1.
5–82 7859 6137–009

Error Codes
mkdir()
If any of the following conditions occurs, the mkdir() function returns -1 and sets errno to
the corresponding value:
EACCES The calling process is denied one of the following:
• Search permission to a directory in the path name
• Write permission on the parent directory of the new directory
EEXIST A directory with the same path name already exists.
EFAULT The pointer specified by path is invalid.
EINVAL mode has undefined bits set.
EMLINK The link count of the parent directory exceeds the C standard value
INT_MAX.
ENOENT Either of the following errors occurred:
• A directory in the path name does not exist.
• path points to an empty string.
ENOSPC Either of the following errors occurred:
• The parent directory has too many entries.
• The file system does not have enough space to hold the new
directory.
ENOTDIR A component of the path name prefix is not a directory.
7859 6137–009 5–83

mkfifo()
mkfifo()
Application
Use the mkfifo() function to create a new first-in-first-out (FIFO) file, setting its file
permissions and security attributes. The new FIFO is empty.
Synopsis
int mkfifo(const char * path, mode_t mode);
Description
The mkfifo() function creates a FIFO file, where:
path
mode
is a pointer to the name of the new FIFO file.
contains the file permission settings for the new FIFO file, which are first modified
by the file mode creation mask of the calling process.
File Mode Attributes
The mkfifo() function also sets the following attributes in the file mode:
• The user ID of the new FIFO file to the effective user ID of the calling process
• The group ID of the new FIFO file to the effective group-ID of the process
Return Values
If the mkfifo() function completes successfully, it does the following:
• Sets the file permissions, user ID, and group ID for the new FIFO file, as discussed
in the preceding paragraphs
• Sets the st_atime, st_ctime, and st_mtime fields of the new FIFO file
• Updates the st_atime and st_mtime fields of the parent directory
• Returns 0
Otherwise, mkfifo() sets errno to identify the specific error and returns -1.
5–84 7859 6137–009

Error Codes
mkfifo()
If any of the following conditions occurs, the mkfifo() function returns -1 and sets errno
to the corresponding value:
EACCES The calling process is denied one of the following:
• Search permission to a component of the path name
• Write permission to the parent directory of the new
file
EEXIST A file with the same path name already exists.
EFAULT The pointer specified by path is invalid.
EINVAL mode has bits set that are either undefined or not file
permission bits.
ENOENT Either of the following errors occurred:
• A directory in the path name does not exist.
• path points to an empty string.
ENOSPC Either of the following errors occurred:
• The parent directory has too many entries.
• The file system does not have enough resources for
file allocation.
ENOTDIR A component of the path prefix is not a directory.
EROFS The parent directory exists on a read-only file system.
7859 6137–009 5–85

new_process()
new_process()
Application
Use _cifs_new_process (and _cifs_end_process) to group activities into logical
processes, where all activities (threads) of a process share a set of open files.
Note: There is no POSIX equivalent to _cifs_new_process.
Synopsis
int _cifs_new_process();
Description
All threads (OS 2200 activities) of a program making use of CIFS services normally share
open file descriptors and a current directory setting. This collection of file information and
the threads that share it is known as a process. If a program needs separate sets of file
descriptors, or multiple current directories, it can use the _cifs_new_process() function to
create additional processes. The thread that invokes _cifs_new_process() becomes the
first thread for the new process. A thread spawned by another thread (using the
tskstart() function in the UCS Runtime System library) always belongs to the same
process as the spawning thread, and may not change that association other than by
creating a new process.
When _cifs_new_process() is invoked, the new process starts with copies of all open file
descriptors (except those marked with FD_CLOEXEC by the F_SETFD command of the
fcntl() function) and the current directory setting of the process to which the invoking
thread previously belonged. Subsequent open(), close(), etc., requests have no effect on
any other process of the program.
The _cifs_end_process() function can be used to inform CIFS that its services are no
longer required by the set of threads making up the process. This happens automatically
when all threads of a process terminate, but can be forced at an earlier time if desired by
program logic.
Return Values
Returns a value of zero if successful and a value -1 if any errors are detected (with errno
set to the appropriate value).
5–86 7859 6137–009

open()
Application
open()
Use the open() function to open a file, specifying how you can access the file and setting
special attributes. Opening a file does the following:
• Creates an open file description and corresponding file descriptor for this unique
instance of the open file.
Note: The new open file description is not shared by any other process on the
system; the file descriptor identifies this open file description only.
• Can create the file, if it does not already exist. In this case, you must also specify the
file permissions for the file mode. See also the creat() function.
Synopsis
int open(const char * path, int oflag[, mode_t mode]);
Description
The open() function opens a file, where:
path
oflag
mode
is a pointer to the name of the file to be opened.
sets the access specification and file status flags in the open file description. See
“The oflag Argument” in a following subsection for the valid values for oflag.
is an optional argument of type mode_t that sets the file permissions when a new
file is created (see the file status flag O_CREAT). See “The mode Argument” in a
following subsection for the valid values for mode.
Results of Opening a File
The open() function does the following:
1. Sets the initial read/write offset to the start of the file
2. Selects the numerically lowest available file descriptor for the process
3. Returns the file descriptor so that other I/O functions can access the file
7859 6137–009 5–87

open()
Example
The following code statement opens a file that does not currently exist:
fd_inventory = open("/books/novels/f inventory", O_CREAT | O_RDWR,
S_IRUSR | S_IRGRP | S_IWUSR | S_IWGRP);
The statement does the following tasks:
• Creates the file f_inventory in the directory /books/novels
• Opens the file for reading and writing
• Assigns read and write permission for the owner and group classes
• Captures the file descriptor returned by open() in fd_inventory
The following code shows an alternate solution for this example. It has the advantage of
declaring variables with specific values that can be used in other open operations.
int oflags = O_CREAT | O_RDWR;
int perms = S_IRUSR | S_IRGRP | S_IWUSR | S_IWGRP;
fd_inventory = open("/books/novels/f_inventory", oflags, perms);
Files Affected by open()
A process must open a file before reading from or writing to it. The open() function
opens the following types of files:
• Regular files
• FIFO files
• Directories (for reading only)
Note: The open() function can also create a regular file if it does not exist. The other
types of files must exist before open() can access them.
Return Values
If the open() function completes successfully, it does the following:
• Updates the following time information fields if O_CREAT is set and the file does not
exist:
− The st_atime, st_ctime, and st_mtime fields for the file
− The st_atime and st_mtime fields for the parent directory
• Updates the st_atime and st_mtime time information fields for the file if O_TRUNC is
set for an existing file
• Returns the file descriptor
Otherwise, open() sets errno to identify the specific error and returns -1.
5–88 7859 6137–009

Error Codes
open()
If any of the following conditions occur, the open() function returns -1 and sets errno to
the corresponding value:
EACCES Any of the following access errors occurred:
• The calling process is denied search permission on one or more
directories in path.
• The file exists and the permissions specified by oflag are
denied.
• The file does not exist and write permission is denied for the
parent directory of the file to be created.
• O_TRUNC is specified and write permission is denied.
EAGAIN A resource is temporarily unavailable. Either the calling process
attempted to open a file that was rolled out with O_NONBLOCK
set, or the wait time specified by the CIFS$WAITROLBAK
environment variable expired. This is a temporary condition and a
subsequent call might complete normally.
EBUSY A resource is temporarily unavailable. Either the calling process
attempted to open a file that was exclusively assigned with
O_NONBLOCK set, or the wait time specified by the
CIFS$WAITXUSE environment variable expired. This is a temporary
condition and a subsequent call might complete normally.
EEXIST O_CREAT and O_EXCL are set and the file exists.
EFAULT The pointer specified by path is invalid.
EINTR The open() operation was interrupted by a signal.
EINVAL Any of the following errors occurred:
• O_CREAT is specified and mode is missing.
• An open() function call with read-only access and O_TRUNC
specified is not valid. The two options are incompatible.
• oflag has neither the O_RDONLY, the O_WRONLY, nor the
O_RDWR flags set. One of these flags must be set.
• An open() function call with more than one of S_1100SDF and
S_1100BIN specified is not valid. A file cannot have more than
one of these attributes.
• An open() function call for a FIFO file with read/write access is
not valid.
• Either oflag or mode has undefined bits set.
EIO An input/output error occurred.
EISDIR The file is a directory and oflag specifies write access.
EMFILE The calling process is attempting to open a file and the limit on the
maximum number of open file descriptors for a process would be
exceeded.
7859 6137–009 5–89

open()
ENOENT Either of the following errors occur:
• O_CREAT is not set and the file does not exist.
• O_CREAT is set and either
− A directory in the path name does not exist.
− path points to an empty string.
ENOSPC The directory or file system that is to contain the new file is out of
available space.
ENOTDIR A component of the path name prefix is not a directory.
ENXIO O_NONBLOCK and O_WRONLY are set for a FIFO file and no
process has the file open for reading.
The oflag Argument
The oflag argument is the bitwise inclusive OR operation of the following values:
• An access specification value
• Any combination of values for file status flags
Access Specification Values
The following symbolic constants are valid access specifications:
O_RDONLY Open the file for reading only.
O_WRONLY Open the file for writing only.
O_RDWR Open the file for reading and writing. (This is the same as
specifying both O_RDONLY and O_WRONLY.)
File Status Flag Values
The following symbolic constants are valid file status flags:
O_APPEND The read/write offset is set to the end of the file before each write
operation.
O_CREAT The open() function
• Creates a regular file with path as its path name
• Sets ownership of the regular file, as follows:
− Sets the user ID of the file to the effective user ID of the process
− Sets the group ID of the file to the effective group ID of the
process
When O_CREAT is set, open() requires a third argument, mode, of type
mode_t. The file permission attributes are set to the value in mode minus
the attributes set in the process' file mode creation mask (see the
umask() function). The mode argument does not affect whether the file is
opened for read or write access or both.
O_DSYNC The open() function opens the file for synchronized read and write
operations.
5–90 7859 6137–009

open()
The kernel implements a buffering system for the file data in volatile
storage. I/O buffering increases the speed at which data can be accessed
and changed, but it also increases the risk of lost data due to a system
failure. When file I/O operations are not synchronized, it is possible for file
data to reside in volatile storage for some period of time without being
written to a disk device.
Setting the O_DSYNC flag
• Causes any data written through the file descriptor to also be written
to the disk device before the write() function returns
• Ensures that any data read from a file descriptor is written to the disk
device before the read() function returns that data
O_EXCL Use O_EXCL with O_CREAT to ensure that the file does not already exist,
as follows:
If O_EXCL is ... And O_CREAT is ... Then ...
Set Set open() fails if the file exists.
Set Not set open() ignores O_EXCL.
Not set Set open() opens the file if it already exists;
otherwise, open() creates the file.
Not set Not set open() opens the file if it already exists;
otherwise, open() fails.
O_NONBLOCK This value determines whether open() waits for certain file
availability or fails, as follows:
If O_NONBLOCK is ...
And the file type
is ... Then...
Set Regular open() fails if the OS 2200 file
container is rolled out or otherwise
temporarily unavailable.
Set FIFO For read-only access, open() returns
without a delay.
For write-only access, open() fails if no
process has the file open for reading.
7859 6137–009 5–91

open()
If O_NONBLOCK is ...
And the file type
is ... Then...
Not set Regular The process waits if the OS 2200 file
container is rolled out or exclusively
assigned. The maximum wait time can
be specified by the
CIFS$WAITROLBAK and
CIFS$WAITXUSE environment
variables.
Not set FIFO For read-only access, open() waits until
a process opens the file for writing.
For write-only access, open() waits
until a process opens the file for
reading.
O_NONBLOCK This has no effect when opening any other type of file.
O_SYNC This value has the same effect as O_DSYNC, with the addition
of ensuring that file access times are updated on the disk device
before returning from read() or write() requests on the file
descriptor. Setting both O_SYNC and O_DSYNC has the same
effect as setting only O_SYNC.
O_TRUNC This value truncates the file length to zero, leaving the file mode
and file owner unchanged. This affects only a regular file opened
with write-only or read/write access. A call to open() with readonly
access and O_TRUNC set returns an error.
5–92 7859 6137–009

The mode Argument
The mode argument is type mode_t. It is the bitwise inclusive OR operation of the
following attributes for a newly created file (see Section 3 for a discussion of the
attributes in the file mode):
• File permission attributes
Permission
Class
Read Write
Permission Attributes
Search/
Execute
open()
Read/Write/
Search/Execute
Owner S_IRUSR S_IWUSR S_IXUSR S_IRWXU
Group S_IRGRP S_IWGRP S_IXGRP S_IRWXG
Other S_IROTH S_IWOTH S_IXOTH S_IRWXO
• File format attributes
− Binary format: S_1100BIN
− System data format (SDF): S_1100SDF
7859 6137–009 5–93

opendir()
opendir()
Application
Use the opendir() function to open a directory stream, making it accessible to the calling
process at the first directory entry. You must first open a directory stream before doing
anything with it.
See closedir() for closing an open directory, readdir() for reading the next directory entry,
and rewinddir() for repositioning the stream at its beginning.
Synopsis
DIR * opendir(const char * dirname);
Description
The opendir() function opens a directory stream and positions the stream to the first
directory entry, where dirname identifies the directory to open.
Return Values
If the opendir() function completes successfully, it returns a pointer to a directory stream.
Otherwise, opendir() sets errno to identify the specific error and returns a null pointer.
Error Codes
If any of the following conditions occurs, the opendir() function returns a null pointer and
sets errno to the corresponding value:
EACCES One of the following errors occurred:
• Search permission is denied for a component of the path name
prefix of dirname.
• Read permission is denied for the directory itself.
EFAULT dirname is not a valid pointer.
EIO An I/O error occurred on a directory in the path name.
EMFILE The calling process would exceed the maximum number of file
descriptors allowed.
ENOENT One of the following errors occurred:
• The directory does not exist.
• dirname is an empty string.
ENOMEM Memory could not be allocated for the DIR object.
ENOTDIR A component of dirname is not a directory.
5–94 7859 6137–009

pack()
Application
pack()
Use the pack() function to pack the underlying OS 2200 program files of CIFS directories.
Synopsis
int pack(const char *path);
Description
The pack() function packs the underlying OS 2200 program file of a CIFS file or directory.
This recovers unused TOC space and file text space resulting from the program file
having deleted elements. The action is directly analogous to a FURPUR @PACK. Any
existing relocatable and PROC entry point tables will be preserved.
Notes:
• The pack operation requires CIFS to have exclusive use (@ASG,AX) of a file while it
is being packed. The program file must not be assigned to any run or name section,
including the run doing the pack() API call. (An EBUSY status is returned.)
• Unlike the -pr option of the CIFSUT touch command, the pack () API does not have
recursive capabilities. Only one program file can be packed for each API call. The
CIFS pack is a safe pack; if the system in that goes down or an X-keyin to the run is
done during the pack. The contents of the program file are preserved, except in
extremely rare circumstances.
path
is a pointer to the path name of a file or directory
Return Values
pack() returns a zero value if any of the following conditions are true:
• If it can pack the underlying program file.
• If the pack is already packed.
• If it is not able to pack productively.
• If there is no underlying program file.
If there is an error, then pack() returns a -1 and sets errno to an appropriate value.
Error Codes
The following are the possible errno values on an error return:
EACCES Access to a file or directory is denied.
EFAULT The path pointer caused a fault in CIFS, an IGDM.
ENAMETOOLONG The path name length is too long.
7859 6137–009 5–95

pack()
ENOENT The named file or directory does not exist or CIFS could not
assign the program file.
ENOTDIR A component of the path prefix is not a directory.
EPERM Access to a file or directory is denied.
EBUSY The program file is rolled-out or assigned to someone else. CIFS
requires exclusive access to the file.
ENONMEM Buffer space was unavailable.
EIO An IO error occurred on the backing program file.
E1100CORRUPT A basic error in the program file, such as the text for elements
being out of order.
E1100INTERNAL An internal error occurred in CIFS.
5–96 7859 6137–009

perror()
Application
Use the perror() function to print a message corresponding to an error that occurred.
Synopsis
void perror(const char * s);
Description
perror()
The perror() function associates the error number in errno with an error message and
writes a line to the standard error file, where a line is the message followed by a newline
character.
The argument s is a pointer to a string specified to precede the message. If s is not the
null pointer and the character to which s points is not the nul character, perror() writes
the following sequence before writing the message:
1. The string to which s points
2. A colon and a space
The contents of the error message strings are the same as those returned by a call to
strerror () with the argument errno.
Return Values
The perror() function returns no value.
7859 6137–009 5–97

pipe()
pipe()
Application
Use the pipe() function to create a pipe to transmit data between processes. Pipes are
temporary entities that help processes communicate with each other. Pipes have a
”read end” and a ”write end,” which are located by file descriptors returned by pipe().
When using a pipe, one process writes data to it and another process reads the data on
a First-In-First-Out (FIFO) basis; or one process can pipe data to itself.
The pipe() function also initializes the O_NONBLOCK flags as clear; (see the open()
function) for both file descriptors. You can set these flags with the fcntl() function (see
the fcntl() function.) See “Redirecting Standard Files to Pipes” for information on using
pipes.
Synopsis
int pipe(int fildes[2]);
Description
The pipe() function creates a pipe and returns its file descriptors in the fildes array,
where:
fildes[0]
fildes[1]
is the file descriptor for the read end of the pipe.
is the file descriptor for the write end of the pipe.
Return Values
If the pipe() function completes successfully, it does the following:
• Initializes the st_atime, st_ctime, and st_mtime fields of the pipe
• Returns 0
Otherwise, pipe() sets errno to identify the specific error and returns -1.
Error Codes
If the following condition occurs, the pipe() function returns -1 and sets errno to the
corresponding value:
EMFILE The calling process would exceed the maximum number of file
descriptors allowed.
5–98 7859 6137–009

Redirecting Standard Files to Pipes
Using C Standard Files
pipe()
To agree on the file descriptors for a pipe, programs follow the convention of using the C
standard files to correspond to the pipe's file descriptors, as follows:
C Standard File Program Name
Standard input file (stdin) STDIN_FILENO 0
Standard output file
(stdout)
STDOUT_FILENO 1
Standard error file (stderr) STDERR_FILENO 2
Redirecting Standard Files
File
Descriptor
In your program, you can redirect the standard files to one end of a pipe. For example, to
redirect STDOUT_FILENO to the write end of a pipe, do the following procedure:
1. Close STDOUT_FILENO, making its file descriptor available for reuse.
2. Duplicate the write end of the pipe. The kernel always chooses the lowest available
number for a new file descriptor, which is the one previously assigned to
STDOUT_FILENO.
3. Close the original write end of the pipe, leaving STDOUT_FILENO as the write end.
7859 6137–009 5–99

printf()
printf()
Application
Use the printf() function to write formatted output to the standard output.
Synopsis
int printf(const char * format, ...);
Description
The printf() function is equivalent to calling fprintf() using stdout as the file pointer, as
follows:
fprintf(stdout, format, ...);
See fprintf() for a description of the format argument.
Return Values
If it completes successfully, the printf() function returns the number of characters
transmitted. Otherwise, printf() returns a negative value.
5–100 7859 6137–009

putc()
Application
Use the putc() function to write characters to an output stream.
Synopsis
int putc(int c, FILE * stream);
Description
The putc() function is equivalent to fputc().
Return Values
putc()
If it completes successfully, the putc() function returns the character written. If a write
error occurs, putc() sets the error indicator and returns EOF.
7859 6137–009 5–101

putchar()
putchar()
Application
Use the putchar() function to write a character to standard output.
Synopsis
int putchar(int c);
Description
The putchar() function is equivalent to calling putc() with the second argument stdout
(standard output).
Return Values
If it completes successfully, the putchar() function returns the character written. If a
write error occurs, putchar() sets the error indicator and returns EOF.
5–102 7859 6137–009

puts()
Application
Use the puts() function to write a string of characters to standard output.
Synopsis
int puts(const char * s);
Description
puts()
The puts() function writes the string to which s points to the standard output stream
(stdout), appending a newline character to the output. The nul character terminating the
array is not written.
Return Values
If it completes successfully, the puts() function returns 0. Otherwise, puts() returns EOF.
7859 6137–009 5–103

ead()
read()
Application
Use the read() function to read data from a file at the current read/write position. Use the
lseek() function to reposition the read/write offset, if necessary. See the following
subsections for more information: “Determining the Number of Bytes Read,” “Starting
Position for Different File Types,” and “Reading Different File Types.”
Synopsis
ssize_t read(int fildes, void * buf, size_t nbyte);
Description
The read() function reads data from a file into a buffer, where:
fildes
buf
nbyte
is a file descriptor.
is a pointer to the buffer that receives the data as it is read.
is the number of bytes to be read, which is limited by the size of a data bank.
Return Values
If the read() function completes successfully, it does the following:
• Updates the st_atime field of the file (see the fstat() and stat() functions), if it reads
any bytes
• Increments the read/write offset by the number of bytes actually read
• Returns the number of bytes actually read and placed into the buffer
Otherwise, read() sets errno to identify the specific error and returns -1.
Error Codes
If any of the following conditions occurs, the read() function returns -1 and sets errno to
the corresponding value:
EAGAIN The file descriptor's O_NONBLOCK flag is set and no data is available.
EBADF fildes is not a valid file descriptor open for reading.
5–104 7859 6137–009

EFAULT One of the following errors occurred:
• buf points to an invalid address, and nbyte is greater than 0.
• buf is valid, but (buf+(nbyte-1)) points to an invalid address.
EIO An I/O error occurred during processing of the request.
Determining the Number of Bytes Read
The read() function returns the number of bytes actually read and stored in the buffer,
which is never greater than nbyte. The following paragraphs relate this return value to
the input value of nbyte.
Return Value = nbyte
The read() function read and stored the exact number of bytes requested.
Return Value < nbyte
The value returned is less than nbyte if one of the following statements is true:
• Fewer than nbyte bytes remain between the read/write offset and the end of the
file.
read()
• The file is a pipe or FIFO that has fewer than nbyte bytes immediately available for
reading.
Return Value = 0
The value returned is 0 if one of the following statements is true:
• The value of nbyte is 0; the function has no other effects.
• The value of nbyte is not 0, but the read/write offset is at the end of file (EOF).
Starting Position for Different File Types
The file type determines which byte in the file is the first to be read, as shown in the
following paragraphs.
Regular Files
The read() function starts at the position given by the read/write offset associated with
the open file description corresponding to fildes. Before returning, read() increases the
read/write offset by the number of bytes read.
Pipes and FIFO Files
The read() function starts at the current position associated with the file corresponding to
fildes. The value of the read/write offset has no meaning for these file types.
If the starting position is at or beyond the current end of file (EOF), the function returns 0
and stores nothing into the buffer. Subsequent read operations attempt to read from the
device again, unless EOF is a hard EOF mark on stdin. In this case, all subsequent read
operations return 0 and store no data into the buffer.
7859 6137–009 5–105

ead()
Reading Different File Types
The file type determines the behavior of the read() function, as shown in the following
paragraphs.
Empty Pipe or FIFO File
The read() function performs as follows:
• If no process has the pipe or FIFO open for writing, read() returns 0 to indicate the
end of the file.
• If some process has the pipe or FIFO open for writing and the O_NONBLOCK flag
for the open file description corresponding to fildes is set (see the open() and fcntl()
functions), read() returns and sets errno to EAGAIN.
• If some process has the pipe or FIFO open for writing and the O_NONBLOCK flag is
clear, read() waits until some data is written or the pipe or FIFO is closed by all
processes that have the pipe or FIFO open for writing.
S_1100BIN File Created Outside of CIFS
These files can contain areas of unwritten data that are indistinguishable from valid data.
Reading these areas results in bytes with indeterminate values. A process must never
assume these areas are zero-filled.
S_1100SDF File
The read() function performs as follows:
• Translates Fieldata images to ASCII
• Removes all SDF attributes from the text returned, so the process cannot use this
attribute to read SDF line numbers
5–106 7859 6137–009

eaddir()
Application
readdir()
Use the readdir() function to read the current entry in a directory stream (that is, the
entry at the current position); readdir() then positions the directory stream at the next
entry. The dirent structure passes information about the directory entry, if a current entry
exists. Before reading a directory stream, you must open it.
You can distinguish the end of the directory from error cases; see “Finding the End of
the Directory” in this subsection.
See opendir() for opening a directory stream, closedir() for closing an open directory, and
rewinddir() for repositioning a directory stream at its beginning.
Synopsis
struct dirent * readdir(DIR * dirp);
Description
The readdir() function reads the next entry in a directory stream, where dirp is a pointer
to the directory stream from which to read the directory entry. The directory stream
must have been opened previously by opendir().
The dirent Structure
The dirent structure passes the location of the file for each entry in a directory stream.
The following table describes type struct dirent, which is defined in .
Member
Name Member Type Description
d_ino ino_t File serial number, unique for the file in its file
system
d_name char * Nul-terminated file name
Note: Other fields in the dirent structure are reserved for internal use by CIFS.
Calling readdir() Repeatedly
If a process opens a directory and then repeatedly calls readdir() on the directory stream,
readdir() returns one entry for each file continuously in the directory from the time of the
opendir() call. This includes one entry for the dot file (d_name is “ . “) and one entry for
the dot-dot file (d_name is “ .. “).
Every time readdir() reads the same directory stream, it overwrites the previous directory
entry returned.
Multiple Directory Streams
Performing readdir() on one directory stream never interferes with entries in other
directory streams.
7859 6137–009 5–107

eaddir()
Sharing Directory Streams with Child Processes
When a process calls tskstart() and _cifs_new_process(), it shares with its child both its
directory streams and its open file descriptions. Either the parent or the child process
can read entries first. Either process can rewind the shared directory stream with
rewinddir(). If one process changes the positioning of a shared directory stream, that
change is immediately visible to the other process.
Finding the End of the Directory
Use the following procedure to distinguish the end of the directory from error cases:
1. Set errno to 0.
2. Call readdir().
3. Check the value of errno if readdir() returns a null pointer.
• If errno equals 0, readdir() reached the end of the directory.
• If errno does not equal 0, readdir() returned an error.
See “Return Values” below to see when readdir() returns a null pointer.
Return Values
If the readdir() function completes successfully, it does the following:
• Updates the st_atime of the directory each time the directory is actually read. The
function can store several entries for one call in the buffer and not do actual read
operations for other calls. The update to st_atime is not written to nonvolatile
storage until the directory stream is closed by one of the following events:
− A call to closedir()
− Process termination
• Returns one of the following:
− A pointer to a directory entry
− A null pointer, if no more entries exist. In this case, readdir() does not change the
value of errno.
Otherwise, readdir() sets errno to identify the specific error and returns a null pointer.
Error Codes
If any of the following conditions occurs, the readdir() function returns a null pointer and
sets errno to the corresponding value:
EBADF dirp does not point to a valid DIR object representing a directory stream.
EFAULT dirp is not a valid pointer.
5–108 7859 6137–009

ealpath()
Application
The realpath() function returns the fully-resolved, absolute path of a specified file.
Synopsis
char * realpath(char * file_name, char * resolved_name, ...)
Description
realpath()
The function attempts to find the full path in which file_name resides, and returns the
result in resolved_name. An integer third argument (optional) can be used to specify the
size of the resolved_name string area; if it is zero or not given, the default size is 1024.
Return Values
Upon successful completion, the function returns a pointer to resolved_name. If
unsuccessful, it returns NULL and sets errno to an appropriate value. If the return value
is NULL and errno is ENOENT, resolved_name has been filled in with the fully-expanded
path, but the file in question does not exist. In all other cases where NULL is returned,
the contents of resolved_name are indeterminate.
7859 6137–009 5–109

emove()
remove()
Application
Use the remove() function to remove any type of named file, including an empty
directory.
Synopsis
int remove(const char * pathname);
Description
The remove() function causes a file to be removed, where path points to the name of the
file. If the file is open, any subsequent input or output operations to the file do not fail.
Subsequent attempts to open the file fail unless the file is re-created.
Return Values
If the remove() function completes successfully, it returns 0. Otherwise, remove()
returns a nonzero value and sets errno to an appropriate value.
5–110 7859 6137–009

ename()
Application
rename()
Use the rename() function to change the path name of an existing file. The new entry
can be in the same directory or in different directories. If it is in the same directory, the
file name must be unique.
If the new path name also resolves to an existing file, the link to that file is removed
before the name is reused; this possibly removes the unlinked file from the file system
(see “General Rules for Renaming Files” in this subsection).
See the link() function for creating new directory entries for a file and the unlink() function
for removing file links.
Synopsis
int rename(const char * old, const char * new);
Description
The rename() function changes the path name of an existing file, where:
old
new
is a pointer to the file to rename.
is a pointer to the new path name to attach to the file.
Neither old nor new can refer to a character file.
Example 1
The following example illustrates a simple rename operation within a directory:
7859 6137–009 5–111

ename()
Example 2
The following diagram illustrates a simple rename operation between two directories:
Example 3
The following diagram illustrates a complex rename operation, where the new path
name resolves to an existing file. The existing link to /dir_2/file_2 is removed first; then
the rename operation is similar to example 2, with a different file name.
General Rules for Renaming Files
The following general rules apply to renaming files:
• If the old and new path names resolve to the same file, rename() returns
successfully without making any changes.
• If the old and new path names do not resolve to the same file, the following rules
apply:
− The process must have write-access permission to the directory containing the
link to the old file.
− The process must have write-access permission to the directory that contains
the new link.
• If the new path name resolves to an existing file, the file is unlinked from the last
directory in the new path name before its name is reused for old.
5–112 7859 6137–009

ename()
If no other links to the file exist, the file is removed from the file hierarchy as soon as
all references to it are closed (see the close() function). The dot and dot-dot entries
cannot be manipulated by the rename() and rmdir() functions. These entries are
automatically deleted from a directory when its last link is removed.
Special Rules for Renaming a Directory
The following special rules apply to renaming a directory:
• The process must have write-access permission to the old directory.
• If the new path name exists in the file system, it must resolve to a directory.
• If the new path name resolves to an existing directory, the process must have writeaccess
permission to it and it must be empty.
• The old path name must not resolve to a directory contained in the new path name.
Special Rules for Renaming a Nondirectory File
The new path name must not resolve to an existing directory.
Return Values
If the rename() function completes successfully, it does the following:
• Updates the st_atime and st_mtime fields of the parent directory of each file
• Returns 0
Otherwise, rename() sets errno to identify the specific error and returns -1.
Error Codes
If any of the following conditions occurs, the rename() function returns -1 and sets errno
to the corresponding value:
EACCES Any of the following errors occurred:
• The calling process is denied search permission to a component of
either path name.
• The calling process is denied write permission to directories
containing either old or new.
• The calling process is denied write permission to directories to
which either old or new point.
EEXIST The link named by new is a directory with entries other than dot and dotdot;
that is, it is not an empty directory.
EFAULT The pointer specified by old or new is invalid.
EINVAL One of the following errors occurred:
• The directory path name in new contains the directory name in old.
• The last component of either old or new is either dot or dot-dot.
EISDIR The path name in new resolves to a directory, and the path name in old
resolves to a file that is not a directory.
7859 6137–009 5–113

ename()
ENOENT
Either of the following errors occurred:
• The link named by old does not exist.
• Either old or new points to an empty string.
ENOSPC The parent directory of new has too many entries.
ENOTDIR Either of the following errors occurred:
• A component of either path name prefix is not a directory.
• old names a directory, and new names a file that is not a directory.
5–114 7859 6137–009

ewind()
Application
rewind()
Use the rewind() function to set the file position indicator to the beginning of a stream.
Synopsis
void rewind(FILE * stream);
Description
The rewind() function is equivalent to the following call to fseek():
fseek(stream, OL, SEEK_SET);
Detecting Error Cases
Use the following procedure to detect error cases:
1. Set errno to 0.
2. Call rewind().
3. Check the value of errno.
• If errno equals 0, rewind() did not detect an error.
• If errno does not equal 0, rewind() detected an error.
Return Values
The rewind() function returns no value. It clears the error indicator if no problems are
encountered.
7859 6137–009 5–115

ewinddir()
rewinddir()
Application
Use the rewinddir() function to reposition a directory stream at its beginning. The
rewinddir() function updates the directory stream to reflect the current state of the
directory, making visible any directory entries added since the directory stream was
opened.
You can distinguish a successful call to rewinddir() from error cases; see “Detecting
Error Cases” in this subsection.
See opendir() for opening a directory, closedir() for closing an open directory, and
readdir() for reading the next directory entry.
Synopsis
void rewinddir(DIR * dirp);
Description
The rewinddir() function resets the position of the directory stream to its beginning,
where dirp is a pointer to the directory stream to rewind. The directory stream must
have been opened previously by opendir().
Detecting Error Cases
Use the following procedure to detect error cases:
1. Set errno to 0.
2. Call rewinddir().
3. Check the value of errno.
• If errno equals 0, rewinddir() did not detect an error.
• If errno does not equal 0, rewinddir() detected an error.
Return Values
The rewinddir() function returns no value.
Error Codes
If any of the following conditions occurs, the rewinddir() function sets errno to the
corresponding value:
EBADF dirp does not point to a valid DIR object representing an open
directory stream.
EFAULT dirp is not a valid pointer.
5–116 7859 6137–009

mdir()
Application
Use the rmdir() function to remove an empty directory from the file system.
Synopsis
int rmdir(const char * path);
Description
rmdir()
The rmdir() function removes an empty directory and its dot and dot-dot entries, where
path is a pointer to the directory to remove. The directory cannot be the system root
directory.
If any process has the directory open or has an open directory stream (see the opendir()
function) when rmdir() removes the last link, the directory contents remain accessible
until all references are closed.
Return Values
If the rmdir() function completes successfully, it does the following:
• Updates the st_atime and st_mtime fields of the parent directory
• Returns 0
Otherwise, rmdir() sets errno to identify the specific error and returns -1.
Error Codes
If any of the following conditions occurs, the rmdir() function returns -1 and sets errno to
the corresponding value:
EACCES Any of the following errors occurred:
• The calling process is denied search permission to a component of
the path name.
• The calling process is denied write permission to the parent directory
of the directory to be removed.
EEXIST path names a directory that is not empty.
EFAULT The pointer specified by path is invalid.
EINVAL The calling process is requesting that the dot or dot-dot entry in a directory
be removed.
EIO An I/O error prevented the completion of the function.
ENOENT Either of the following errors occurred:
• The directory does not exist.
• path points to an empty string.
ENOTDIR A component of the path name is not a directory.
7859 6137–009 5–117

scanf()
scanf()
Application
Use the scanf() function to read formatted input from the standard input.
Synopsis
int scanf(const char * format, ...);
Description
The scanf() function is equivalent to calling fscanf() using stdin as the file pointer, as
follows:
fscanf(stdin, format, ...);
See fscanf() for a description of the format argument.
Return Values
If it completes successfully, the scanf() function returns either of the following:
• The number of assigned input items, which can be 0 in the event of an early conflict
between an input character and the format
• EOF, if it encounters end of file before the first conflict or conversion
Otherwise, scanf() returns when it encounters the end of the format string.
5–118 7859 6137–009

share()
Application
share()
Use _cifs_share() to specify the network-visible name for the given directory. The share
name cannot be more than 31 characters long.
Notes:
• There is no POSIX equivalent to _cifs_share().
• Many network clients cannot access share names with more than 12 characters.
Synopsis
int _cifs_share(const char * path, const char * share_name);
Description
The path parameter must specify a directory to which the caller has full access. The
share_name parameter must be NULL or point to a string of 31 or fewer characters from
the printable ASCII set, not including the slash (/), back slash (\), question mark (?),
asterisk (*), or comma (,) characters. If the share_name pointer is NULL or an empty
string, the call removes network visibility for the directory. If the share_name string
contains invalid characters, the network visibility for the directory is unchanged.
Otherwise, the share_name becomes the network name for the directory, replacing any
existing name.
Return Values
Returns a value of zero if successful and a value of -1 if any errors are detected (with
errno set to the appropriate value).
7859 6137–009 5–119

sprintf()
sprintf()
Application
Use the sprintf() function to write formatted output to a character array.
Synopsis
int sprintf(char * s, const char * format, ...);
Description
The sprintf() function is equivalent to fprintf, except that the argument s specifies a
character array to which the generated output is written (rather than to a stream). A nul
character is appended after the characters are written, but the nul character is not
counted as part of the returned sum.
Return Values
The sprintf() function returns the number of characters written to the array, not counting
the terminating nul character.
5–120 7859 6137–009

sscanf()
Application
Use the sscanf() function to read formatted input from a string.
Synopsis
int sscanf(const char * s, const char * format, ...);
Description
sscanf()
The sscanf() function is equivalent to fscanf(), except that the argument s specifies a
string from which the input is read (rather than from a stream). Reaching the end of the
string is equivalent to encountering end of file for the fscanf() function.
Return Values
If it completes successfully, the sscanf() function returns the number of assigned input
items (which can be 0 in the event of an early conflict between an input character and
the format). Otherwise, sscanf() returns when it encounters the end of the format string.
7859 6137–009 5–121

stat()
stat()
Application
Use the stat() function to retrieve information about a named file. In particular, you can
get information about the file mode, security attributes, file size, and access times.
The stat() function uses a path name to identify the file. See the fstat() function for a
similar function that uses a file descriptor.
Synopsis
int stat(const char * path, struct stat * buf);
Description
The stat() function returns information about a file in a stat structure, where:
path
buf
is a pointer to the requested file.
is a pointer to a stat structure in which stat() returns the file information; see the
fstat() function for the contents of the stat structure.
The calling process does not need read, write, or execute permission to the file; but it
must have search permission to all directories in the path name leading to the file. Refer
to the fstat() function for a table that describes the stat structure.
Return Values
If the stat() function completes successfully, it returns 0. Otherwise, stat() sets errno to
identify the specific error and returns -1.
Error Codes
If any of the following conditions occurs, the stat() function returns -1 and sets errno to
the corresponding value:
EACCES The calling process is denied search permission to a directory in the path
name.
EFAULT The pointer specified by path is invalid.
ENOENT Either of the following errors occurred:
• The file or directory does not exist.
• path points to an empty string.
ENOTDIR A component of the path name prefix is not a directory.
5–122 7859 6137–009

strerror()
Application
strerror()
Use the strerror() function to retrieve the error message associated with a particular error
number.
Synopsis
char * strerror(int errnum, ...);
Description
The strerror() function retrieves the ELMS text for the specified error number, errnum,
using first the CIFS component, and then the URTS component if the message does not
exist within CIFS. There are two optional arguments used to specify insert text for the
requested message. The second argument (first additional) is an integer giving the
number of inserts. The third argument (second additional) is an array of character
pointers, where each pointer gives the location of an insert string appropriate for the
message.
Return Values
The strerror() function returns a pointer to the retrieved message text with any inserts
applied. This area is modifiable by the caller and is overwritten on subsequent calls to
strerror().
7859 6137–009 5–123

tmpfile()
tmpfile()
Application
Use the tmpfile() function to create a temporary file for use while a program executes.
Synopsis
FILE * tmpfile();
Description
The tmpfile() function creates a temporary file, where FILE is an opaque data type that
describes an open instance of a file. The file is opened for update and automatically
removed at program termination.
Default Permissions When Creating a File
If the tmpfile() function creates a file, it assigns read and write permissions to the owner,
group, and other permission classes by default. The following file mode specification for
the open() function is equivalent:
S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH
Return Values
The tmpfile() function returns a pointer to the stream of the file that it created. If the file
cannot be created, tmpfile() returns a null pointer.
5–124 7859 6137–009

tmpnam()
Application
tmpnam()
Use the tmpnam() function to generate a string to use as a file name that is different
from any existing file name.
Synopsis
char * tmpnam(char * s);
Description
The tmpnam() function generates a string that is not the same as the name of an existing
file, where s is a pointer to an array for the results.
The tmpnam() function generates a different string each time it is called.
Note: Files created using strings generated by the tmpnam() function are temporary
only in the sense that their names must not conflict with those generated by
conventional naming rules for the implementation. You must still use the remove()
function to remove such files when their use is ended and before program termination.
Return Values
If s is a null pointer, tmpnam() leaves its result in an internal static object and returns a
pointer to that object. Subsequent calls to tmpnam() can modify the same object.
If s is not null, it is assumed to point to an array of at least L_tmpnam characters.
tmpnam() writes its result in that array and returns the argument as its value.
7859 6137–009 5–125

truncate()
truncate()
Application
Use the truncate() function to set the end-of-file position for an existing regular file.
Synopsis
int truncate(const char * path, off_t length);
Description
A regular file whose name is given by path has its size (in bytes) set to length. If the file
was previously longer than the length specified, those bytes are no longer accessible. If
the file was previously shorter than the length specified, bytes between the old
end-of-file and the specified length are read as zeroes. For truncate(), the caller must
have write access to the file.
For files stored in SDF format, the length value of 34359738367 (defined as INT_MAX in
the limits.h header file) has special meaning. CIFS treats this as an indication that it must
recalculate the actual size of the file when it is next read based on the position of the
EOF record, rather than pad the file with zeroes.
Return Values
Upon successful completion, the function returns a value of 0. If unsuccessful, it returns
a value of -1 and sets errno to the appropriate value.
5–126 7859 6137–009

umask()
Application
umask()
Use the umask() function to create the file mode creation mask for the calling process
and save its previous version.
Synopsis
mode_t umask(mode_t cmask);
Description
The umask() function sets the file mode creation mask, where cmask contains the value
for the mask.
The file mode creation mask is a process attribute that limits the permissions the
process can attach to a file. The mask is a set of attributes corresponding to read, write,
and search/execute permissions for each of the owner, group, and other permission
classes. If an attribute is set in the mask, that permission is denied when files are
created. For example, to prohibit anyone in the group and other permission classes from
writing to a file, set the corresponding attributes in the file mode creation mask before
creating the file.
Functions that create files request file permissions through a mode argument in the call
statement. However, they first apply the file mode creation mask to turn off
corresponding permissions that are set in the mode argument. For example, if the
attributes for group and other write permissions are set in the file mode creation mask,
those permissions are not set for files created subsequently.
Note: To apply the file mode creation mask, functions perform a bitwise AND
operation between the value of mode and the complement of the file mode creation
mask.
Setting the File Mode Creation Mask
You can set the file mode creation mask using any of the symbolic constants for the
individual or group permission settings, as follows:
mode_t fmc_mask; /* Previous mask value */
fmc_mask = umask(S_IWGRP | S_IRWXO);
The previous code sets the file mode creation mask to contain both of the following:
• Write access by the group class
• Any access by the other class
The mask, then, prohibits those permissions for functions that apply the mask to the
mode argument.
7859 6137–009 5–127

umask()
Return Values
The umask() function returns the previous value of the file mode creation mask.
Error Codes
The umask() function returns no error conditions.
5–128 7859 6137–009

uname()
Application
Use the _cifs_uname() function to retrieve version information about the CIFS
subsystem.
Note: There is no POSIX equivalent to _cifs_uname().
Synopsis
int _cifs_uname(char * cifs_bdi, char * cifs_name);
Description
uname()
The _cifs_uname() function returns version information about the CIFS subsystem. The
cifs_bdi parameter receives the bank descriptor index (BDI) of the subsystem gate bank,
in symbolic form. The space pointed to by cifs_bdi must be able to hold 8 characters.
The cifs_name parameter is filled with the subsystem name, the date and time of the
subsystem construction, and the build number. The cifs_name area must be at least 48
characters long.
Return Values
The _cifs_uname() function returns zero for successful completions or -1 for errors.
When an error is detected, errno is set to an appropriate value.
7859 6137–009 5–129

ungetc()
ungetc()
Application
Use the ungetc() function to return a character to the input stream, causing the next read
operation to read that character.
Synopsis
int ungetc(int c, FILE * stream);
Description
The ungetc() function pushes a character back onto the input stream, where:
c
FILE
stream
specifies the character.
is an opaque data type that describes an open instance of a file.
is a pointer to a FILE object for input. The external storage corresponding to the
stream is unchanged.
The character is returned by the next read on that stream, provided no intervening call to
fseek() erases all memory of pushed-back characters.
Notes:
• ungetc() at end of file is legal; it causes feof() to return false until the character is reread.
• ungetc() does not change the value of the file pointer.
• ungetc() is not allowed for output operations.
Return Values
If it completes successfully, the ungetc() function returns the character pushed back to
the input stream. Otherwise, ungetc() returns EOF.
5–130 7859 6137–009

unlink()
Application
unlink()
Use the unlink() function to remove a link from a named, nondirectory file, which
decreases the file's link count by 1. If the link count becomes 0, unlink() deletes the file
from the file system.
See the rename() function for changing the name of a file and the link() function for
creating new directory entries for a file.
Synopsis
int unlink(const char * path);
Description
The unlink() function removes a link from a file, where path is a pointer to the file link to
be removed. Path cannot point to a directory; use rmdir() to remove a directory.
If a process has the file open when it is being removed, that process can continue to
access the file through the open file descriptor.
Return Values
If the unlink() function completes successfully, it does the following:
• Updates the st_atime and st_mtime fields of the parent directory
• Updates the st_atime field of the file, if the file's link count is not 0
• Returns 0
Otherwise, unlink() sets errno to identify the specific error and returns -1.
Error Codes
If any of the following conditions occurs, the unlink() function returns -1 and sets errno to
the corresponding value:
EACCES Any of the following errors occurred:
• The calling process is denied search permission to a component of
the path name.
• The calling process is denied write permission to the directory
containing the link to be removed.
EFAULT The pointer specified by path is invalid.
ENOENT Either of the following errors occurred:
• The file does not exist.
• path points to an empty string.
ENOTDIR A component of the path name prefix is not a directory.
7859 6137–009 5–131

utime()
utime()
Application
Use the utime() function to change the access time and modification time of a file, using
either the current system time or an arbitrary time setting. You can retrieve these values
into a stat structure using the stat() function.
These times are also changed by functions that perform input and output operations on
the file; check the paragraphs under “Return Values” for each function to see which
time fields the function updates, if any.
Privilege Requirement
For a process to change the access time and modification time of a file, one of the
following must be true:
• The process is privileged.
• The effective user ID of the process is equal to the owning user ID of the file.
Synopsis
int utime(const char * path, const struct utimbuf * times);
Description
The utime() function sets the access time and modification time of a file to either the
current time or the values in the utimbuf structure, where:
path
times
is a pointer to the file.
controls how utime() sets the access time and modification time; it is one of the
following:
• A null pointer
utime() sets both the access time and modification time of the file to the current
system time if
− The calling process is allowed to change the times (see “Privilege
Requirement” in this subsection)
− The calling process has write permission to the file.
• A pointer to a utimbuf structure
utime() sets the access time and modification time of the file to the values in the
structure if the calling process is allowed to change the times (see “Privilege
Requirement” in this subsection). Whether the process has write permission to
the file is immaterial.
5–132 7859 6137–009

The utimbuf Structure
The following table describes the utimbuf structure, which is defined in the header
:
Member
Name
Member
Type* Description **
actime time_t This value is put into the st_atime field of the file.
modtime time_t This value is put into the st_mtime field of the file.
* Type time_t is an arithmetic type capable of representing a time value.
** Time values are measured in seconds from 00:00:00 January 1, 1970, local time.
Setting Values in the utimbuf Structure
utime()
The following program fragment sets the values in the utimbuf structure to the current
time, using the time() function. It then uses these values to update the st_atime and
st_mtime fields for the file /my_dir/my_file.
#include
#include
#include
...
time_t time_of_day;
...
{ struct utimbuf file_times;
time_of_day = time_of_day;
file_times.actime = time_of_day;
file_times.modtime = time_of_day;
utime("/my_dir/my_file", &file_times);
}
...
Return Values
If the utime() function completes successfully, it returns 0; otherwise, utime() sets errno
to identify the specific error and returns -1.
7859 6137–009 5–133

utime()
Error Codes
If any of the following conditions occurs, the utime() function returns -1 and sets errno to
the corresponding value:
EACCES Either of the following errors occurred:
• The calling process is denied search permission on a directory in
the path name.
• times is a null pointer, and all of the following are true:
− The effective user ID of the calling process does not match
the user ID of the owner of the file.
− The calling process is denied write permission to the file.
− The process is not privileged.
EFAULT The pointer specified by path is invalid.
ENOENT Either of the following errors occurred:
• The file does not exist.
• path points to an empty string.
ENOTDIR A component of the path name prefix is not a directory.
EPERM All of the following are true:
• times is not null.
• The effective user ID of the calling process does not match the
file's owner.
• The process is not privileged.
5–134 7859 6137–009

vfprintf()
Application
Use the vfprintf() function to write formatted output.
Synopsis
int vfprintf(FILE * stream, const char * format, va_list arg);
Description
vfprintf()
The vfprintf() function is equivalent to fprintf(). The variable argument list is replaced by
arg, which has been initialized by va_start() and possibly by subsequent calls to va_arg().
The vfprintf() function does not call va_end().
Return Values
If it completes successfully, the vfprintf() function returns the number of characters
transmitted. Otherwise, vfprintf() returns a negative value.
7859 6137–009 5–135

vprintf()
vprintf()
Application
Use the vprintf() function to write formatted output to the standard output.
Synopsis
int vprintf(const char * format, va_list arg);
Description
The vprintf() function is equivalent to printf(). The variable argument list is replaced by
arg, which has been initialized by va_start() and possibly by subsequent calls to va_arg().
The vprintf() function does not call va_end().
Return Values
If it completes successfully, the vprintf() function returns the number of characters
transmitted. Otherwise, vprintf() returns a negative value.
5–136 7859 6137–009

vsprintf()
Application
Use the vsprintf() function to write formatted output to a character array.
Synopsis
int vsprintf(char * s, const char * format, va_list arg);
Description
vsprintf()
The vsprintf() function is equivalent to sprintf(). The variable argument list is replaced by
arg, which has been initialized by va_start() and possibly by subsequent calls to va_arg().
The vsprintf() function does not call va_end().
Return Values
If it completes successfully, the vsprintf() function returns the number of characters
written to the array, not counting the terminating nul character.
7859 6137–009 5–137

write()
write()
Application
Use the write() function to write data to a file at the current read/write position. Use the
lseek() function to reposition the read/write offset. See the following subsections for
more information: “Determining the Number of Bytes Written,” “Starting Position for
Different File Types,” “Writing Different File Types,” and “Translating Special
Characters.”
Synopsis
ssize_t write(int fildes, const void * buf, size_t nbyte);
Description
The write() function writes data from a buffer to an open file, where:
fildes
buf
nbyte
is a file descriptor.
is a pointer to the buffer holding the data.
is the number of bytes to be written, which is limited by the size of a data bank.
Attempting to Write Beyond the Limits
The write() function fails if the file position exceeds the maximum size of the file.
Return Values
If the write() function completes successfully, it does the following:
• Updates the st_atime and st_mtime fields (see the fstat() and stat() functions) of the
file, if the function wrote any bytes
• Returns the number of bytes actually written to the file
Otherwise, write() sets errno to identify the specific error and returns -1.
5–138 7859 6137–009

Error Codes
write()
If any of the following conditions occurs, the write() function returns -1 and sets errno to
the corresponding value:
EAGAIN The O_NONBLOCK flag is set, the calling process is writing to a pipe
or FIFO, and one of the following conditions occurred:
• The pipe or FIFO is full.
• The pipe or FIFO does not have nbyte space available.
EBADF fildes is not a valid file descriptor open for writing.
EFAULT One of the following errors occurred:
• buf points to an invalid address, and nbyte is greater than 0.
• buf is valid, but (buf+(nbyte-1)) points to an invalid address.
EFBIG The calling process is attempting to write at a starting position beyond
the highest position allowed for the file.
EIO A disk error occurred.
EPIPE One of the following errors occurred:
• An attempt is made to write to a pipe or FIFO file that is not open
for reading by any process.
• While waiting for room in a pipe, all file descriptors open for
reading the pipe are closed.
Determining the Number of Bytes Written
The write() function returns the number of bytes actually written from the buffer to the
file, which is never greater than nbyte. The following paragraphs relate this return value
to the input value of nbyte.
Return Value = nbyte > 0
The write() function wrote and stored the exact number of bytes requested.
Return Value < nbyte
The value returned is less than nbyte if one of the following statements is true:
• Fewer than nbyte bytes can be written without exceeding the maximum size of the
file.
• The file is a pipe or FIFO that has fewer than nbyte bytes immediately available for
writing.
Return Value = 0
The value returned is 0 if the value of nbyte is 0.
Starting Position for Different File Types
The file type determines the first byte in the file to be written, as shown in the following
paragraphs.
7859 6137–009 5–139

write()
Regular Files
The function starts at the current position of the read/write offset associated with the
open file description corresponding to fildes. Before returning, write() increases the
read/write offset by the number of bytes written to the file.
If the O_APPEND flag associated with the open file description corresponding to fildes is
set, the read/write offset is set to the end of the file immediately before each write
operation.
Writing data to locations beyond the end of the file causes the file to expand
automatically.
Pipes and FIFO Files
The function starts at the current position associated with the file corresponding to
fildes.
Writing to Different File Types
The file type determines the behavior of the write() function, as shown in the following
paragraphs.
Regular Files
Data accumulates in buffers, which are written to nonvolatile storage when all processes
have closed the file (see the close() function).
Pipes and FIFO Files
Pipes and FIFO files have a storage capacity of 7,168 bytes to store data until it is read.
No data is written to nonvolatile storage.
If the pipe or FIFO file is full, a process must wait for data to be read from it before
writing data to it. The O_NONBLOCK flag associated with the open file description
corresponding to fildes (see the open() and fcntl() functions) determines the behavior of
write() for pipes and FIFO files, as follows:
5–140 7859 6137–009

O_NONBLOCK
Set write() does one of the
following:
Value of nbyte
≤ 7,168* > 7,168**
• Successfully writes all
the data
• Returns an error
condition if there is not
room for all the data
Clear write() waits for room in
the file for all the data
write() does one of the
following:
• Writes as much data as
immediately possible and
returns the number of
bytes written. (If the pipe
or FIFO file is empty,
write() transfers 7,168
bytes.)
• Returns an error condition
if the pipe or FIFO file is
full.
write()
write() transfers data to the
pipe, not returning until one of
the following occurs:
• The nbyte bytes are
written
• If the pipe is empty,
write() transfers at least
7,168 bytes before
returning.
* If a process writes 7,168 bytes or less to a pipe, the data in the pipe is guaranteed to be
contiguous.
** If a process writes more than 7,168 bytes to a pipe, the data can alternate with data from
other processes writing to the pipe.
The call returns an error condition if one of the following occurs:
• No process has the pipe open for reading.
• While write() is waiting for data to be read from a pipe, all file descriptors open for
reading the pipe are closed.
Translating Special Characters
The newline (\n) characters have special meaning for a write operation when fildes refers
to stdout, stderr, or an SDF file. The newline character causes write() to write the
characters preceding the newline since the end of the last line as either of the following:
• One line to stdout or stderr
• One image to the SDF file
7859 6137–009 5–141

xlate()
xlate()
Application
Use the _cifs_xlate() function to set or retrieve the translation attributes for a directory.
Note: There is no POSIX equivalent to _cifs_xlate().
Synopsis
int _cifs_xlate(const char * path, enum xlate_func func, char * ccs_in,
char * ccs_out);
Description
The path parameter specifies the directory for which translation information is set or
retrieved. The func setting must be one of the following: XLATE_GET, XLATE_SET_IN,
XLATE_SET_OUT, or XLATE_SET_BOTH.
For XLATE_GET, ccs_in and ccs_out specify where to return the coded character set
(CCS) names for the directory; the resulting values will be empty strings if translation is
not enabled for the specified directory.
For XLATE_SET_IN and XLATE_SET_BOTH, ccs_in is the CCS name used to establish
the translation mode for files written into the directory; an empty string turns off
translation.
For XLATE_SET_OUT, ccs_out is the CCS name used to establish the translation mode
for files read from the directory; an empty string turns off translation.
See the CIFSUT xlate command for a list of valid CCS names.
Return Values
If the _cifs_xlate() function completes successfully, it returns zero. Otherwise, it returns
-1 and sets an errno value.
Error Codes
If errors are detected, _cifs_xlate() returns -1 and sets errno to an appropriate value.
Some of the possible values are:
ECCSNAME One or both of the requested CCS names is not known to
CIFS.
ENOTDIR The requested path is not a directory.
5–142 7859 6137–009

Section 6
COBOL Program Interfaces
This section lists the COBOL copy procs and application program interfaces (APIs)
supplied by the CIFSLIB component.
Table of UCOB COPY PROCS
The following table lists the UCOB COPY PROCS that are available to CIFS programs.
These PROCS are in the element CIFS-DEF in the file SYS$LIB$*CIFS$LIB.
Proc Name Description
CIFS-AMODE Contains definitions for CIFS$ACCESS
CIFS-API Contains definitions for the CIFS status definitions
CIFS-DIR Contains definitions for a DIR variable for directory service
subprograms
CIFS-FCNTL Contains definitions for the cifs-flock-struct variable for file
locking and cifs-fcntl-cmd variable for file control operations
CIFS-FILE Contains definitions for a FILE variable for stream service
subprograms
CIFS-FPOS Contains definitions for the cifs-fpos variable for file positioning
CIFS-MODE Contains definitions for the cifs-mode variable for CIFS$OPEN,
CIFS$CHMOD, and so on
CIFS-OFLAG Contains definitions for the cifs-oflag variable for CIFS$OPEN
CIFS-STAT Contains definitions for the cifs-stat and cifs-istat data item for
CIFS$STAT and CIFS$ISTAT
CIFS-XLATE Contains definitions for the cifs-xlate variable for CIFS$XLATE
commands
7859 6137–009 6–1

Table of UCOB APIs
Table of UCOB APIs
The following UCOB APIs are available for use from CIFS programs.
CIFS Call Parameters
CALL "CIFS$ACCESS" USING PATH, CIFS-AMODE, CIFS-STATUS
CALL "CIFS$CHDIR" USING PATH, CIFS-STATUS
CALL "CIFS$CHMOD" USING PATH, CIFS-MODE, CIFS-STATUS
CALL "CIFS$CHOWN" USING PATH, OWNER, GROUP, CIFS-STATUS
CALL "CIFS$CLEARERR" USING CIFS-FILE
CALL "CIFS$CLOSE" USING FD, CIFS-STATUS
CALL "CIFS$CLOSEDIR" USING CIFS-DIR, CIFS-STATUS
CALL "CIFS$CREAT" USING PATH, CIFS-MODE, NEW-FD, CIFS-STATUS
CALL "CIFS$DUP" USING OLD-FD, NEW-FD, CIFS-STATUS
CALL "CIFS$DUP2" USING FD-1, FD-2, CIFS-STATUS
CALL "CIFS$FCLOSE" USING CIFS-FILE, CIFS-STATUS
CALL "CIFS$FCNTL" USING FD, FCNTL-CMD, CMD-PARAM, RETURN-VALUE,
CIFS-STATUS
CALL "CIFS$FDATASYNC" USING FD, CIFS-STATUS
CALL "CIFS$FDOPEN" USING FD, TYPE, CIFS-FILE, CIFS-STATUS
CALL "CIFS$FEOF" USING CIFS-FILE, EOF-FLAG
CALL "CIFS$FERROR" USING CIFS-FILE, ERROR-FLAG
CALL "CIFS$FFLUSH" USING CIFS-FILE, CIFS-STATUS
CALL "CIFS$FGETC" USING CIFS-FILE, NEXT-CHAR, CIFS-STATUS
CALL "CIFS$FGETPOS" USING CIFS-FILE, CIFS-FPOS, CIFS-STATUS
CALL "CIFS$FGETS" USING STRING, MAX-CHARS, CIFS-FILE, CIFS-STATUS
CALL "CIFS$FILENO" USING CIFS-FILE, FD, CIFS-STATUS
CALL "CIFS$FOPEN" USING PATH, TYPE-STRING, CIFS-FILE, CIFS-STATUS
CALL "CIFS$FPRINTF" USING CHARS-OUT, CIFS-FILE, FORMAT-STRING[, ITEM...]
CALL "CIFS$FPUTC" USING CHAR, CIFS-FILE, CIFS-STATUS
CALL "CIFS$FPUTS" USING STRING, CIFS-FILE, CHARS-OUT, CIFS-STATUS
CALL "CIFS$FREAD" USING BUFFER, ELT-SIZE, ELT-COUNT, CIFS-FILE, ELTS-READ,
CIFS-STATUS
CALL "CIFS$FREOPEN" USING PATH, TYPE-STRING, CIFS-FILE, CIFS-STATUS
CALL "CIFS$FSCANF" USING ITEMS-SCANNED, CIFS-FILE, FORMAT-STRING[, ITEM...]
CALL "CIFS$FSEEK" USING CIFS-FILE, OFFSET, WHENCE, CIFS-STATUS
6–2 7859 6137–009

CIFS Call Parameters
CALL "CIFS$FSETPOS" USING CIFS-FILE, CIFS-FPOS, CIFS-STATUS
CALL "CIFS$FSTAT" USING FD, CIFS-STAT, CIFS-STATUS
CALL "CIFS$FSYNC" USING FD, CIFS-STATUS
CALL "CIFS$FTELL" USING CIFS-FILE, OFFSET, CIFS-STATUS
CALL "CIFS$FTRUNCATE" USING FD, LENGTH, CIFS-STATUS
Table of UCOB APIs
CALL "CIFS$FWRITE" USING BUFFER, ELT-SIZE, ELT-COUNT, CIFS-FILE, ELTS-WRITTEN,
CIFS-STATUS
CALL "CIFS$GETC" USING CIFS-FILE, NEXT-CHAR, CIFS-STATUS
CALL "CIFS$GETCHAR" USING NEXT-CHAR, CIFS-STATUS
CALL "CIFS$GETCWD" USING PATH-BUFFER, MAX-SIZE, CIFS-STATUS
CALL "CIFS$GETS" USING STRING, CIFS-STATUS
CALL "CIFS$ISTAT" USING INO, CIFS-ISTAT, SIZE, CIFS-STATUS
CALL "CIFS$LINK" USING PATH1, PATH2, CIFS-STATUS
CALL "CIFS$LSEEK" USING FD, OFFSET, WHENCE, NEW-OFFSET, CIFS-STATUS
CALL "CIFS$MASK" USING NAME, MASK, RESULT
CALL "CIFS$MKDIR" USING PATH, CIFS-MODE, CIFS-STATUS
CALL "CIFS$MKFIFO" USING PATH, CIFS-MODE, CIFS-STATUS
CALL "CIFS$OPEN" USING PATH, CIFS-OFLAG, CIFS-MODE, NEW-FD, CIFS-STATUS
CALL "CIFS$OPENDIR" USING PATH, CIFS-DIR, CIFS-STATUS
CALL "CIFS$PACK" USING PATH, CIFS-STATUS
CALL "CIFS$PERROR" USING CIFS-STATUS, MSG-STR
CALL "CIFS$PIPE" USING FD-PAIR, CIFS-STATUS
CALL "CIFS$PRINTF" USING CHARS-OUT, FORMAT-STRING[, ITEM...]
CALL "CIFS$PUTC" USING CHAR, CIFS-FILE, CIFS-STATUS
CALL "CIFS$PUTCHAR" USING CHAR, CIFS-STATUS
CALL "CIFS$PUTS" USING STRING, CIFS-STATUS
CALL "CIFS$READ" USING FD, BUFFER, BYTES-TO-READ, BYTES-READ, CIFS-STATUS
CALL "CIFS$READDIR" USING CIFS-DIR, ENTRY-INO, ENTRY-NAME, MAX-LEN, TRUE-LEN,
CIFS-STATUS
CALL "CIFS$REMOVE" USING PATH, CIFS-STATUS
CALL "CIFS$RENAME" USING OLD-PATH, NEW-PATH, CIFS-STATUS
CALL "CIFS$REWIND" USING CIFS-FILE, CIFS-STATUS
CALL "CIFS$REWINDDIR" USING CIFS-DIR, CIFS-STATUS
CALL "CIFS$RMDIR" USING PATH, CIFS-STATUS
7859 6137–009 6–3

Table of UCOB APIs
CIFS Call Parameters
CALL "CIFS$SCANF" USING ITEMS-SCANNED, FORMAT-STRING[, ITEM...]
CALL "CIFS$SHARE" USING PATH, SHARE-NAME, CIFS-STATUS
CALL "CIFS$SPRINTF" USING CHARS-OUT, DEST-STRING, FORMAT-STRING[, ITEM…]
CALL "CIFS$SSCANF" USING ITEMS-SCANNED, SCAN-STRING, FORMAT-STRING[, ITEM...]
CALL "CIFS$STAT" USING PATH, CIFS-STAT, CIFS-STATUS
CALL "CIFS$STDERR" USING CIFS-FILE
CALL "CIFS$STDIN" USING CIFS-FILE
CALL "CIFS$STDOUT" USING CIFS-FILE
CALL "CIFS$STRERROR" USING ERRNUM, MESSAGE-STRING[, INSERT-STRING…]
CALL "CIFS$TMPFILE" USING CIFS-FILE, CIFS-STATUS
CALL "CIFS$TMPNAM" USING NAME-STRING, CIFS-STATUS
CALL "CIFS$TRUNCATE" USING PATH, LENGTH, CIFS-STATUS
CALL "CIFS$UMASK" USING NEW-CIFS-MODE, OLD-CIFS-MODE, CIFS-STATUS
CALL "CIFS$UNAME" USING CIFS-SS-BDI, CIFS-SS-NAME, CIFS-STATUS
CALL "CIFS$UNGETC" USING PREV-CHAR, CIFS-FILE, RTN-CHAR, CIFS-STATUS
CALL "CIFS$UNLINK" USING PATH, CIFS-STATUS
CALL "CIFS$UTIME" USING PATH, CIFS-UTIMBUF, CIFS-STATUS
CALL "CIFS$WRITE" USING FD, BUFFER, BYTES-TO-WRITE, BYTES-WRITTEN,
CIFS-STATUS
CALL "CIFS$XLATE" USING PATH, CIFS-XLATE, CCS-IN, CCS-OUT, CIFS-STATUS
6–4 7859 6137–009

CIFS$ACCESS
Application
CIFS$ACCESS
Use the cifs$access service subprogram to determine if either of the following is true:
• A file exists.
• The calling process has permission to access a file.
Synopsis
CALL "cifs$access" USING path, cifs-amode, cifs-status.
Description
The cifs$access service subprogram checks file permissions or existence, where:
path
is a nul-terminated character string that contains the path name of the file.
cifs-amode
is a 1-word ( 1(36) BINARY-1 ) item that is used to determine what condition to
check for. Use the COBOL COPY PROC CIFS-AMODE in order to get the proper
declarations. Set the following data items based upon the condition you are checking
for:
• File permissions
Set the following variables that are within the CIFS-AMODE COPY PROC:
− CIFS-AMODE-R-OK (Check for read permission)
− CIFS-AMODE-W-OK (Check for write permission)
− CIFS-AMODE-X-OK (Check for search/execute permission)
• File existence
cifs-status
Set the variable CIFS-AMODE-F-OK in order to check whether the file or
directory exists.
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Checking File Permissions
The cifs$access service subprogram checks each permission requested in cifs-amode.
The service subprogram uses the real user ID and real group-ID of the calling process to
decide which file permission class (owner, group, or other) to check.
7859 6137–009 6–5

CIFS$ACCESS
Return Values
The cifs$access service subprogram returns 0 in the cifs-status parameter if all the
specified access permissions are allowed or if the file exists (whichever was requested).
Otherwise, cifs$access sets cifs-status to identify the specific error that was
encountered.
Error Codes
If any of the following conditions occurs, the cifs$access service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EACCES Either of the following errors occurred:
• One or more permissions specified by cifs-amode are denied.
• The calling process is denied search permission on a directory
in the path name.
CIFS-EFAULT The value specified by path is invalid.
CIFS-EINVAL An invalid value was specified for cifs-amode.
CIFS-ENOENT Either of the following errors occurred:
• The file does not exist.
• path contains an empty string.
CIFS-ENOTDIR A component of the path prefix is not a directory.
6–6 7859 6137–009

Example
CIFS$ACCESS
SPECIAL-NAMES.
SYMBOLIC nul IS 1.
:
WORKING-STORAGE SECTION.
COPY CIFS-API.
COPY CIFS-AMODE.
01 CIFS-AMODE PIC 1(36) BINARY-1.
01 CIFS-AMODE-BITS REDEFINES CIFS-AMODE.
03 FILLER PIC 1(32) BINARY-1.
03 CIFS-AMODE-F-OK PIC 1 BINARY-1.
03 CIFS-AMODE-R-OK PIC 1 BINARY-1.
03 CIFS-AMODE-W-OK PIC 1 BINARY-1.
03 CIFS-AMODE-X-OK PIC 1 BINARY-1.
01 ARGUMENT-1.
03 ARG1 PIC X(11).
03 FILLER PIC X VALUE NUL.
:
MOVE 'aaaaa/b.txt' TO ARG1 OF ARGUMENT-1.
MOVE 1 TO CIFS-AMODE-F-OK.
CALL "CIFS$ACCESS" USING ARGUMENT-1,
CIFS-AMODE,
CIFS-STATUS.
DISPLAY 'The CIFS-STATUS returned from CIFS$OPEN is ' CIFS-STATUS.
* Check if an invalid file or path error was returned
IF CIFS-ENOENT
DISPLAY 'Invalid directory or file'.
* If status returned is non-zero, call routine to print the error
IF CIFS-STATUS NOT EQUAL 0
CALL "CIFS$PERROR" USING CIFS-STATUS.
7859 6137–009 6–7

CIFS$CHDIR
CIFS$CHDIR
Application
Use the cifs$chdir service subprogram to change to a different current working directory.
Synopsis
CALL "cifs$chdir" USING path, cifs-status.
Description
The cifs$chdir service subprogram changes the current working directory of the calling
process, where path identifies the new directory.
path
is a nul-terminated character string that contains the path name of the file.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$chdir service subprogram completes successfully, it returns a value of 0 in the
cifs-status parameter. Otherwise, cifs$chdir sets cifs-status to identify the specific error
that was encountered.
Error Codes
If any of the following conditions occurs, the cifs$chdir service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EACCES
The calling process is denied search permission to a directory
in the path name.
CIFS- EFAULT The value specified by path is invalid.
CIFS-ENOENT
Either of the following errors occurred:
• The directory does not exist.
• path points to an empty string.
CIFS-ENOTDIR A component of the path name is not a directory.
6–8 7859 6137–009

CIFS$CHMOD
Application
CIFS$CHMOD
Use the cifs$chmod service subprogram to change the file permissions and program file
types of the mode for a file.
Privilege Requirement
For a process to change the file permissions and program file types of a file, the user ID
of the process must be equal to the user ID of the file.
Synopsis
CALL "cifs$chmod" USING path, cifs-mode, cifs-status.
Description
The cifs$chmod service subprogram changes the file permissions and program file types
bits, where:
path
is a nul-terminated character string that contains the path name of the file that is to
have its permissions modified.
cifs-mode
is a 1-word (1(36) BINARY-1) data item that contains the new settings for the file
permissions and program file types. Use the COBOL COPY PROC CIFS-MODE for
the declaration of this variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Open Files and Directory Streams
Any process with an open directory stream or a file descriptor to an open file can
continue accessing the stream or file, even if the cifs$chmod service subprogram
changes the permission bits.
7859 6137–009 6–9

CIFS$CHMOD
Changing File Permissions and Special File Attributes
If the process is allowed to change the file permissions of a file, cifs$chmod sets the file
permissions in the file mode to the values specified in cifs-mode. The cifs-mode data
item can be found in the COPY PROC CIFS-MODE, which looks as follows:
Return Values
01 CIFS-MODE PIC 1(36) BINARY-1.
01 CIFS-MODE-BITS REDEFINES CIFS-MODE.
03 CIFS-MODE-1100BIN PIC 1 BINARY-1.
03 CIFS-MODE-1100SDF PIC 1 BINARY-1.
03 CIFS-MODE-DIRECT PIC 1 BINARY-1.
03 CIFS-MODE-LEPF PIC 1 BINARY-1.
03 CIFS-MODE-NPF PIC 1 BINARY-1.
03 FILLER PIC 1(11) BINARY-1.
03 CIFS-MODE-SDF-ELEMENT PIC 1 BINARY-1.
03 CIFS-MODE-BIN-ELEMENT PIC 1 BINARY-1.
03 CIFS-MODE-UNKNOWN PIC 1 BINARY-1.
03 FILLER PIC 1 BINARY-1.
03 CIFS-MODE-REGULAR PIC 1 BINARY-1.
03 CIFS-MODE-DIRECTORY PIC 1 BINARY-1.
03 CIFS-MODE-CHARACTER PIC 1 BINARY-1.
03 CIFS-MODE-PIPE PIC 1 BINARY-1.
03 CIFS-MODE-ISUID PIC 1 BINARY-1.
03 CIFS-MODE-ISGID PIC 1 BINARY-1.
03 FILLER PIC 1 BINARY-1.
03 CIFS-MODE-IRWXU PIC 111 BINARY-1.
03 CIFS-MODE-IRWXG PIC 111 BINARY-1.
03 CIFS-MODE-IRWXO PIC 111 BINARY-1.
77 CIFS-MODE-IREAD PIC 1(36) BINARY-1 VALUE 4.
77 CIFS-MODE-IWRITE PIC 1(36) BINARY-1 VALUE 2.
77 CIFS-MODE-IEXEC PIC 1(36) BINARY-1 VALUE 1.
If the cifs$chmod service subprogram completes successfully, it returns a value of 0 in
the cifs-status parameter and updates the time of last access for the file. Otherwise,
cifs$chmod sets cifs-status to identify the specific error that was encountered.
6–10 7859 6137–009

Error Codes
CIFS$CHMOD
If any of the following conditions occurs, the cifs$chmod service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EACCES The calling process is denied search permission to a
directory in the path name.
CIFS-EFAULT The value specified by path is invalid.
CIFS-EINVAL Any of the following errors occurred:
• cifs-mode has undefined bits set.
• cifs-mode has bits set that cifs$chmod cannot
change.
• A path name component is longer than 4095
characters.
CIFS-ENOENT Either of the following errors occurred:
• The file does not exist.
• path contains an empty string.
CIFS-ENOTDIR A component of the path name is not a directory.
CIFS-EPERM Both of the following conditions are true:
• The effective user ID does not match the owner of
the file or directory.
• The process is privileged.
7859 6137–009 6–11

CIFS$CHOWN
CIFS$CHOWN
Application
Use the cifs$chown service subprogram to change the security attributes (user ID and
group ID) of a file, assigning the file to a different owner and group. If the value of the
CIFS$ACR environment variable is not blank, that value (public, private, or ACR name)
can also be applied to the specified file.
For a process to change the security attributes of a file, one of the following must be
true:
• The user ID of the process is equal to the user ID of the file.
• The process is privileged.
Synopsis
CALL "cifs$chown" USING path, owner, group, cifs-status.
Description
The cifs$chown service subprogram changes the user ID and group ID of a file, where:
path
owner
group
is a nul-terminated character string that contains the path name of the file.
is a 1-word ( S1(36) BINARY-1 ) data item that contains the new user ID for the file.
If owner = -1, the user ID is unchanged.
is a 1-word ( S1(36) BINARY-1 ) data item that contains the new group ID for the file.
If group = -1, the group ID is unchanged. If both owner = -1 and group = -1, both the
user ID and group ID are unchanged; therefore, cifs$chown changes neither the time
of last access field nor the file mode.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$chown service subprogram completes successfully, it does the following:
• Updates the time of last access field of the file
• Returns 0 in cifs-status
Otherwise, cifs$chown sets cifs-status to identify the specific error that was
encountered.
6–12 7859 6137–009

Error Codes
CIFS$CHOWN
If any of the following conditions occurs, the cifs$chown service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EACCES The calling process is denied search permission to a
directory in the path name.
CIFS-EFAULT The value specified by path is invalid.
CIFS-EINVAL owner or group is a value that can never possibly be a valid
user ID or group ID.
CIFS-
ENAMETOOLONG
A path name component is longer than 4095 characters.
CIFS-ENOENT Either of the following errors occurred:
• The file does not exist.
• path contains an empty string.
CIFS-ENOTDIR A component of the path name is not a directory.
CIFS-EPERM Both of the following conditions exist:
• The effective user ID does not match the owner of the
file or directory.
• The process is not privileged.
7859 6137–009 6–13

CIFS$CLEARERR
CIFS$CLEARERR
Application
Use the cifs$clearerr service subprogram to clear the end-of-file and error indicators for
the stream.
Synopsis
CALL "cifs$clearerr" USING cifs-file.
Description
The cifs$clearerr service subprogram clears the end-of-file and error indicators for a
stream, where:
cifs-file
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
The end-of-file and error indicators are cleared only at the following times:
• When the file is opened
• By an explicit call to one of the following service subprograms:
− cifs$clearerr
− cifs$fseek
− cifs$rewind
Return Values
The cifs$clearerr service subprogram returns no value.
6–14 7859 6137–009

CIFS$CLOSE
Application
CIFS$CLOSE
Use the cifs$close service subprogram to release certain file attributes and prevent
further access to a file through a specific file descriptor. Closing a file does the following:
• Deallocates the specified file descriptor and makes it available for reuse by
subsequent calls to other service subprograms, such as cifs$open and cifs$dup.
Reusing file descriptors is important for redirecting the standard files (standard input,
standard output, and standard error) to a pipe, for example.
• Removes all record locks the calling process holds on the file. You might want to
close a file to clear all locks you set on it, and then open the file again to access a
different segment. This reduces lock conflicts for cooperating processes trying to
access the same file.
Synopsis
CALL "cifs$close" USING fildes, cifs-status.
Description
The cifs$close service subprogram removes access to an open file description through a
certain file descriptor, where fildes identifies the file descriptor. That is, the calling
process can no longer use that file descriptor for input and output operations to the
original file.
fildes
is a 1-word (S1(36) BINARY-1) data item which contains the file description of the file
to be closed.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Additional Processing for the Last File Descriptor
When fildes identifies the last file descriptor for the following file types, cifs$close does
the additional processing specified:
• Pipe or FIFO file
cifs$close discards any data remaining in the pipe or FIFO file.
• Open file description
cifs$close discards the open file description.
• File whose link count is 0
cifs$close deletes the file and frees its space.
7859 6137–009 6–15

CIFS$CLOSE
Return Values
If the cifs$close service subprogram completes successfully, it returns 0 in cifs-status.
Otherwise, cifs$close sets cifs-status to identify the specific error that was encountered.
Error Codes
If any of the following conditions occurs, the cifs$close service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EBADF fildes is not a valid file descriptor.
CIFS-EIO I/O error occurred while writing the file.
6–16 7859 6137–009

CIFS$CLOSEDIR
Application
CIFS$CLOSEDIR
Use the cifs$closedir service subprogram to close an open directory stream and make it
inaccessible to the calling process. If no other processes share this directory stream,
access to the stream is closed.
If a process terminates, all effects of cifs$closedir occur for each directory stream open
to the process.
See cifs$opendir for opening directory, cifs$readdir for reading the next directory entry,
and cifs$rewinddir for repositioning the stream at its beginning.
Synopsis
CALL "cifs$closedir" USING cifs-dir, cifs-status.
Description
The cifs$closedir service subprogram closes access to the directory stream by the calling
process, where cifs-dir designates the directory stream to close. The directory stream
must have been opened previously by the cifs$opendir service subprogram.
cifs-dir
is a 2-word (S1(72) BINARY-1) data item containing the directory stream to close.
Use the COBOL COPY PROC CIFS-DIR for the declaration of this variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$closedir service subprogram completes successfully, it does the following:
• Updates the time of last access field for the directory
• Returns 0 in cifs-status
Otherwise, cifs$closedir sets cifs-status to identify the specific error that was
encountered.
Error Codes
If any of the following conditions occurs, the cifs$closedir service subprogram returns a
nonzero value in the cifs-status parameter.
7859 6137–009 6–17

CIFS$CLOSEDIR
The following COBOL level 88 condition names (defined in the COBOL COPY PROC
CIFS-API) can be checked in order to determine the error that was returned:
CIFS-EBADF cifs-dir is not a valid directory stream.
CIFS-EFAULT cifs-dir is not a valid value.
6–18 7859 6137–009

CIFS$CREAT
Application
CIFS$CREAT
Use the cifs$creat service subprogram to create and open a new regular file, specifying
how you can access it and setting its file permissions.
Synopsis
CALL "cifs$creat" USING path, cifs-mode, new-fd, cifs-status.
Description
The cifs$creat service subprogram call is the same as a special case of cifs$open, as
follows:
CALL "cifs$open" USING path, cifs-oflag, cifs-mode, new-fd, cifs-status.
Where cifs-oflag has the fields CIFS-OFLAG-WRONLY, CIFS-OFLAG-CREAT and CIFS-
OFLAG-TRUNC set.
See the cifs$open service subprogram for details of the path, cifs-oflag and cifs-mode
arguments.
path
is an alphanumeric variable that contains the name of the file to be opened.
cifs-mode
new-fd
is a 1-word (1(36) BINARY-1) data item that sets the file permissions when a new file
is created. Use the COBOL COPY PROC CIFS-MODE for the declaration of this
variable. See “The cifs-mode Argument” and the CIFS-OFLAG-CREAT file status in
the description of cifs$open for the valid values for cifs-mode.
is a 1-word (S1(36) BINARY-1) data item into which the file description of the newly
created file is placed.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Caution
Using cifs$creat when a file of the same name exists truncates the file's
length to 0.
7859 6137–009 6–19

CIFS$CREAT
Return Values
If the cifs$creat service subprogram completes successfully, it returns the file descriptor
for the new file into the new-fd parameter. Otherwise, cifs$creat sets cifs-status to
identify the specific error that was encountered
Error Codes
If any of the following conditions occurs, the cifs$creat service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-E1100FILE The system could not assign the OS 2200 file that contains the
file's data space.
CIFS-EACCES Either of the following errors occurred:
• The calling process is denied search permission on a
directory in the path name.
• The calling process is denied write permission for the file
or the parent directory of the file.
CIFS-EAGAIN An attempt to create and open an imported file failed because
the corresponding OS 2200 file existed but was rolled out or
otherwise unavailable. This is a temporary condition; a
subsequent attempt might succeed.
CIFS-EFAULT The name specified by path is invalid.
CIFS-EINTR The create operation was interrupted by a signal.
CIFS-EINVAL cifs-mode has undefined bits set.
CIFS-EIO An input/output error prevented completion of the request.
CIFS-EISDIR The path name resolves to a directory.
CIFS-EMFILE The calling process cannot create the file because the limit on
the maximum number of open file descriptors for a process
would be exceeded.
CIFS-ENOENT Either of the following errors occurred:
• A directory in the path name does not exist.
• path specifies an empty string.
CIFS-ENOSPC The directory or file system that is to contain the new file is out
of available space.
CIFS-ENOTDIR A component of the path name prefix is not a directory.
6–20 7859 6137–009

CIFS$DUP
Application
CIFS$DUP
Use the cifs$dup service subprogram to create an additional file descriptor for an existing
open file description. This capability is important for redirecting standard files to a pipe,
for example. The new file descriptor has the following properties:
• Its value is the lowest number available for the process.
• It shares the same open file description and file locks with the original file descriptor.
You can also duplicate a file descriptor by setting the 88 level condition name
CIFS-F-DUPFD to TRUE in the cifs$fcntl service subprogram. See the cifs$dup2 service
subprogram for associating a specific file descriptor with an open file description.
Synopsis
CALL "cifs$dup" USING old-fildes, new-fildes, cifs-status.
Description
The cifs$dup service subprogram duplicates the file descriptor designated by old-fildes.
The duplicated file descriptor occurs in the first available file descriptor location.
old-fildes
is a 1-word (S1(36) BINARY-1) data item which contains the file description of the file
to be duplicated.
new-fildes
is a 1-word (S1(36) BINARY-1) data item which contains the file description of the
newly created file descriptor.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
7859 6137–009 6–21

CIFS$DUP
Diagram
The following diagram shows a duplicated file descriptor for an open file description:
Return Values
If the cifs$dup service subprogram completes successfully, it returns the index of the
newly created file descriptor into the new-fildes parameter and it returns 0 in cifs-status.
Otherwise, cifs$dup sets cifs-status to identify the specific error that was encountered.
Error Codes
If any of the following conditions occurs, the cifs$dup service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EBADF old-fildes is not a valid open file descriptor.
CIFS-EMFILE The calling process exceeds the maximum number of file
descriptors allowed.
6–22 7859 6137–009

CIFS$DUP2
Application
CIFS$DUP2
Use the cifs$dup2 service subprogram to associate a specific file descriptor index with
an existing open file description. The new file descriptor shares the same open file
description and file locks with the original file descriptor. See cifs$dup for creating an
additional file descriptor for the open file description.
Synopsis
CALL "cifs$dup2" USING fildes1, fildes2, cifs-status.
Description
The cifs$dup2 service subprogram causes the file descriptor fildes2 to identify the same
open file description as fildes1.
If fildes2 exists and corresponds to an open file other than fildes1, cifs$dup2 first closes
fildes2 (which can remove locks and the file itself; see the cifs$close service
subprogram). If fildes1 and fildes2 are equal, cifs$dup2 does not duplicate or close any
file descriptors.
fildes1
fildes2
is a 1-word (S1(36) BINARY-1) data item which contains a file descriptor.
is a 1-word (S1(36) BINARY-1) data item which contains a file descriptor.
cifs-status
is a 1-word ( 1(36) BINARY-1) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
7859 6137–009 6–23

CIFS$DUP2
Diagram
The following diagram shows a specific file descriptor associated with an open file
description:
Return Values
If the cifs$dup2 service subprogram completes successfully, it returns the value of
fildes2, a file descriptor, and it returns 0 in cifs-status. Otherwise, cifs$dup sets
cifs-status to identify the specific error that was encountered.
Error Codes
If any of the following conditions occurs, the cifs$dup2 service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EBADF One of the following errors occurred:
• fildes1 is not a file descriptor.
• fildes2 is either negative or greater than the maximum number
of file descriptors allowed.
6–24 7859 6137–009

CIFS$FCLOSE
Application
CIFS$FCLOSE
Use the cifs$fclose service subprogram to write all remaining data in the buffer to a file
and close the file.
Synopsis
CALL "cifs$fclose" USING cifs-file, cifs-status.
Description
The cifs$fclose service subprogram flushes any output buffer for a stream and closes
the associated file, where:
cifs-file
is an opaque data item that describes an open instance of a file. It is a 2-word (S1(72)
BINARY-1) data item in which the value of the open instance of the file is stored.
Use the COBOL COPY PROC CIFS-FILE for the declaration of this variable.
cifs-status
is a 1-word ( 1(36) BINARY-1) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$fclose service subprogram successfully closes the stream, it returns 0 in the
cifs-status argument. Otherwise, if it detects errors or if the stream was already closed,
cifs$fclose returns a nonzero value in the cifs-status argument.
7859 6137–009 6–25

CIFS$FCNTL
CIFS$FCNTL
Application
Use the cifs$fcntl service subprogram to manage an open file in the following ways,
which are described in following subsections:
• Duplicate a file descriptor; see “File Descriptor Services.”
• Retrieve information about or change the values of the file status flags and access
specification; see “File Status Flags and Access Specification Services.”
• Manage advisory record locking services; see “Record Locking Services.”
Synopsis
CALL "cifs$fcntl USING fildes, cifs-fcntl-cmd, parm, return-value, cifsstatus.
Description
The cifs$fcntl service subprogram performs file services, where:
fildes
is a 1-word (S1(36) BINARY-1) data item which contains the file description of an
open file.
cifs-fcntl-cmd
is a 1-word (1(36) BINARY-1) data item which indicates which service to perform.
Use the COBOL COPY PROC CIFS-FCNTL for the declaration of this variable. The
cifs-fcntl-cmd field can be set to any of the COBOL level 88 names that are
associated with it.
It can have any value in the following table.
Service
Duplicate file
descriptor
Get flags and
information
Set flags and
information
*Wait if blocked
File Descriptor
File Status and
Access
Specification
CIFS-F-DUPFD – –
– CIFS-F-GETFL
CIFS-F-GETFD
– CIFS-F-SETFL
CIFS-F-SETFD
Advisory Record
Locking
CIFS-F-GETLK
CIFS-F-SETLK,
CIFS-F-SETLKW*
See the following subsections for detailed information about each type of service.
6–26 7859 6137–009

parm
CIFS$FCNTL
is an argument of varying type whose value depends on cifs-fcntl-cmd, as shown in
the following table (see the following descriptions of the symbolic names for more
information about parm):
If cifs-fcntl-cmd is ... Then parm is ...
CIFS-F-DUPFD An integer giving the smallest desired value for the new file
descriptor
CIFS-F-GETFD,
CIFS-F-GETFL
CIFS-F-SETFD,
CIFS-F-SETFL
CIFS-F-GETLK, CIFS-F-
SETLK, CIFS-F-SETLKW
return-value
Not required; it is ignored
An integer giving the new setting for the status flags for the
specified file descriptor
The cifs-flock-struct group item that describes the locking
request (can be used to unlock or change an existing lock)
is a 1-word ( 1(36) BINARY-1 ) data item that contains the return status.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Caution
cifs$fcntl cannot determine if the third argument has the wrong type. Even if
the type is incorrect, cifs$fcntl interprets the storage as the correct type,
resulting in undefined and unpredictable behavior.
Return Values
If the cifs$fcntl service subprogram completes successfully, its return value in the
argument return-value depends on cifs-fcntl-cmd, as follows:
If cifs-fcntl-cmd is ... Then cifs$fcntl returns in return-value ...
CIFS-F-DUPFD A new file descriptor
CIFS-F-GETFD,
CIFS-F-GETFL
Any other value 0
The values of the file status flags and file access
specifications
If the cifs$fcntl service subprogram completes successfully it returns 0 in cifs-status.
Otherwise, cifs$fcntl sets cifs-status to identify the specific error that was encountered.
7859 6137–009 6–27

CIFS$FCNTL
Error Codes
If any of the following conditions occurs, the cifs$fcntl service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EAGAIN cifs-fcntl-cmd is CIFS-F-SETLK and one of the following is true:
• L-TYPE is CIFS-F-WRLCK and another process owns a lock on
some portion of the segment to be locked.
• L-TYPE is CIFS-F-RDLCK and another process owns an
exclusive lock on some portion of the segment to be locked.
CIFS-EBADF Any of the following errors occurred:
CIFS-EDEADL
K
• fildes is not a valid file descriptor.
• The following conditions are all true:
− cifs-fcntl-cmd is CIFS-F-SETLK or CIFS-F-SETLKW.
− L-TYPE is CIFS-F-RDLCK.
− fildes is not a file descriptor open for reading.
• The following conditions are all true:
− cifs-fcntl-cmd is CIFS-F-SETLK or CIFS-F-SETLKW.
− L-TYPE is CIFS-F-WRLCK.
− fildes is not a file descriptor open for writing.
Both of the following conditions occurred:
• cifs-fcntl-cmd is CIFS-F-SETLKW.
• Suspending the process because of a conflict with the
request would cause a deadlock.
CIFS-EFAULT Both of the following conditions occurred:
• cifs-fcntl-cmd is CIFS-F-GETLK, CIFS-F-SETLK, or CIFS-F-
SETLKW.
• parm is not a valid value.
CIFS-EINTR Both of the following conditions occurred:
• cifs-fcntl-cmd is CIFS-F-SETLKW.
• The process received a signal before the locking request was
granted.
6–28 7859 6137–009

CIFS-EINVAL Any of the following errors occurred:
• cifs-fcntl-cmd is not one of the valid values listed.
CIFS$FCNTL
• cifs-fcntl-cmd is CIFS-F-DUPFD and parm is less than 0 or
greater than or equal to the maximum number of open files.
• cifs-fcntl-cmd is CIFS-F-GETLK, CIFS-F-SETLK, or CIFS-F-
SETLKW, and the cifs-flock-struct data item to which parm
points is invalid.
• cifs-fcntl-cmd is CIFS-F-SETFD, and the value of parm is not 0.
• cifs-fcntl-cmd is CIFS-F-DUPFD, CIFS-F-SETFL, CIFS-F-GETLK,
CIFS-F-SETLK, or CIFS-F-SETLKW and parm is not specified.
• cifs-fcntl-cmd is CIFS-F-SETFL, and the value of parm has
undefined bits set.
CIFS-EMFILE Both of the following conditions occurred:
• cifs-fcntl-cmd is CIFS-F-DUPFD.
• No file descriptors greater than or equal to parm are available.
CIFS-ENOLCK Both of the following conditions occurred:
The cifs-flock-struct data item
• cifs-fcntl-cmd is either CIFS-F-SETLK or CIFS-F-SETLKW.
• Satisfying the lock or unlock request results in the number of
locked regions for the process exceeding the maximum
number of locks allowed for a process.
The cifs-flock-struct data item provides information to the kernel about the locking
request. It also gives the process information about existing locks. The following table
describes the cifs-flock-struct data item, which is defined in the COBOL COPY PROC
CIFS-FCNTL:
Member
Name Description Values
l-len Number of
consecutive bytes to
be locked or unlocked
l-pid Process ID of process
owning a conflicting
lock
If positive, l-len bytes; if 0, to the end of the file
(cannot be negative)
Returned by CIFS-F-GETLK
7859 6137–009 6–29

CIFS$FCNTL
Member
Name Description Values
l-start Distance to the first
byte in the lock from
the address specified
by l-whence
l-type Request type, one of
• Exclusive lock
• Shared lock
• Unlock
l-whence File address at which
to add l-start to find
the first byte in the
lock; either
Illustration
• Current position
• End of file
• Beginning of
file
Any integer (positive, negative, or 0)
Notes:
• The result of applying –l-start to
l-whence must be ≥ 0. That is, the
starting position of the lock cannot be
before the beginning of the file.
• If an CIFS-F-GETLK request finds a
conflicting lock, the value of l-start
identifies the first byte of the
conflicting lock relative to the
beginning of the file.
CIFS-F-WRLCK, CIFS-F-RDLCK, CIFS-F-UNLCK
Note: If an CIFS-F-GETLK request does not
find a conflicting lock, the kernel changes the
value of l-type to CIFS-F-UNLCK.
CIFS-SEEK-CUR-WHENCE, CIFS-SEEK-END-
WHENCE, CIFS-SEEK-SET-WHENCE
Note: If an CIFS-F-GETLK request finds a
conflicting lock, the value of l-whence is CIFS-
SEEK-SET-WHENCE.
Values in the flock structure determine how and where a lock is created on a file. Given
specific values for the starting offset position (l-start) and length (l-len) of a desired lock,
the value of l-whence determines whether the lock occurs at the beginning, current
position, or end of a file, as shown in the following diagram:
6–30 7859 6137–009

Locking and Unlocking Whole Files
CIFS$FCNTL
A process can lock or unlock an entire file if it sets a lock of zero length and zero offset
that starts at the beginning of the file, as shown by the following values:
• l-len = 0
• l-start = 0
• l-whence = CIFS-SEEK-SET-WHENCE
Replacing and Merging Locks
A successful CIFS-F-SETLK or CIFS-F-SETLKW request replaces the previous lock type
for each byte in the specified region with the new lock type. Before returning, cifs$fcntl
merges adjacent locks of the same type that are owned by the requesting process.
For example, suppose a process owns shared locks on bytes 0 through 5 and bytes 7
through 9 in a file. The process requests a shared lock on byte 6 (or on a range including
byte 6). The result is a single shared lock on bytes 0 through 9.
File Descriptor Services
The symbolic names in this subsection are the values for cifs-fcntl-cmd that allow
cifs$fcntl to duplicate a file descriptor (CIFS-F-DUPFD).
CIFS-F-DUPFD —Duplicate File Descriptor
This service requires an integer type for parm. The cifs$fcntl service subprogram creates
and returns a new file descriptor with the following characteristics:
• It is greater than or equal to parm.
• It refers to the same open file description as fildes.
7859 6137–009 6–31

CIFS$FCNTL
File Descriptor Closure Mode Services
The CIFS-F-GETFD and CIFS-F-SETFD flags can be used to set up multiactivity programs,
but are currently not supported for COBOL.
File Status Flags and Access Specification Services
The symbolic names in this subsection are the values for cifs-fcntl-cmd that allow
cifs$fcntl to
• Retrieve the file status flags and file access specification (CIFS-F-GETFL)
• Set the file status flags (CIFS-F-SETFL)
File status flags and the file access specification are associated with an open file
description. They do not indicate anything about other open file descriptions that
reference the same file.
CIFS-F-GETFL —Get File Status Flags and Access Specification
The cifs$fcntl service subprogram returns the following values associated with fildes
(see the cifs$open service subprogram for descriptions of its symbolic names):
File Attribute Value Description
File status flags CIFS-OFLAG-APPEND
CIFS-OFLAG-DSYNC
File access
specification
CIFS-OFLAG-NONBLOCK
CIFS-OFLAG-SYNC
CIFS-OFLAG-RDONLY
CIFS-OFLAG-WRONLY
parm is not required for this service and is ignored.
CIFS-F-SETFL —Set File Status Flags
Append mode
Synchronize file data on read and
write operations
No delay
Synchronize file data and access
times on read and write operations
Open for reading
Open for writing
This service requires an integer type for parm containing the new settings for the file
status flags in the open file description associated with fildes. For this service, cifs$fcntl
ignores other bits in parm.
If the result of an AND operation between parm and a file status constant is zero,
cifs$fcntl clears the corresponding file status flag in the open file description; otherwise,
cifs$fcntl sets the flag. In other words, you must set the flag in parm if you want it set in
the open file description; if the flag is not set in parm, it is cleared in the open file
description. The following constants set the corresponding file status flag:
• CIFS-OFLAG-APPEND
• CIFS-OFLAG-DSYNC
• CIFS-OFLAG-NONBLOCK
• CIFS-OFLAG-SYNC
6–32 7859 6137–009

CIFS$FCNTL
If both the CIFS-OFLAG-DSYNC and CIFS-OFLAG-SYNC flags are set (see the cifs$open
service subprogram), the effect is the same as if only CIFS-OFLAG-SYNC is set.
Calling cifs$fcntl with CIFS-F-GETFD
The following code shows how to call cifs$fcntl to get the file status flags and file mode,
where fd-a is an existing file descriptor:
COPY CIFS-API.
COPY CIFS-OFLAG.
01 return-value PIC s1(36) BINARY-1.
01 CIFS-FCNTL-CMD PIC 1(36) BINARY-1.
88 CIFS-F-DUPFD VALUE 0.
88 CIFS-F-GETFD VALUE 1.
88 CIFS-F-GETFL VALUE 2.
88 CIFS-F-GETLK VALUE 3.
88 CIFS-F-SETFD VALUE 4.
88 CIFS-F-SETFL VALUE 5.
88 CIFS-F-SETLK VALUE 6.
88 CIFS-F-SETLKW VALUE 7.
...
set cifs-f-getfl to true.
CALL "cifs$fcntl" USING fd-a, cifs-fcntl-cmd, 0,
return-value, cifs-status.
Interpreting the Results of Calling cifs$fcntl with CIFS-F-GETFL
To extract the file access specification and file status flags from the result of
CIFS-F-GETFL, do the following:
01 CIFS-OFLAG PIC 1(36) BINARY-1.
01 CIFS-OFLAG-BITS REDEFINES CIFS-OFLAG.
03 FILLER PIC 1(26) BINARY-1.
03 CIFS-OFLAG-SYNC PIC 1 BINARY-1.
03 CIFS-OFLAG-DSYNC PIC 1 BINARY-1.
03 FILLER PIC 1 BINARY-1.
03 CIFS-OFLAG-EXCL PIC 1 BINARY-1.
03 CIFS-OFLAG-TRUNC PIC 1 BINARY-1.
03 CIFS-OFLAG-CREAT PIC 1 BINARY-1.
03 CIFS-OFLAG-APPEND PIC 1 BINARY-1.
03 CIFS-OFLAG-NONBLOCK PIC 1 BINARY-1.
03 CIFS-OFLAG-WRONLY PIC 1 BINARY-1.
03 CIFS-OFLAG-RDONLY PIC 1 BINARY-1.
...
move return-value to cifs-oflag.
At this point the user can check any of the file access specifications or file status fields
by looking at the desired field in the CIFS-OFLAG-BITS data item.
7859 6137–009 6–33

CIFS$FCNTL
To determine if the file is open for reading from the result of CIFS-F-GETFL, check the
CIFS-OFLAG-RDONLY:
if cifs-oflag-rdonly = 1
then
* Code for readable file *
...
To determine if the file is open for appending data from the result of CIFS-F-GETFL,
check the CIFS-OFLAG-APPEND:
if cifs-oflag-append = 1
then
* Code for appending data *
...
Calling cifs$fcntl with CIFS-F-SETFL
The following code shows how to call cifs$fcntl to set the CIFS-OFLAG-APPEND, CIFS-
OFLAG-NONBLOCK, and CIFS-OFLAG-SYNC file status flags and clear the CIFS-OFLAG-
DSYNC flag, where fd-a is an existing file descriptor:
COPY CIFS-API.
COPY CIFS-OFLAG.
01 return-value PIC s1(36) BINARY-1.
01 CIFS-FNCTL-CMD PIC 1(36) BINARY-1.
88 CIFS-F-DUPFD VALUE 0.
88 CIFS-F-GETFD VALUE 1.
88 CIFS-F-GETFL VALUE 2.
88 CIFS-F-GETLK VALUE 3.
88 CIFS-F-SETFD VALUE 4.
88 CIFS-F-SETFL VALUE 5.
88 CIFS-F-SETLK VALUE 6.
88 CIFS-F-SETLKW VALUE 7.
...
move 1 to CIFS-OFLAG-APPEND.
move 1 to CIFS-OFLAG-NONBLOCK.
move 1 to CIFS-OFLAG-SYNC.
set cifs-f-setfl to true.
CALL "cifs$fcntl" USING fd-a, cifs-fcntl-cmd, cifs-oflag,
return-value, cifs-status.
6–34 7859 6137–009

Record Locking Services
CIFS$FCNTL
The symbolic names in this subsection are the values for cifs-fcntl-cmd that allow
cifs$fcntl to retrieve (CIFS-F-GETLK) or set (CIFS-F-SETLK and CIFS-F-SETLKW) advisory
record locks on any file or directory. They require parm to point to a flock data item
(CIFS-FLOCK-STRUCT).
CIFS-F-GETLK—Get Record-Locking Information
The cifs$fcntl service subprogram searches for a lock owned by another process that
conflicts with the lock description (shared or exclusive) in the flock data item indicated by
parm. That is, the type and location of an existing lock would prevent the requested lock
from being created. The behavior of cifs$fcntl depends on whether a conflicting lock
exists, as follows:
• A conflicting lock exists; cifs$fcntl does the following:
− Overwrites the flock data item with the information retrieved about the
conflicting lock
− Sets l-start to the first byte of the conflicting lock, relative to the beginning of the
file
− Sets l-whence to CIFS-SEEK-SET-WHENCE
• No conflicting lock exists; cifs$fcntl does the following:
− Sets l-type to CIFS-F-UNLCK
− Leaves the rest of the flock data item unchanged
If parm points to a data item whose l-type field is CIFS-F-UNLCK, it is not possible for a
lock conflict to arise. Therefore, cifs$fcntl behaves the same as the second case.
Conclusions About Using CIFS-F-GETLK
You can draw the following conclusions about using CIFS-F-GETLK:
• If you request an exclusive or shared lock and cifs$fcntl returns a data item whose
l-type field is CIFS-F-UNLCK, then no conflicting lock existed at the time of the call.
However, this does not guarantee that no conflicting lock exists if you try to set the
same lock using CIFS-F-SETLK, because another process can establish a conflicting
lock in the interim.
• An appropriate use for CIFS-F-GETLK is to determine more information about a lock
that conflicts with your request to set a lock with CIFS-F-SETLK. In particular, the
process ID of the owner of the conflicting lock might be useful, depending on the
application.
• If your request has lock type CIFS-F-UNLCK, using CIFS-F-GETLK is meaningless.
7859 6137–009 6–35

CIFS$FCNTL
CIFS-F-SETLK—Set Record-Locking Information
The cifs$fcntl service subprogram sets or clears a lock on a file segment according to the
description in the flock data item indicated by parm, as shown in the following table (the
symbolic names are defined in CIFS-FCNTL COPY PROC):
If l-type is ... Then cifs$fcntl uses l-whence, l-start, and l-len to ...
CIFS-F-RDLCK Establish a shared lock.
CIFS-F-WRLCK Establish an exclusive lock.
CIFS-F-UNLCK Remove any locks in the indicated range.
If cifs$fcntl cannot set the requested lock because of conflicts with existing locks, it fails.
CIFS-F-SETLKW—Set Record-Locking Information; Wait If Blocked
This service is the same as CIFS-F-SETLK, except that the process waits until the
request can be satisfied or is interrupted. If the process is interrupted while waiting for a
region to be unlocked, cifs$fcntl fails and the lock is not created.
6–36 7859 6137–009

Calling cifs$fcntl with CIFS-F-SETLK
CIFS$FCNTL
The following code shows how to call cifs$fcntl to set an exclusive lock at the current
read/write position in the file, where fd-a is an existing file descriptor:
01 CIFS-FLOCK-STRUCT.
03 L-TYPE PIC S1(18) BINARY-1.
88 CIFS-F-RDLCK VALUE 1.
88 CIFS-F-UNLCK VALUE 2.
88 CIFS-F-WRLCK VALUE 3.
03 L-WHENCE PIC S1(18) BINARY-1.
88 CIFS-SEEK-SET-WHENCE VALUE 0.
88 CIFS-SEEK-CUR-WHENCE VALUE 1.
88 CIFS-SEEK-END-WHENCE VALUE 2.
03 L-START PIC S1(36) BINARY-1.
03 L-LEN PIC S1(36) BINARY-1.
03 L-PID PIC S1(36) BINARY-1.
*
01 CIFS-FCNTL-CMD PIC 1(36) BINARY-1.
88 CIFS-F-DUPFD VALUE 0.
88 CIFS-F-GETFD VALUE 1.
88 CIFS-F-GETFL VALUE 2.
88 CIFS-F-GETLK VALUE 3.
88 CIFS-F-SETFD VALUE 4.
88 CIFS-F-SETFL VALUE 5.
88 CIFS-F-SETLK VALUE 6.
88 CIFS-F-SETLKW VALUE 7.
...
move 12 to 1-len.
move 0 to 1-start.
set cifs-f-wrlck to true.
set cifs-seek-cur-whence to true.
set cifs-f-setlk to true.
call "cifs$fcntl" using fd-a, cifs-fcntl-cmd, cifs-flock-struct,
return-value, cifs-status.
Modifying Existing Locks
If the calling process already has locks covering part of the segment indicated by the lock
description, cifs$fcntl modifies these locks as necessary. For example, if the process
owns an exclusive lock on the first 10 bytes of the file and requests a shared lock on
byte 5 (l-start = 5), it then owns 3 distinct locks, as follows:
• An exclusive lock on bytes 0 through 4
• A shared lock on byte 5
• An exclusive lock on bytes 6 through 9
7859 6137–009 6–37

CIFS$FCNTL
Clearing Existing Locks
You can clear all 3 locks in the previous example by unlocking the first 10 bytes of the
file, as follows:
COPY CIFS-API.
COPY CIFS-OFLAG.
01 return-value PIC S1(36) BINARY-1.
01 CIFS-FLOCK-STRUCT.
03 L-TYPE PIC S1(18) BINARY-1.
88 CIFS-F-RDLCK VALUE 1.
88 CIFS-F-UNLCK VALUE 2.
88 CIFS-F-WRLCK VALUE 3.
03 L-WHENCE PIC S1(18) BINARY-1.
88 CIFS-SEEK-SET-WHENCE VALUE 0.
88 CIFS-SEEK-CUR-WHENCE VALUE 1.
88 CIFS-SEEK-END-WHENCE VALUE 2.
03 L-START PIC S1(36) BINARY-1.
03 L-LEN PIC S1(36) BINARY-1.
03 L-PID PIC S1(36) BINARY-1.
*
01 CIFS-FCNTL-CMD PIC 1(36) BINARY-1.
88 CIFS-F-DUPFD VALUE 0.
88 CIFS-F-GETFD VALUE 1.
88 CIFS-F-GETFL VALUE 2.
88 CIFS-F-GETLK VALUE 3.
88 CIFS-F-SETFD VALUE 4.
88 CIFS-F-SETFL VALUE 5.
88 CIFS-F-SETLK VALUE 6.
88 CIFS-F-SETLKW VALUE 7.
...
move 10 to 1-len.
move 0 to 1-start.
set cifs-f-unlck to true.
set cifs-seek-set-whence to true.
set cifs-f-setlk to true.
call "cifs$fcntl" using fd-a, cifs-fcntl-cmd, cifs-flock-struct,
return-value, cifs-status.
6–38 7859 6137–009

CIFS$FDATASYNC
Application
CIFS$FDATASYNC
Use the cifs$fdatasync service subprogram to write to the device all data currently in a
portion of the buffer cache for a file, thus protecting the data against loss due to a
system outage. With cifs$fdatasync, an application can synchronize all file updates at
one time, instead of on every read or write operation. However, cifs$fdatasync does not
synchronize file access times.
For a similar service subprogram that does synchronize file access times, see the
cifs$fsync service subprogram. For alternate methods of synchronizing disk data, see the
discussions of the CIFS-OFLAG-SYNC and CIFS-OFLAG-DSYNC flags under the
cifs$open and cifs$fcntl service subprograms.
Synopsis
CALL "cifs$fdatasync" USING fildes, cifs-status
Description
The cifs$fdatasync service subprogram writes from the buffer cache to the device all
data belonging to the specified file, where fildes specifies a regular file open for writing.
The data written is that portion of the buffer cache associated with the file referenced by
fildes.
fildes
is a 1-word (S1(36) BINARY-1) data item which contains a file descriptor.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$fdatasync service subprogram completes successfully, it returns 0 in the
cifs-status parameter. Otherwise, cifs$fdatasync sets cifs-status to identify the specific
error that was encountered.
7859 6137–009 6–39

CIFS$FDATASYNC
Error Codes
If any of the following conditions occurs, the cifs$fdatasync service subprogram returns
a nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EBADF fildes is not a valid file descriptor open for writing.
CIFS-EINVAL Data synchronization is not supported for the type of
file described by fildes.
CIFS-EIO The file could not be fully synchronized because of an
I/O error.
6–40 7859 6137–009

CIFS$FDOPEN
Application
Use the cifs$fdopen service subprogram to create a stream and associate a file
descriptor with it.
Synopsis
CALL "cifs$fdopen" USING fildes, type, cifs-file, cifs-status.
Description
CIFS$FDOPEN
The cifs$fdopen service subprogram creates a stream and associates a file descriptor
with the stream, where:
fildes
type
cifs-file
is the file descriptor to associate with the stream.
is a character string specifying the access mode for the file. It is the same as the
type-string argument for the cifs$fopen service subprogram. It must be a subset of
the access mode of the initial cifs$open service subprogram.
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
The access mode prefixes “w” and “w+” do not cause truncation of the file. The file
position indicator is set to the position indicated by the file offset associated with the file
descriptor. Error and end-of-file indicators are cleared.
Return Values
If the cifs$fdopen service subprogram completes successfully, it does the following:
• Does not change the last access time field
• Returns a value to a stream in cifs-file
• Returns 0 in cifs-status
Otherwise, cifs$fdopen sets cifs-status to identify the specific error that was
encountered.
7859 6137–009 6–41

CIFS$FDOPEN
Error Codes
If any of the following conditions occurs, the cifs$fdopen service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EINVAL type is not a subset of the access mode of the initial
cifs$open service subprogram.
6–42 7859 6137–009

CIFS$FEOF
Application
Use the cifs$feof service subprogram to test whether a stream is at end of file.
Synopsis
CALL "cifs$feof" USING cifs-file, eof-flag.
Description
CIFS$FEOF
The cifs$feof service subprogram tests the end-of-file indicator for a stream, where:
cifs-file
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
eof-flag
is a 1-word (S1(36) BINARY-1) data item which is used as the end-of-file indicator.
Return Values
The cifs$feof service subprogram returns a nonzero value into eof-flag if the end-of-file
indicator is set.
7859 6137–009 6–43

CIFS$FERROR
CIFS$FERROR
Application
Use the cifs$ferror service subprogram to test whether a read/write error occurred.
Synopsis
CALL "cifs$ferror" USING cifs-file, error-flag.
Description
The cifs$ferror service subprogram tests the read/write error indicator for a stream,
where:
cifs-file
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
error-flag
is a 1-word (S1(36) BINARY-1) data item which is used as the read/write error
indicator.
Return Values
The cifs$ferror service subprogram returns a nonzero value into error-flag if the
read/write error indicator is set.
6–44 7859 6137–009

CIFS$FFLUSH
Application
CIFS$FFLUSH
Use the cifs$fflush service subprogram to write all remaining data in the buffer to a file
without closing the file.
Synopsis
CALL "cifs$fflush" USING cifs-file, cifs-status.
Description
The cifs$fflush service subprogram causes any unwritten data for an output stream to be
written to the file, where:
cifs-file
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
The cifs$fflush service subprogram returns a nonzero value in cifs-status if a write error
occurs.
7859 6137–009 6–45

CIFS$FGETC
CIFS$FGETC
Application
Use the cifs$fgetc service subprogram to obtain the next character from an input
stream.
Synopsis
CALL "cifs$fgetc" USING cifs-file, next-char, cifs-status.
Description
The cifs$fgetc service subprogram obtains the next character (if present) from an input
stream, where:
cifs-file
is an opaque data item that describes an open instance of a file. It is a 2-word (S1(72)
BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the declaration of
this variable.
next-char
is a 1-byte field that is used to hold the next character that is retrieved.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
The cifs$fgetc service subprogram retrieves the next character and advances the
associated file position indicator, if defined.
Return Values
If the cifs$fgetc service subprogram completes successfully, it returns the next
character from the specified input stream into the next-char parameter and returns 0 in
cifs-status. Otherwise, cifs$fgetc sets cifs-status to identify the specific error that was
encountered.
6–46 7859 6137–009

CIFS$FGETPOS
Application
CIFS$FGETPOS
Use the cifs$fgetpos service subprogram to obtain the current value of the file position
indicator.
Synopsis
CALL "call$fgetpos" USING cifs-file, cifs-fpos, cifs-status.
Description
The cifs$fgetpos service subprogram obtains the current value of the file position
indicator, where:
cifs-file
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
cifs-fpos
is a 2-word group item in which the value is returned. Use the COBOL COPY PROC
CIFS-FPOS for the declaration of this variable. The cifs$fsetpos service subprogram
can use this data item.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If it completes successfully, the cifs$fgetpos service subprogram returns 0 in cifs-status.
Otherwise, cifs$fgetpos sets cifs-status to identify the specific error that was
encountered.
7859 6137–009 6–47

CIFS$FGETS
CIFS$FGETS
Application
Use the cifs$fgets service subprogram to read the next characters from an input stream
into a string.
Synopsis
CALL "cifs$fgets" USING string, max-chars, cifs-file, cifs-status.
Description
The cifs$fgets service subprogram reads the next max-chars - 1 characters from an input
stream into a character string, where:
string
is an alphanumeric data item that contains the characters read. A nul character is
written immediately after the last character read into the data item.
max-chars
cifs-file
specifies one more than the number of characters to read. That is, cifs$fgets reads
at most max-chars - 1 characters.
is an opaque data item that describes an open instance of a file. It is a 2-word (S1(72)
BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the declaration of
this variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$fgets service subprogram returns successfully, the string parameter contains
the characters that were read and the cifs-status parameter is set to 0. Otherwise,
cifs$fgets sets cifs-status to identify the specific error that was encountered.
6–48 7859 6137–009

CIFS$FILENO
Application
CIFS$FILENO
Use the cifs$fileno service subprogram to retrieve a file descriptor for a specific data
stream.
Synopsis
CALL "cifs$fileno" USING cifs-file, fildes, cifs-status.
Description
The cifs$fileno service subprogram retrieves a file descriptor, where:
cifs-file
fildes
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
is a 1-word (S1(36) BINARY-1) data item which contains the file description of the
specified file.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$fileno service subprogram completes successfully, it returns a file descriptor
into the fildes parameter and sets cifs-status to 0. Otherwise, cifs$fileno sets cifs-status
to identify the specific error that was encountered.
Error Codes
If any of the following conditions occurs, the cifs$fileno service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EFAULT The value specified by stream is invalid.
CIFS-EINVAL The stream to which stream points is invalid.
7859 6137–009 6–49

CIFS$FOPEN
CIFS$FOPEN
Application
Use the cifs$fopen service subprogram to open a path name and associate a stream
with it.
Synopsis
CALL "cifs$fopen" USING pathname, type-string, cifs-file, cifs-status.
Description
The cifs$fopen service subprogram opens a path name and associates a stream with it,
where:
pathname
is an alphanumeric variable that contains the name of the file to be opened.
type-string
is an alphanumeric data item that contains any of the sequences in the following
table. Additional characters, separated from the given sequences by a comma, may
follow these, but cifs$fopen ignores them. The sequences may be in upper or lower
case, although upper case might not be portable to other platforms.
Sequence Description
r Open existing text file for reading.
w Create file for writing or truncate to 0 length.
a Append; open file or create for writing at end of file.
rb Open existing binary file for reading.
wb Create binary file for writing or truncate to 0 length.
ab Append; open binary file or create for writing at end of file.
r+ Open existing file for update (reading and writing).
w+ Create file for update or truncate to 0 length.
a+ Append; open file or create for update, writing at end of file.
r+b or rb+ Open existing binary file for update (reading and writing).
w+b or wb+ Create binary file for update or truncate to 0 length.
a+b or ab+ Append; open binary file or create for update, writing at end of
file.
Note: The letter b in the type sequence is effective only when a file is created. In all
other cases, the file retains its existing type (SDF or binary), and b, if present, is ignored.
6–50 7859 6137–009

cifs-file
CIFS$FOPEN
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Appending Data to a File
Opening a file with append mode (a, ab, a+, or a+b) forces all subsequent writes to the
file to the current end of file, regardless of previous calls to the cifs$fseek service
subprogram.
Updating a File
When you open a file for update, you can perform both input and output operations on
the associated stream. However, an output operation cannot be directly followed by an
input operation without an intervening call to cifs$fseek, cifs$rewind, or cifs$fflush.
Similarly, an input operation cannot be directly followed by an output operation without
an intervening call to cifs$fseek or cifs$rewind, unless the input operation encounters
the end of the file.
Default Permissions When Creating a File
If the cifs$fopen service subprogram creates a file, it assigns read and write permissions
to the owner, group, and other permission classes by default. The following file mode
specification for the cifs$open service subprogram is equivalent:
compute cifs-mode-irwxu = cifs-mode-iread + cifs-mode-iwrite.
compute cifs-mode-irwxg = cifs-mode-iread + cifs-mode-iwrite.
compute cifs-mode-irwxo = cifs-mode-iread + cifs-mode-iwrite.
Return Values
If it completes successfully, the cifs$fopen service subprogram returns an opaque data
item that describes an open instance of the file into cifs-file and it also returns 0 in
cifs-status. Otherwise, cifs$fopen sets cifs-status to identify the specific error that was
encountered.
7859 6137–009 6–51

CIFS$FPRINTF
CIFS$FPRINTF
Application
Use the cifs$fprintf service subprogram to write formatted output.
Synopsis
CALL "cifs$fprintf" USING chars-out, cifs-file, format, [item...].
Description
The cifs$fprintf service subprogram writes formatted output, where:
chars-out
cifs-file
format
item
is a 1-word ( S1(36) BINARY-1 ) data item that contains the number of bytes written
out.
is an opaque data item that describes an open instance of a file. It is a 2-word (S1(72)
BINARY-1) data item into which the value of the open instance of the file is stored.
Use the COBOL COPY PROC CIFS-FILE for the declaration of this variable. A
formatted output string can have a maximum of 32,767 characters.
is an alphanumeric data item that controls the output by specifying how subsequent
arguments are converted before being output. See the subsection “Format Strings”
for additional information.
is an alphanumeric data item that contains the data to be printed.
Format Strings
A format string contains two types of objects:
• Plain characters
Plain characters are copied unchanged to the output stream.
• Conversion specifications
Each conversion specification results in fetching 0 or more subsequent arguments.
If the format is exhausted while arguments remain, the excess arguments are evaluated
but otherwise ignored. The cifs$fprintf service subprogram returns when it encounters
the end of the format string.
6–52 7859 6137–009

Conversion Specifications
CIFS$FPRINTF
Each conversion specification is introduced by the percent (%) character. After the %
character, the following characters appear in sequence:
1. An optional field, integer$, where integer is a decimal integer value specifying the
next argument to be converted for output.
2. Zero or more flags that modify the meaning of the conversion specification.
3. An optional decimal integer, other than 0, specifying a minimum field width. If the
converted value has fewer characters than the field width, it is padded with spaces
on the left of the field width (or on the right if the left adjustment flag is specified).
Note: If the first character after the percent (%) sign is 0, then it is a flag character,
not a field width.
4. An optional precision, in the form of a period (.) followed by an optional decimal
integer. If the integer is omitted, it is treated as 0. The padding specified by the
precision overrides the padding specified by the field width. The precision specifies
the following number:
a. For d, i, o, u, x, and X conversions, the minimum number of digits to appear
b. For e, E, and f conversions, the number of digits to appear after the decimal
point
c. For g and G conversions, the maximum number of significant digits
d. For s conversions, the maximum number of characters to be printed from a
string
5. An optional h, l, L, or ll (lowercase double L) format character, which must appear as
follows:
a. h
b. l
c. L
This letter specifies that a following d, i, o, u, x, or X conversion specifier applies
to a half-word BINARY argument (PIC 9(5) BINARY). It means the argument has
been promoted according to the integral promotions and its value moves to a
half-word BINARY field before printing.
This letter specifies that a following d, i, o, u, x, or X conversion specifier applies
to a full-word BINARY argument (PIC 9(10) BINARY). This letter specifies that a
following n conversion specifier applies to a full-word BINARY argument (PIC
9(10) BINARY.
This letter specifies that a following e, E, f, g, or G conversion specifier applies to
a COMP-2 argument.
If h, l, or L appears with any other conversion specifier, it is ignored.
7859 6137–009 6–53

CIFS$FPRINTF
d. ll
These letters (lowercase double L) specify that a following d, I, o, x, or X
conversion specifier applies to a 2-word PIC S1(72) BINARY-1 argument.
6. A character that specifies the type of conversion to be applied.
A field width or precision, or both, can be indicated by an asterisk (*) instead of a digit
string. In this case, a PIC 9(10) BINARY argument supplies the field width or precision.
The arguments specifying field width or precision must appear before the argument (if
any) to be converted. A negative field width argument is read as a - flag followed by a
positive field width. A negative precision argument is the same as if it were omitted.
Precision and width can also be indicated by an asterisk ( * ) followed by a decimal
integer and the $ character, where the decimal integer specifies the position in the
argument list of the integer argument containing the field width or precision.
The following table lists the flag characters and their meanings.
Flag
Character Description
- The result of the conversion is left justified within the field.
+ The result of a signed conversion always begins with a plus or minus sign.
Space If the first character of a signed conversion is not a sign, a space is placed
before the result. If the space and + flags both appear, the space flag is
ignored.
# The result is converted to an alternate form. For c, d, i, s, and u
conversions, the flag has no effect.
For o conversion, it increases the precision to force the first digit of the
result to be 0.
For x and X conversions, a nonzero result has 0x or 0X placed before it. For
e, E, f, g, and G conversions, the result always contains a decimal point,
even if no digits follow the decimal point (normally, a decimal point appears
in the result of these conversions only if a digit follows it). For g and G
conversions, trailing 0s are not removed from the result, as they normally
are.
0 For numeric conversions (d, i, o, u, x, X, e, E, f, g, G), the field width is
padded with leading zeros following any indication of sign or base; the field
is not padded with spaces.
If the 0 and - flags both appear, the 0 flag is ignored. For d, i, o, u, x, and X
conversions, the 0 flag is ignored if a precision is specified. For other
conversions, the behavior is undefined if a precision is specified.
Note: If the first character after the percent (%) sign is 0, then this
character is a zero flag, not a field width.
6–54 7859 6137–009

The following table lists the conversion specifiers and their meanings.
Specifier Description
CIFS$FPRINTF
c The least significant byte of the 9(10) BINARY argument is converted to a
character and printed.
d, i, o, u, x,
X
The 9(10) BINARY argument is converted to signed decimal (d or i),
unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal notation
(x or X). The letters abcdef are used for x conversion and the letters
ABCDEF for X conversion. The precision specifies the minimum number
of digits to appear. If the value being converted can be represented in
fewer digits, it is expanded with leading 0s. The default precision is 1. The
result of converting a 0 value with a precision of 0 is no characters.
e, E The COMP-2 argument is converted in the style [-]d.ddde+dd, where one
digit occurs before the decimal point and the number of digits after the
decimal point is equal to the precision.
When the precision is missing, 6 digits are produced. If the precision is 0,
no decimal point appears. The value is rounded to the appropriate number
of digits.
The E format code produces a number with E instead of e introducing the
exponent. The exponent always contains at least 2 digits. However, if the
magnitude to print is greater than or equal to 1E+100, additional exponent
digits are printed as necessary.
f The COMP-2 argument is converted to decimal notation in the style
[-]ddd.ddd, where the number of digits after the decimal point is equal to
the precision specification.
If the precision is missing, it is taken as 6; if the precision is explicitly 0, no
decimal point appears. If a decimal point appears, at least one digit
appears before it. The value is rounded to the appropriate number of
digits.
g, G For the g format code, the COMP-2 argument is printed in style f or e. For
a G format code, it is printed in style E. In each style, the precision
specifies the number of significant digits.
The style used depends on the value converted. Style e is used only if the
exponent resulting from the conversion is less than -4 or greater than the
precision. Trailing zeros are removed from the result. A decimal point
appears only if it is followed by a digit.
n The argument is taken to be a 9(10) BINARY integer into which is written
the number of characters written to the output stream so far by this call to
cifs$fprintf. No argument is converted.
p The argument is taken to be a PIC S1(72) BINARY-1 data item. The value
is printed as 24 octal digits.
7859 6137–009 6–55

CIFS$FPRINTF
Specifier Description
s The argument is taken to be an alphanumeric character string. Characters
from the string are written up to but not including the terminating NUL, or
until the number of characters indicated by the precision is written. If the
precision is missing, it is taken to be arbitrarily large so that all characters
before the first NUL are printed.
The maximum number of characters that can be printed for one %s
conversion is 6999.
% The character % is printed. No argument is converted.
Considerations for Conversion Specifications
If the conversion specifier is not one of the characters in the above table, the character is
printed and no argument is converted.
If any argument is or points to an aggregate (except for an array of characters using %s
conversion or any %p conversion), the behavior is undefined.
A nonexistent or small field width does not cause truncation of a field. If the conversion
result is wider than the field width, the field is expanded to contain the conversion result.
Return Values
If it completes successfully, the cifs$fprintf service subprogram returns the number of
characters transmitted into the chars-out argument. Otherwise, cifs$fprintf returns a
negative value in the argument.
Examples
Print a date and time in the form “Tuesday, July 3, 10:02,” where weekday and month
are strings:
CALL "cifs$frpintf" USING bytes-written, cifs-stdout-file,
"%s, %s %d, %.2d:%.2d/n",
weekday, month, day, hour, min.
Print pi to five decimal places:
01 r1 comp-2.
...
COMPUTE r1 = 4 * function atan(1.0).
CALL "cifs$fprintf" USING bytes-written, cifs-stdout-file,
"pi = %.5f/n", r1.
6–56 7859 6137–009

CIFS$FPUTC
Application
Use the cifs$fputc service subprogram to write a character to an output stream.
Synopsis
CALL "cifs$fputc" USING char, cifs-file, cifs-status.
Description
CIFS$FPUTC
The cifs$fputc service subprogram writes a character to an output stream, where:
char
cifs-file
is an alphanumeric data item that specifies the character to write.
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
The cifs$fputc service subprogram writes the character at the position indicated by the
associated file position indicator (if defined), advancing the indicator appropriately. If the
file position indicator is not defined, the character is appended to the output stream.
Return Values
If the cifs$fputc service subprogram returns successfully, the character specified in char
is written to the output stream and the cifs-status parameter is set to 0. Otherwise,
cifs$fputc sets cifs-status to identify the specific error that was encountered.
7859 6137–009 6–57

CIFS$FPUTS
CIFS$FPUTS
Application
Use the cifs$fputs service subprogram to write a string to an output stream.
Synopsis
CALL "cifs$fputs" USING string, cifs-file, chars-out, cifs-status.
Description
The cifs$fputs service subprogram writes a string to an output stream, where:
string
cifs-file
is an alphanumeric data item that contains the characters to be written to the output
stream.
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
chars-out
is a 1-word (S1(36) BINARY-1) data item that contains the number of characters
written to the output stream
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$fputs service subprogram returns successfully, the number of bytes written is
returned in chars-out and the cifs-status parameter is set to 0. Otherwise, cifs$fputs sets
cifs-status to identify the specific error that was encountered.
6–58 7859 6137–009

CIFS$FREAD
Application
CIFS$FREAD
Use the cifs$fread service subprogram to read elements from an input stream into an
array.
Synopsis
CALL "cifs$fread" USING buffer, elt-size, elt-count, cifs-file,
elts-read, cifs-status.
Description
The cifs$fread service subprogram reads elements from an input stream into an array,
where:
buffer
elt-size
is an alphanumeric character string.
specifies the size of an element in the array.
elt-count
cifs-file
specifies the number of elements to attempt to read.
is an opaque data item that describes an open instance of a file. It is a 2-word (S1(72)
BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the declaration of
this variable.
elts-read
specifies the number of elements read.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
The cifs$fread service subprogram advances the file position indicator (if defined) by the
number of bytes successfully read. If an error occurs, the resulting value of the file
position indicator is indeterminate. If a partial element is read, its value is indeterminate.
Use either the cifs$ferror or cifs$feof service subprogram to distinguish between a read
error and end of file.
7859 6137–009 6–59

CIFS$FREAD
Return Values
If it completes successfully, the cifs$fread service subprogram returns the number of
elements read into elts-read; this number can be less than elt-count if a read error or end
of file occurs. If either elt-size or elt-count is 0, cifs$fread returns 0 and both the contents
of the array and the state of the input stream remain unchanged. If an error occurs,
cifs-status is set to identify the specific error that was encountered.
6–60 7859 6137–009

CIFS$FREOPEN
Application
CIFS$FREOPEN
Use the cifs$freopen service subprogram to open a path name and associate a stream
with it. This service subprogram first attempts to close a file associated with the stream.
The primary use of cifs$freopen is to change the file associated with a standard text
stream (standard error, standard input, or standard output) since those identifiers are not
values that can be updated by the cifs$fopen service subprogram.
Synopsis
CALL "cifs$freopen" USING path, type-string, cifs-file, cifs-status.
Description
The cifs$freopen service subprogram opens a path and associates a stream with it,
where:
path
is an alphanumeric variable that contains the name of the file to be opened.
type-string
cifs-file
is an alphanumeric data item that contains one of the sequences in the table in
cifs$fopen. Additional characters can follow these sequences, but cifs$freopen
ignores them.
is an opaque data item that describes an open instance of a file. It is a 2-word (S1(72)
BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the declaration of
this variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
The cifs$freopen service subprogram first attempts to close any file associated with the
specified stream, ignoring any failure to close the file successfully.
Default Permissions When Creating a File
If the cifs$freopen service subprogram creates a file, it assigns read and write
permissions to the owner, group, and other permission classes by default.
7859 6137–009 6–61

CIFS$FREOPEN
The following file mode specification for the cifs$open service subprogram is equivalent:
compute cifs-mode-irwxu = cifs-mode-iread + cifs-mode-iwrite.
compute cifs-mode-irwxg = cifs-mode-iread + cifs-mode-iwrite.
compute cifs-mode-irwxo = cifs-mode-iread + cifs-mode-iwrite.
Return Values
If it completes successfully, the cifs$freopen service subprogram returns the value of
stream in the cifs-file parameter and place a 0 in cifs-status. Otherwise, cifs$freopen
sets cifs-status to identify the specific error that was encountered.
6–62 7859 6137–009

CIFS$FSCANF
Application
Use the cifs$fscanf service subprogram to read formatted input.
Synopsis
CALL "cifs$fscanf" USING items-scanned, cifs-file, format, [item...].
Description
The cifs$fscanf service subprogram reads formatted input, where:
items-scanned
cifs-file
format
item
CIFS$FSCANF
is a 1-word ( S1(36) BINARY-1 ) data item that contains the number of assigned input
items.
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item into which the value of the open instance of the file is
stored. Use the COBOL COPY PROC CIFS-FILE for the declaration of this variable.
A formatted output string can have a maximum of 32,767 characters.
controls the input by specifying how input text is converted for assignment.
Subsequent arguments are objects that receive the converted input. If there are
insufficient arguments for the format, a signal is generated. If the program recovers
from the signal, it treats it as if an asterisk flag were specified. If the format is
exhausted while arguments remain, cifs$fscanf evaluates the excess arguments but
otherwise ignores them.
is an alphanumeric data item that contains the data to be scanned.
Format Strings
The format argument can contain the following code:
• Any number of spaces, horizontal tabs, or newline (line feed) characters that cause
input to be read up to the next nonwhite-space character
• An ordinary character (not %) that must match the next character of the input stream
• Conversion specifications, consisting of the following sequence:
− The character % or the character sequence % digit $ decimal-integer
− An optional assignment-suppressing character *
− An optional decimal integer that specifies the maximum field width
7859 6137–009 6–63

CIFS$FSCANF
− An optional h, l, L, or ll (lowercase double L) indicating the size of the receiving
object
See “Conversion Specifications” below.
Conversion Specifications
A conversion specification directs the conversion of the next input field. Except for the
conversion specifiers c and [, an input field is defined as a sequence of nonspace
characters. It starts at the first character in the input that is not a white-space character
(ASCII characters 9 – 13 and a space) and extends to the first conflicting character or
until the field width, if specified, is exhausted.
When the form % decimal-integer $ is used, the decimal integer indicates to which
argument in the argument list to assign the results of the conversion. If decimal-integer
is n, the conversion results are assigned to the nth argument.
The service subprogram places the result in the object pointed to by the subsequent
argument, unless assignment suppression was indicated by an asterisk ( * ). The
conversion specifier indicates the interpretation of the input field. The corresponding
argument must be an appropriate type.
The following table lists the valid cifs$fscanf conversion specifiers.
Specifier Description
c A character is expected. The subsequent argument must be an
alphanumeric data item. The normal skip over white-space characters is
suppressed in this case. To read the next nonspace character, use %1s.
If a field width is given, the corresponding argument must refer to an
alphanumeric item. The indicated number of characters is read.
d A decimal integer is expected. The subsequent argument must be a
full-word BINARY data item.
e, E, f, g, G A floating-point number is expected. The corresponding argument must
be a floating point value.
i An integer is expected. The corresponding argument must be a full-word
BINARY data item.
n No input is consumed. The subsequent argument must be a full-word
BINARY data item into which is written the number of characters read
from the input stream so far by this call to cifs$fscanf. This is not
counted as a match input item.
o An octal integer is expected. The subsequent argument must be an
integer.
s A character string is expected. The subsequent argument must be an
alphanumeric data item that is large enough to accept the string and a
terminating NUL, which is added automatically. A space, a horizontal tab,
or a newline (line feed) character terminates the input field but is not part
of the field.
u An unsigned decimal integer is expected.
6–64 7859 6137–009

Specifier Description
The subsequent argument must be a full-word BINARY data item.
CIFS$FSCANF
x, X A hexadecimal integer is expected. The subsequent argument must be
an integer.
[ A string that is not to be delimited by spaces is expected. The normal
skip over white-space characters is suppressed in this case. The
subsequent argument must be an alphanumeric data item just as for %s.
The left bracket is followed by a set of characters followed by a right
bracket. The characters between the brackets define the set that
determines the input field string.
If the first character after the left bracket is not a circumflex (^), the input
field consists entirely of characters in the defining set. The first input
character not in the defining set signals the end of the input field.
If the first character after the left bracket is a circumflex (^), the input
field consists entirely of characters not in the defining set. The first input
character in the defining set signals the end of the input field.
If the first character is a right bracket (possibly following a circumflex), it
is assumed to be part of the set. A second right bracket is necessary to
delimit the set. This means the set of characters cannot be empty.
A NUL character is appended to the input.
% A single % is expected in the input at this point. No assignment occurs.
Considerations for Conversion Specifications
Only the characters in the table above can be used as conversion specifiers. If you use
any other character as a conversion specifier, the service subprogram does not recognize
it. Scanning terminates and the service subprogram returns the number of input items
successfully read.
The conversion specifiers d, i, o, u, and x can be preceded by h to indicate a PIC 9(5)
BINARY, or by ll (lowercase double L) to indicate a PIC S1(72) BINARY-1 data item.
Similarly, the conversion specifiers e and f can be preceded by l to indicate that the
subsequent argument is a COMP-2 data item rather than a COMP-1 data item, or by L to
indicate a COMP-2 data item.
If cifs$fscanf encounters the end of the file during a conversion, the conversion
terminates. If conversion terminates on a conflicting input character, the offending
character is left unread in the input stream. Trailing white-space characters (including a
newline character) are unread unless matched in the control string. The compiler cannot
directly determine the success of literal matches and suppressed assignments other
than through the %n conversion.
If a format does not have a corresponding argument, the format is treated as if an
asterisk (*) flag were specified.
7859 6137–009 6–65

CIFS$FSCANF
Return Values
If it completes successfully, the cifs$fscanf service subprogram returns the number of
assigned input items (which can be fewer than provided for, or even 0, in the event of an
early conflict between an input character and the format) into the items-scanned
argument, or EOF if end of file is encountered before the first conflict or conversion.
Otherwise, cifs$fscanf returns when it encounters the end of the format string.
6–66 7859 6137–009

CIFS$FSEEK
Application
CIFS$FSEEK
Use the cifs$fseek service subprogram to set the file position indicator for a stream.
Synopsis
CALL "cifs$fseek" USING cifs-file, offset, whence, cifs-status.
Description
The cifs$fseek service subprogram sets the file position indicator for a stream, where:
cifs-file
offset
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
is a 1-word ( 1(36) BINARY-1 ) data item specifying the number of characters to
move the indicator from the starting position.
whence
is a 1-word ( 1(36) BINARY-1 ) data item that specifies the starting position in the file,
which can be one of the following values:
0 The beginning of the file
1 The current position
2 The end of the file
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
The cifs$fseek service subprogram clears the end-of-file indicator and undoes any
effects of cifs$ungetc. After a call to cifs$fseek for an update file, the next operation can
be either input or output.
Return Values
If the cifs$fseek service subprogram completes successfully, it returns 0 in cifs-status.
Otherwise, cifs$fseek sets cifs-status to identify the specific error that was encountered.
7859 6137–009 6–67

CIFS$FSETPOS
CIFS$FSETPOS
Application
Use the cifs$fsetpos service subprogram to set the file position indicator for a stream.
Synopsis
CALL "cifs$fsetpos" USING cifs-file, cifs-fpos, cifs-status.
Description
The cifs$fsetpos service subprogram sets the file position indicator for a stream, where:
cifs-file
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
cifs-fpos
is a 2-word group item containing the new value for the file position indicator. Use
the COBOL COPY PROC CIFS-FPOS for the declaration of this variable. This
structure must be obtained by a call to the cifs$fgetpos service subprogram.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If it completes successfully, the cifs$fsetpos service subprogram returns 0 in cifs-status.
Otherwise, cifs$fsetpos sets cifs-status to identify the specific error that was
encountered.
6–68 7859 6137–009

CIFS$FSTAT
Application
CIFS$FSTAT
Use the cifs$fstat service subprogram to retrieve information about an open file. In
particular, you can get information about the file mode, security attributes, file size, and
access times.
The cifs$fstat service subprogram uses a file descriptor to identify the file or directory.
See the cifs$stat service subprogram for a similar service subprogram that uses a path
name.
Synopsis
CALL "cifs$fstat" USING fildes, cifs-stat, cifs-status.
Description
The cifs$fstat service subprogram returns information about an open file in a group item,
where:
fildes
is a 1-word (S1(36) BINARY-1) data item which contains the file description of the file
to be used.
cifs-stat
is a group item in which cifs$fstat returns the file information. Use the COBOL
COPY PROC CIFS-STAT for the declaration of this variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
7859 6137–009 6–69

CIFS$FSTAT
The cifs-stat Data Item
The cifs-stat group item identifies certain information about a file or directory. The
following table describes the data item, which is defined in the COBOL COPY PROC
CIFS-STAT. The size of the data item cifs-stat is 44 bytes.
Field Name Offset Description
cifs-stat-mode 0 File mode.
cifs-stat-ino 4 File serial number.
cifs-stat-dev 8 Numeric identifier for the file system in which
the file resides.
cifs-stat-nlink 12 Number of links to the file or directory.
cifs-stat-uid 16 Owner user ID of file or directory.
cifs-stat-gid 20 Group-ID of file or directory.
cifs-stat-size 24 Size, in bytes, for directories or regular files;
bytes available to be read for pipe or FIFO
files.
cifs-stat-rdev 28 If the inode represents a device file, this value
identifies the specific type of device that the
inode controls. The values are
1 = /dev/tty
2 = standard input, output, or error device
3 = /dev/null
4 = /dev/random or /dev/urandom
cifs-stat-atime 32 Time of last access to file data.
cifs-stat-mtime 36 Time of last data modification.
cifs-stat-ctime 40 Time of file creation.
Return Values
If the cifs$fstat service subprogram completes successfully, it returns 0 in cifs-status.
Otherwise, cifs$fstat sets cifs-status to identify the specific error that was encountered.
Error Codes
If any of the following conditions occurs, the cifs$fstat service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EBADF fildes is not a valid file descriptor.
CIFS-EFAULT The address stored in cifs-stat is invalid.
6–70 7859 6137–009

CIFS$FSYNC
Application
CIFS$FSYNC
Use the cifs$fsync service subprogram to write to the device all data currently in the
buffer cache for a file, thus protecting the data against loss due to a system outage.
With cifs$fsync, an application can synchronize all file updates at one time, instead of on
every read or write operation. The cifs$fsync service subprogram also synchronizes file
access times.
For a similar service subprogram that does not synchronize file access times, see
cifs$fdatasync. For alternate methods of synchronizing disk data, see the discussions of
the CIFS-OFLAG-SYNC and CIFS-OFLAG-DSYNC flags under the cifs$open and cifs$fcntl
service subprograms.
Synopsis
CALL "cifs$fsync" USING fildes, cifs-status.
Description
The cifs$fsync service subprogram writes from the buffer cache to the mass storage
device all data belonging to the specified file, where fildes specifies a regular file open
for writing.
fildes
is a 1-word (S1(36) BINARY-1) data item which contains the file description of the file
to be used.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$fsync service subprogram completes successfully, it returns 0 in cifs-status.
Otherwise, cifs$fsync sets cifs-status to identify the specific error that was encountered.
Error Codes
If any of the following conditions occurs, the cifs$fsync service subprogram returns a
nonzero value in the cifs-status parameter.
The following COBOL level 88 condition names (defined in the COBOL COPY PROC
CIFS-API) can be checked in order to determine the error that was returned:
CIFS-EBADF fildes is not a valid file descriptor open for writing.
CIFS-EINVAL Data synchronization is not supported for the type of file described by
fildes.
CIFS-EIO The file could not be fully synchronized because of an I/O error.
7859 6137–009 6–71

CIFS$FTELL
CIFS$FTELL
Application
Use the cifs$ftell service subprogram to obtain the current value of the file position
indicator for a stream.
Synopsis
CALL "cifs$ftell" USING cifs-file, offset, cifs-status.
Description
The cifs$ftell service subprogram obtains the current value in bytes of the file position
indicator for a stream, relative to the beginning of the file, where:
cifs-file
offset
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
is a 1-word ( 1(36) BINARY-1 ) data item that contains the file position indicator for
the stream returned from cifs$ftell.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$ftell service subprogram returns successfully, the current value of the file
position indicator for the stream, relative to the beginning of the file, is placed into the
offset parameter and the cifs-status parameter is set to 0. Otherwise, cifs$ftell sets
cifs-status to identify the specific error that was encountered.
6–72 7859 6137–009

CIFS$FTRUNCATE
Application
CIFS$FTRUNCATE
The cifs$ftruncate service subprogram sets the end-of-file position for an open file.
Synopsis
CALL "cifs$ftruncate" USING fildes, length, cifs-status.
Description
A file referenced by the descriptor fildes has its size (in bytes) set to length. If the file
was previously longer than the length specified, those bytes are no longer accessible. If
the file was previously shorter than the length specified, bytes between the old end of
file and the specified length are read as zeroes. For cifs$ftruncate, the calling program
must have the file open for writing.
For files stored in SDF format, the length value of 34359738367 (defined as INT_MAX in
the limits.h header file) has special meaning. CIFS treats this as an indication that it must
recalculate the actual size of the file when next read based on the position of the EOF
record, rather than pad the file with zeroes.
fildes
length
is a 1-word (S1(36) BINARY-1) data item which contains a file descriptor of the file
being used.
is a 1-word (S1(36) BINARY-1) data item.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$ftruncate service subprogram completes successfully, it returns 0 in
cifs-status. Otherwise, cifs$fruncate sets cifs-status to identify the specific error that
was encountered.
7859 6137–009 6–73

CIFS$FWRITE
CIFS$FWRITE
Application
Use the cifs$fwrite service subprogram to write elements from a buffer to an output
stream.
Synopsis
CALL "cifs$fwrite" USING buffer, elt-size, elt-count, cifs-file,
elts-written, cifs-status.
Description
The cifs$fwrite service subprogram writes elements from an array to an output stream,
where:
buffer
elt-size
is an alphanumeric character string to be written to the output stream.
specifies the size of an element in the array.
elt-count
cifs-file
specifies the number of elements to attempt to write.
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
elts-written
specifies the number of elements written.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
The cifs$fwrite service subprogram advances the file position indicator by the number of
bytes successfully written. If an error occurs, the resulting value of the file position
indicator is indeterminate.
Return Values
If it completes successfully, the cifs$fwrite service subprogram returns the number of
elements written into elts-written; this number is less than elts-count only if a write error
occurs. If an error occurs, cifs-status is set to identify the specific error that was
encountered.
6–74 7859 6137–009

CIFS$GETC
Application
CIFS$GETC
Use the cifs$getc service subprogram to obtain the next character from an input stream.
Synopsis
CALL "cifs$getc" USING cifs-file, next-char, cifs-status.
Description
The cifs$getc service subprogram is equivalent to cifs$fgetc.
cifs-file
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
next-char
is a 1-byte field used to hold the next character that is retrieved.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$getc service subprogram completes successfully, it returns the next character
from the specified input stream and returns 0 in cifs-status. Otherwise, cifs$getc sets
cifs-status to identify the specific error that was encountered.
Application
Use the cifs$getchar service subprogram to obtain the next character from standard
input.
Synopsis
CALL "cifs$getchar" USING next-char, cifs-status.
Description
The cifs$getchar service subprogram is equivalent to calling cifs$getc with the cifs-file
argument set to standard input.
next-char
is a 1-byte field used to hold the next character that is retrieved.
7859 6137–009 6–75

CIFS$GETC
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
The cifs$getchar service subprogram returns the next character from standard input and
returns 0 in cifs-status. Otherwise, cifs$getchar sets cifs-status to identify the specific
error that was encountered.
6–76 7859 6137–009

CIFS$GETCWD
Application
CIFS$GETCWD
Use the cifs$getcwd service subprogram to identify a process' current working directory.
You can specify where the information is returned.
Synopsis
CALL "cifs$getcwd" USING path-buffer, max-size, cifs-status.
Description
The cifs$getcwd service subprogram identifies the absolute path name of the current
working directory of the calling process, where:
path-buffer
is an alphanumeric field into which the cifs$getcwd service subprogram returns the
path name of the current working directory in the path.
max-size
is the size in bytes of path-buffer. This variable must be declared as 9(10) BINARY. If
the path name of the working directory has more characters in it than max-size
allows, an error occurs.
cifs-status
is a 1-word (1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$getcwd service subprogram completes successfully, it returns the absolute
path name for the current working directory into the parameter path-buffer. Otherwise,
cifs$getcwd sets cifs-status to identify the specific error that was encountered.
Error Codes
If any of the following conditions occurs, the cifs$getcwd service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EFAULT The path-buffer is invalid.
CIFS-EINVAL max-size is less than or equal to 0.
CIFS-ENOMEM The path-buffer is null and no memory space is available to the
process.
CIFS-ERANGE max-size is greater than 0 but less than the length of the path
name plus 1.
7859 6137–009 6–77

CIFS$GETS
CIFS$GETS
Application
Use the cifs$gets service subprogram to read a string of characters from standard input
into an array.
Synopsis
CALL "cifs$gets" USING string, cifs-status.
Description
The cifs$gets service subprogram reads characters from the standard input stream and
places them into the argument string, until it encounters the end of the file or a newline
(line feed) character. Cif$gets discards any newline character and writes a nul character
immediately after the last character in the character string.
string
is an alphanumeric data item that contains the characters read from the standard
input stream.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If cifs$gets completes successfully, the service subprogram returns the characters into
the string parameter and returns 0 in cifs-status. If cifs$gets encounters end of file
before reading any characters into the string parameter, the contents of the string
parameter remain unchanged. If a read error occurs, the contents of the array are
indeterminate. Otherwise, cifs$gets sets cifs-status to identify the specific error that
was encountered.
6–78 7859 6137–009

CIFS$ISTAT
Application
CIFS$ISTAT
Use the cifs$istat service subprogram to retrieve CIFS-unique information about a file or
directory.
Synopsis
CALL "cifs$istat" USING cifs-stat-ino, cifs-istat, size, cifs-status.
Description
If cifs-stat-ino corresponds to a valid file serial number, the service subprogram places up
to size bytes of the following information into the cifs-istat area. The cifs-stat-ino
argument is typically obtained from the CIFS-STAT-INO field of the CIFS-STAT group
item (COPY PROC CIFS-STAT) returned by a cifs$stat or cifs$fstat service subprogram.
cifs-stat-ino
is a data item that corresponds to a valid file serial number. The COBOL COPY PROC
CIFS-STAT contains the declaration of this variable.
cifs-istat
size
is group item in which cifs$istat returns the file information. Use the COBOL COPY
PROC CIFS-STAT for the declaration of this variable.
is a 1-word ( 1(36) BINARY-1 ) data item that contains the number of bytes to store
into the cifs-istat buffer.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
The CIFS-ISTAT buffer contains the following fields.
Field Name Offset Description
cifs-istat-cycle 0 OS 2200 absolute F-cycle of this file.
cifs-istat-cycle-chain 4 Inode number of the next OS 2200 F-cycle
of this same file name. See File Definition
and File Types in Section 3 for a description
of inode.
cifs-istat-alt-os-dir-ino 8 Inode number of the alternate OS 2200
directory version of this file name. See File
Definition and File Types in Section 3 for a
description of inode.
7859 6137–009 6–79

CIFS$ISTAT
Field Name Offset Description
cifs-istat-os2200 12 Indicates where a directory inode appears in
the /os2200 hierarchy. See File Definition
and File Types in Section 3 for a description
of inode.
Can contain the following values:
0 Not in the /os2200 hierarchy
1 The /os2200 directory
2 An immediate subdirectory (qualifier) of
/os2200
3 A program or data file in the /os2200
hierarchy
cifs-istat-owner 16 Owner of the file. For owned files, this is the
OS 2200 user ID. For unowned files, this is
the project or account, depending on the
value of the configuration variable PRIVAC.
cifs-istat-directory 29 The OS 2200 MFD containing this file; either
STD or SHARED.
cifs-istat-contain 36 For regular files, the name of the underlying
OS 2200 file container. The field contains a
null string for other file types.
cifs-istat-element-name 74 The element name associated with the file;
null string if the file is not stored as an
OS 2200 element.
cifs-istat-element-version 87 The element version associated with the file;
not used if the file is not stored as an
OS 2200 element.
cifs-istat-element-type 100 The type of the underlying element, either 1,
5, 6, or 7. Not used if the file is not stored
as an OS 2200 element.
cifs-istat-element-sub-type 102 The subtype of the underlying symbolic or
omnibus element; not used for other
element types or if the file is not stored as
an OS 2200 element.
cifs-istat-share 104 For directories, the network share name
assigned to it; a null string if the directory is
not shared.
cifs-istat-acr 136 The ACR name associated with a file.
The size of CIFS-ISTAT is 144 bytes. The data item CIFS-ISTAT-SIZE contains this
information. The data is stored in the order listed; whatever does not fit in size bytes is
discarded.
Return Values
If the cifs$istat service subprogram completes successfully, it returns 0 in cifs-status.
Otherwise, cifs$istat sets cifs-status to identify the specific error that was encountered.
6–80 7859 6137–009

CIFS$LINK
Application
CIFS$LINK
Use the cifs$link service subprogram to create new directory entries for a file, allowing
you to reference one file in multiple ways. The new entries can be in the same directory
or in different directories.
cifs$link increases the link count of the referenced file by 1.
Synopsis
CALL "cifs$link" USING path1, path2, cifs-status.
Description
The cifs$link service subprogram creates a new directory entry (link), provided the
process has the necessary permissions (see “Permissions Required” in this subsection),
where:
path1
path2
is an alphanumeric variable that contains the name of an existing regular or FIFO file.
is an alphanumeric variable that contains the path name for the new link for the file
named by path1. The directory in which the new link is created must be in the same
file system as path1.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Diagrams
The cifs$link service subprogram causes both directory entries to refer to the same
physical file. In the following diagrams, both link_1 and link_2 refer to the same file,
whether they are in the same directory or not.
7859 6137–009 6–81

CIFS$LINK
Permissions Required
The calling process must have all the following permissions to create the link:
• Search permission for all the path1 component directories
• Search permission for all the path2 component directories
• Write permission to the parent directory of the new file
Return Values
If the cifs$link service subprogram completes successfully, it does the following:
• Updates the last accessed time field of the path1 file
• Updates the last modified time field of the path2 directory
• Returns 0 in cifs-status
Otherwise, cifs$link sets cifs-status to identify the specific error that was encountered.
6–82 7859 6137–009

Error Codes
CIFS$LINK
If any of the following conditions occurs, the cifs$link service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EACCES Any of the following errors occurred:
• The calling process is denied search permission to a
component of either path name.
• The calling process is denied write permission to the
path2 directory.
CIFS-EEXIST The link named by path2 already exists.
CIFS-EFAULT The value specified by path1 or path2 is invalid.
CIFS-EIO An I/O error occurred.
CIFS-EMLINK The number of links to the file named by path1 exceeds the
maximum.
CIFS-ENOENT Any of the following errors occurred:
• A directory in either path name does not exist.
• The file in path1 does not exist.
• Either path1 or path2 contains an empty string.
CIFS-ENOSPC The path2 directory to contain the link has too many entries.
CIFS-ENOTDIR A component of either path name prefix is not a directory.
CIFS-EPERM The file named by path1 is a directory or a character file.
7859 6137–009 6–83

CIFS$LSEEK
CIFS$LSEEK
Application
Use the cifs$lseek service subprogram to set the read/write offset for an open file at a
specific position in the file. You can also set the read/write offset beyond the end of
existing data in the file without increasing the file size; however, a write operation at that
location increases the file size.
Definition
The read/write offset is the file address at which the next cifs$read or cifs$write
operation starts.
Synopsis
CALL "cifs$lseek" USING fildes, offset, whence, new-offset, cifs-status.
Description
The cifs$lseek service subprogram sets the read/write offset for an open file description,
where:
fildes
offset
is a 1-word (S1(36) BINARY-1) data item which contains the file description of the file
to be used.
is a 1-word ( 1(36) BINARY-1 ) data item that specifies the new location of the
read/write offset from the beginning, current position, or end of a file, as shown in
the table and diagram below.
whence
is a 1-word ( 1(36) BINARY-1 ) data item that specifies whether the read/write offset
is calculated from the beginning, current position, or end of a file. See the following
table and diagram for the valid values for whence and their relationships to offset.
Value of
whence
How the Read/Write Offset Is
Calculated
1 Current offset value plus offset bytes
2 Size of the file plus offset bytes
0 offset bytes from the beginning of the
file
6–84 7859 6137–009

new-offset
CIFS$LSEEK
is a 1-word ( 1(36) BINARY-1 ) data item that specifies the new read/write offset
from the beginning of the file.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Illustration
Given a value for offset, the value of whence determines whether the read/write offset
occurs at the beginning, current position, or end of a file. The following diagram shows
the possible new positions of the read/write offset:
Reading Unwritten Areas
If a file contains unwritten gaps, reading these areas returns bytes with the value 0.
However, files created outside of CIFS can contain unwritten data that is not detectable;
reading these areas returns bytes with indeterminate values.
Service Subprogram Behavior for Different File Types
All calls to cifs$lseek fail for the following file types:
• Pipes
• FIFO files
For some types of files, a read/write offset is not meaningful; for these files, the
read/write offset returned by cifs$lseek is undefined.
Portability Issue
In other implementations, the returned argument new-offset can be unsigned. To test
for an error in a portable way, compare the returned argument new-offset with -1.
7859 6137–009 6–85

CIFS$LSEEK
Return Values
If the cifs$lseek service subprogram completes successfully, it returns the new
read/write offset location in bytes from the beginning of the file in the new-offset
argument. Otherwise, cifs$lseek sets cifs-status to identify the specific error that was
encountered and returns a value of –1 in the new-offset argument.
Error Codes
If any of the following conditions occurs, the cifs$lseek service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EBADF fildes is not a valid file descriptor.
CIFS-EINVAL One of the following errors occurred:
• whence is invalid.
• The resulting read/write offset would be
invalid (that is, negative).
CIFS-ESPIPE fildes is associated with a pipe or FIFO file.
6–86 7859 6137–009

CIFS$MASK
Application
CIFS$MASK
Use the cifs$mask service subprogram to determine whether a given string matches a
wild card pattern.
Note: There is no POSIX equivalent to cifs$mask.
Synopsis
CALL "cifs$mask" USING name, mask, result.
Description
name
mask
result
is an alphanumeric variable that contains the name to check.
is an alphanumeric variable that contains the mask characters.
is a 1-word ( 1(36) BINARY-1 ) data item that contains the result of the operation.
The cifs$mask service subprogram checks the name parameter for conformance with
the mask parameter. The mask parameter may contain the wild card characters asterisk
(*) and question mark (?).
A question mark matches a single occurrence of any character; an asterisk matches zero
or more occurrences of any character. Other characters in mask must be a
case-insensitive match to ones in the corresponding positions of name, in order for the
service subprogram to return a nonzero result. For example, the name “abcdef”
conforms to “abc*” and “aBc???”, but not to “abc?” Wild card characters may be mixed
in any order and with any other characters.
Return Values
The cifs$mask service subprogram returns nonzero in the result argument if name
conforms to mask, 0 if it does not.
7859 6137–009 6–87

CIFS$MKDIR
CIFS$MKDIR
Application
Use the cifs$mkdir service subprogram to create a new directory, setting its file
permissions and security attributes. The directory is empty except for its dot and dot-dot
entries. Once the directory is created, you can make directory entries.
Synopsis
CALL "cifs$mkdir" USING path, cifs-mode, cifs-status.
Description
The cifs$mkdir service subprogram creates a directory containing only the dot and dotdot
entries, where:
path
is an alphanumeric data item that contains the name of the new directory.
cifs-mode
is a 1-word (1(36) BINARY-1) data item that contains the file permission settings for
the new file, which are first modified by the file mode creation mask of the calling
process. Use the COBOL COPY PROC CIFS-MODE for the declaration of this
variable. In addition to the permission bits, you can specify the creation of a Large
Element Program File (LEPF); see CIFS$CHMOD for the LEPF and NPF mode
settings.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
File Mode Attributes
The cifs$mkdir service subprogram also sets the following attributes in the file mode for
the directory:
• The user ID of the new directory to the effective user ID of the calling process
• The group-ID of the new directory, to the effective group-ID of the process
Return Values
If the cifs$mkdir service subprogram completes successfully, it does the following:
• Sets the file permissions, user ID, and group-ID for the new directory, as discussed
in the preceding paragraphs
• Sets the last accessed, last modified and last file status change fields of the new
directory
• Updates the last accessed and last modified fields of the parent directory
6–88 7859 6137–009

• Returns 0 in the cifs-status parameter
Otherwise, cifs$mkdir sets cifs-status to identify the specific error that was
encountered.
Error Codes
CIFS$MKDIR
If any of the following conditions occurs, the cifs$mkdir service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EACCES The calling process is denied one of the following:
• Search permission to a directory in the path name
• Write permission on the parent directory of the new directory
CIFS-EEXIST A directory with the same path name already exists.
CIFS-EFAULT The value specified by path is invalid.
CIFS-EINVAL cifs-mode has undefined bits set.
CIFS-EMLINK The link count of the parent directory exceeds the C standard
value INT_MAX.
CIFS-ENOENT Either of the following errors occurred:
• A directory in the path name does not exist.
• path contains an empty string.
CIFS-ENOSPC Either of the following errors occurred:
• The parent directory has too many entries.
• The file system does not have enough space to hold the new
directory.
CIFS-ENOTDIR A component of the path name prefix is not a directory.
7859 6137–009 6–89

CIFS$MKFIFO
CIFS$MKFIFO
Application
Use the cifs$mkfifo service subprogram to create a new first-in-first-out (FIFO) file,
setting its file permissions and security attributes. The new FIFO file is empty.
Synopsis
CALL "cifs$mkfifo" USING path, cifs-mode, cifs-status.
Description
The cifs$mkfifo service subprogram creates a FIFO file, where:
path
is an alphanumeric data item that contains the name of the new FIFO file.
cifs-mode
is a 1-word (1(36) BINARY-1) data item that contains the file permission settings for
the new FIFO file, which are first modified by the file mode creation mask of the
calling process. Use the COBOL COPY PROC CIFS-MODE for the declaration of this
variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
File Mode Attributes
The cifs$mkfifo service subprogram also sets the following attributes in the file mode:
• The user ID of the new FIFO file to the effective user ID of the calling process
• The group-ID of the new FIFO file to the effective group-ID of the process
Return Values
If the cifs$mkfifo service subprogram completes successfully, it does the following:
• Sets the file permissions, user ID, and group ID for the new FIFO file, as discussed
in the preceding paragraphs
• Sets the last accessed, last modified and last file status change fields of the new
FIFO file
• Updates the last accessed and last modified fields of the parent directory
• Returns 0 in the cifs-status parameter
Otherwise, cifs$mkfifo sets cifs-status to identify the specific error that was
encountered.
6–90 7859 6137–009

Error Codes
CIFS$MKFIFO
If any of the following conditions occurs, the cifs$mkfifo service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned.
CIFS-EACCES The calling process is denied one of the
following:
• Search permission to a component of the
path name
• Write permission to the parent directory of
the new file
CIFS-EEXIST A file with the same path name already exists.
CIFS-EFAULT The value specified by path is invalid.
CIFS-EINVAL cifs-mode has bits set that are either
undefined or not file permission bits.
CIFS-ENOENT Either of the following errors occurred:
• A directory in the path name does not
exist.
• path points to an empty string.
CIFS-ENOSPC Either of the following errors occurred:
• The parent directory has too many entries.
• The file system does not have enough
resources for file allocation.
CIFS-ENOTDIR A component of the path prefix is not a
directory.
CIFS-EROFS The parent directory exists on a read-only file
system.
7859 6137–009 6–91

CIFS$OPEN
CIFS$OPEN
Application
Use the cifs$open service subprogram to open a file, specifying how you can access the
file and setting special attributes. Opening a file does the following:
• Creates an open file description and corresponding file descriptor for this unique
instance of the open file.
Note: The new open file description is not shared by any other process on the
system; the file descriptor identifies this open file description only.
• Can create the file, if it does not already exist. In this case, you must also specify the
file permissions for the file mode. See also the cifs$creat service subprogram.
Synopsis
CALL "cifs$open" USING path, cifs-oflag, cifs-mode, new-fd, cifs-status.
Description
The cifs$open service subprogram opens a file, where:
path
is an alphanumeric variable that contains the name of the file to be opened.
cifs-oflag
sets the access specification and file status flags in the open file description. See
"The oflag Argument" in a following subsection for the valid values for cifs-oflag. Use
the COBOL COPY PROC CIFS-OFLAG for the declaration of this variable.
cifs-mode
new-fd
is a 1-word (1(36) BINARY-1) data item that sets the file permissions when a new file
is created (see the file status flag CIFS-OFLAG-CREAT). See “The mode Argument”
in a following subsection for the valid values for cifs-mode. Use the COBOL COPY
PROC CIFS-MODE for the declaration of this variable.
is a 1-word (S1(36) BINARY-1) data item into which the file description of the newly
created file is placed.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
6–92 7859 6137–009

Results of Opening a File
The cifs$open service subprogram does the following:
1. Sets the initial read/write offset to the start of the file
2. Selects the numerically lowest available file descriptor for the process
CIFS$OPEN
3. Returns the file descriptor so that other I/O service subprograms can access the file
Example
The following code statement opens a file that does not currently exist:
move 0 to cifs-oflag.
move 1 to cifs-oflag-creat.
move 1 to cifs-oflag-wronly.
move 1 to cifs-oflag-rdonly.
move 0 to cifs-mode.
compute cifs-mode-irwxu = cifs-mode-iread + cifs-mode-iwrite.
compute cifs-mode-irwxg = cifs-mode-iread + cifs-mode-iwrite.
CALL "cifs$open" USING "/books/novels/f_inventory", cifs-oflag,
cifs-mode, fd-inventory, cifs-status.
The statement does the following tasks:
• Creates the file f-inventory in the directory /books/novels
• Opens the file for reading and writing
• Assigns read and write permission for the owner and group classes
• Captures the file descriptor returned by cifs$open in fd-inventory
Files Affected by cifs$open
A process must open a file before reading from or writing to it. The cifs$open service
subprogram opens the following types of files:
• Regular files
• FIFO files
• Directories (for reading only)
Note: The cifs$open service subprogram can also create a regular file if it does not
exist. The other types of files must exist before cifs$open can access them.
Return Values
If the cifs$open service subprogram completes successfully, it does the following:
• Updates the following time information fields if CIFS-OFLAG-CREAT is set and the
file does not exist:
− The last accessed, last modified, and last file status change fields for the file
− The last accessed and last modified fields for the parent directory
7859 6137–009 6–93

CIFS$OPEN
• Updates the last accessed and last modified time information fields for the file if
CIFS-OFLAG-TRUNC is set for an existing file
• Returns the file descriptor in new-fd
Otherwise, cifs$open sets cifs-status to identify the specific error that was encountered.
Error Codes
If any of the following conditions occurs, the cifs$open service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned.
CIFS-EACCES Any of the following access errors occurred:
• The calling process is denied search permission on one or
more directories in path.
• The file exists and the permissions specified by cifs-oflag
are denied.
• The file does not exist and write permission is denied for
the parent directory of the file to be created.
• CIFS-OFLAG-TRUNC is specified and write permission is
denied.
CIFS-EAGAIN A resource is temporarily unavailable. Either the calling
process attempted to open a file that was rolled out with
O_NONBLOCK set, or the wait time specified by the
CIFS$WAITROLBAK environment variable expired. This is a
temporary condition and a subsequent call might complete
normally.
CIFS-EBUSY A resource is temporarily unavailable. Either the calling
process attempted to open a file that was exclusively
assigned with O_NONBLOCK set, or the wait time specified
by the CIFS$WAITXUSE environment variable expired. This is
a temporary condition and a subsequent call might complete
normally.
CIFS-EEXIST CIFS-OFLAG-CREAT and CIFS-OFLAG-EXCL are set and the file
exists.
CIFS-EFAULT The name specified by path is invalid.
CIFS-EINTR The cifs$open operation was interrupted by a signal.
CIFS-EINVAL Any of the following errors occurred:
• CIFS-OFLAG-CREAT is specified and cifs-mode is missing.
• A cifs$open service subprogram call with read-only
access and CIFS-OFLAG-TRUNC specified is not valid. The
two options are incompatible.
• cifs-oflag has neither the CIFS-OFLAG-RDONLY or the
CIFS-OFLAG-WRONLY flags set. One of these flags must
be set.
• A cifs$open service subprogram call with more than one
of CIFS-MODE-1100SDF and CIFS-MODE-1100BIN
specified is not valid.
6–94 7859 6137–009

CIFS$OPEN
A file cannot have more than one of these attributes.
• A cifs$open service subprogram call for a FIFO file with
read/write access is not valid.
• Either cifs-oflag or cifs-mode has undefined bits set.
CIFS-EIO An input/output error occurred.
CIFS-EISDIR The file is a directory and cifs-oflag specifies write access.
CIFS-EMFILE The calling process is attempting to open a file and the limit
on the maximum number of open file descriptors for a
process would be exceeded.
CIFS-ENOENT Either of the following errors occurred:
• CIFS-OFLAG-CREAT is not set and the file does not exist.
• CIFS-OFLAG-CREAT is set and either
− A directory in the path name does not exist.
− path contains an empty string.
CIFS-ENOSPC The directory or file system that is to contain the new file is
out of available space.
CIFS-ENOTDIR A component of the path name prefix is not a directory.
CIFS-ENXIO CIFS-OFLAG-NONBLOCK and CIFS-OFLAG-WRONLY are set
for a FIFO file and no process has the file open for reading.
The cifs-oflag Argument
The cifs-oflag argument contains the following values:
• An access specification value
• Any combination of values for file status flags
Use the COBOL COPY PROC CIFS-OFLAG for the declaration/definition of the cifs-oflag
fields.
7859 6137–009 6–95

CIFS$OPEN
Access Specification Values
The following symbolic constants are valid access specifications.
CIFS-OFLAG-RDONLY Open the file for reading only.
CIFS-OFLAG-WRONLY Open the file for writing only.
File Status Flag Values
The following symbolic constants are valid file status flags.
CIFS-OFLAG-APPEND The read/write offset is set to the end of the file before
each write operation.
CIFS-OFLAG-CREAT The cifs$open service subprogram
• Creates a regular file with path as its path name
• Sets ownership of the regular file, as follows:
− Sets the user ID of the file to the effective
user ID of the process
− Sets the group ID of the file to the effective
group ID of the process
When CIFS-OFLAG-CREAT is set, cifs$open requires a
third argument, cifs-mode. The file permission attributes
are set to the value in cifs-mode minus the attributes set
in the process' file mode creation mask (see the
cifs$umask service subprogram). The cifs-mode
argument does not affect whether the file is opened for
read or write access or both.
CIFS-OFLAG-DSYNC The cifs$open service subprogram opens the file for
synchronized read and write operations. The kernel
implements a buffering system for the file data in volatile
storage. I/O buffering increases the speed at which data
can be accessed and changed, but it also increases the
risk of lost data due to a system failure. When file I/O
operations are not synchronized, it is possible for file data
to reside in volatile storage for some period of time
without being written to a disk device.
Setting the CIFS-OFLAG-DSYNC flag
• Causes any data written through the file descriptor to
also be written to the disk device before the
cifs$write service subprogram returns
• Ensures that any data read from a file descriptor is
written to the disk device before the cifs$read service
subprogram returns that data
CIFS-OFLAG-EXCL Use CIFS-OFLAG-EXCL with CIFS-OFLAG-CREAT to
ensure that the file does not already exist, as follows.
6–96 7859 6137–009

If CIFS-OFLAG-EXCL is ... And CIFS-OFLAG-CREAT is
...
Then ...
CIFS$OPEN
Set Set cifs$open fails if the file
exists.
Set Not set cifs$open ignores CIFS-
OFLAG-EXCL.
Not set Set cifs$open opens the file if
it already exists;
otherwise, cifs$open
creates the file.
Not set Not set cifs$open opens the file if
it already exists;
otherwise, cifs$open fails.
CIFS-OFLAG-NONBLOCK This value determines whether cifs$open waits for
certain file availability or fails, as follows.
If CIFS-OFLAG-
NONBLOCK is ...
And the file type
is ... Then...
Set Regular cifs$open fails if the
OS 2200 file container is
rolled out or otherwise
temporarily unavailable.
Set FIFO For read-only access,
cifs$open returns
without a delay.
For write-only access,
cifs$open fails if no
process has the file open
for reading.
7859 6137–009 6–97

CIFS$OPEN
If CIFS-OFLAG-
NONBLOCK is ...
And the file type
is ... Then...
Not set Regular The process waits if the
OS 2200 file container is
rolled out or exclusively
assigned. The maximum
wait time can be
specified by the
CIFS$WAITROLBAK and
CIFS$WAITXUSE
environment variables.
Not set FIFO For read-only access,
cifs$open waits until a
process opens the file
for writing.
For write-only access,
cifs$open waits until a
process opens the file
for reading.
CIFS-OFLAG-NONBLOCK This has no effect when opening any other type of
file.
CIFS-OFLAG-SYNC This value has the same effect as CIFS-OFLAG-
DSYNC, with the addition of ensuring that file access
times are updated on the disk device before returning
from cifs$read or cifs$write requests on the file
descriptor. Setting both CIFS-OFLAG-SYNC and
CIFS-OFLAG-DSYNC has the same effect as setting
only CIFS-OFLAG-SYNC.
CIFS-OFLAG-TRUNC This value truncates the file length to zero, leaving
the file mode and file owner unchanged. This affects
only a regular file opened with write-only or
read/write access. A call to cifs$open with read-only
access and CIFS-OFLAG-TRUNC set returns an error.
The cifs-mode Argument
The cifs-mode (use COBOL COPY PROC CIFS-MODE for this declaration) argument
contains the following attributes for a newly created file (see Section 3 for a discussion
of the attributes in the file mode):
• File permission attributes
The file permission attributes can be set into three different permission classes
− Owner (CIFS-MODE-IRWXU)
− Group (CIFS-MODE-IRWXG)
− Other (CIFS-MODE-IRWXO)
6–98 7859 6137–009

CIFS$OPEN
These permission classes can be set using the permission attribute variables
CIFS-MODE-IREAD, CIFS-MODE-IWRITE and CIFS-MODE-IEXEC. For example to
set read and write permission to the owner class, use the following command:
COMPUTE CIFS-MODE-IRWXU = CIFS-MODE-IREAD + CIFS-MODE-IWRITE.
To set read permission to the group class, use the following command:
COMPUTE CIFS-MODE-IRWXG = CIFS-MODE-IREAD.
• File format attributes
− Binary format: CIFS-MODE-1100BIN
− System data format (SDF): CIFS-MODE-1100SDF
7859 6137–009 6–99

CIFS$OPENDIR
CIFS$OPENDIR
Application
Use the cifs$opendir service subprogram to open a directory stream, making it
accessible to the calling process at the first directory entry. You must first open a
directory stream before doing anything with it.
See cifs$closedir for closing an open directory, cifs$readdir for reading the next directory
entry, and cifs$rewinddir for repositioning the stream at its beginning.
Synopsis
CALL "cifs$opendir" USING dirname, cifs-dir, cifs-status.
Description
The cifs$opendir service subprogram opens a directory stream and positions the stream
to the first directory entry, where dirname identifies the directory to open.
dirname
cifs-dir
is a nul-terminated character string that contains the directory name to open.
is a 2-word (S1(72) BINARY-1) data item into which the directory stream is returned.
Use the COBOL COPY PROC CIFS-DIR for the declaration of this variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$opendir service subprogram completes successfully, it returns an identifier for
the directory stream into the cifs-dir argument. Otherwise, cifs$opendir sets cifs-status
to identify the specific error that was encountered.
Error Codes
If any of the following conditions occurs, the cifs$opendir service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EACCES One of the following errors occurred:
• Search permission is denied for a component of the path name
prefix of dirname.
• Read permission is denied for the directory itself.
6–100 7859 6137–009

CIFS-EFAULT dirname is not a valid name.
CIFS-EIO An I/O error occurred on a directory in the path name.
CIFS$OPENDIR
CIFS-EMFILE The calling process would exceed the maximum number of file
descriptors allowed.
CIFS-ENOENT One of the following errors occurred:
• The directory does not exist.
• dirname is an empty string.
CIFS-ENOMEM Memory could not be allocated for the cifs-dir object.
CIFS-ENOTDIR A component of dirname is not a directory.
7859 6137–009 6–101

CIFS$PACK
CIFS$PACK
Application
Use the CIFS$PACK service subprogram to pack the underlying OS 2200 program files
of CIFS directories.
Synopsis
CALL "CIFS$PACK" USING path, cifs-status.
Description
The CIFS$PACK service subprogram packs the underlying OS 2200 program file of a
CIFS file or directory. This recovers unused table of contents (TOC) space and file text
space resulting from the program file having deleted elements. The action is directly
analogous to a FURPUR @PACK. Any existing relocatable and PROC entry point tables
will be preserved.
Notes:
• The pack operation requires CIFS to have exclusive use (@ASG, AX) of a file while it
is being packed. The program file must not be assigned to any run or name section,
including the run doing the CIFS$PACK service subprogram call. (An EBUSY status is
returned.)
• Unlike the -pr option of the CIFSUT touch command, the CIFS$PACK routine does
not have recursive capabilities. Only one program file can be packed for each call.
The CIFS pack is a safe pack; if the system goes down or an X-keyin to the run is
done during the pack, the contents of the program file are retained, except in
extremely rare circumstances.
path
is a nul terminated ASCII character string for a CIFS file or directory whose
underlying program file you wish to pack.
cifs-status
is a 1-word (1(36) BINARY-1) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
CIFS$PACK returns a zero value into the cifs-status parameter if any of the following
conditions are true:
• If it can pack the underlying program file.
• If the file is already packed.
• If it is not able to pack productively.
• If there is no underlying program file.
If there is an error, then cifs-status is set to an appropriate value. A text version of the
status can be displayed by calling the CIFS$PERROR service subprogram, passing the
status to it.
6–102 7859 6137–009

Error Codes
CIFS$PACK
The following are the possible cifs-status values on an error return. These values are
given in the CIFS-API COBOL PROC in element SYS$LIB$*CIFS$LIB.CIFS-DEF:
CIFS-EACCES Access to a file or directory is denied.
CIFS-EFAULT The path pointer caused a fault in CIFS, an
IGDM.
CIFS-ENAMETOOLONG The path name length is too long.
CIFS-ENOENT The named file or directory does not exist or
CIFS could not assign the program file.
CIFS-ENOTDIR A component of the path prefix is not a
directory.
CIFS-EPERM Access to a file or directory is denied.
CIFS-EBUSY The program file is rolled-out or assigned to
someone else CIFS requires exclusive access
to the file.
CIFS-ENONMEM Buffer space is unavailable.
CIFS-EIO An IO error occurred on the backing program
file.
CIFS-E1100CORRUPT A basic error in the program file, such as text
for elements being out of order.
CIFS-E1100INTERNAL An internal error has occurred in CIFS.
7859 6137–009 6–103

CIFS$PERROR
CIFS$PERROR
Application
Use the cifs$perror service subprogram to print a message corresponding to an error
that occurred.
Synopsis
CALL "cifs$perror" USING cifs-status [, msg-str].
Description
The cifs$perror service subprogram associates the error number in cifs-status with an
error message and writes a line to the standard error file, where a line is the message
followed by a newline (line feed) character.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
msg-str
is a character string that can be used to add user information to the error message.
The argument msg-str is a character string specified to precede the message. If
msg-str is present, cifs$perror writes the following sequence before writing the
message:
The string contained in msg-str
A colon and a space
The contents of the error message strings are the same as those returned by a call
to cifs$strerror with the argument errnum set to the value in cifs-status.
Return Values
The cifs$perror service subprogram returns no value.
6–104 7859 6137–009

CIFS$PIPE
Application
CIFS$PIPE
Use the cifs$pipe service subprogram to create a pipe to transmit data between
processes. Pipes are temporary entities that help processes communicate with each
other. Pipes have a “read end” and a “write end,” which are located by file descriptors
returned by cifs$pipe. When you use a pipe, one process writes data to it and another
process reads the data on a first-in-first-out (FIFO) basis; or one process can pipe data to
itself.
The cifs$pipe service subprogram also initializes the CIFS-OFLAG-NONBLOCK flags as
clear; (see the cifs$open service subprogram) for both file descriptors. You can set these
flags with the cifs$fcntl service subprogram (see the cifs$fcntl service subprogram). See
“Redirecting Standard Files to Pipes” for information on using pipes.
Synopsis
CALL "cifs$pipe" USING fd-pair, cifs-status.
Description
The cifs$pipe service subprogram creates a pipe and returns its file descriptors in the fdpair
group item where:
fd-pair
is a 2-group data item defined as follows:
01 fd-pair
02 fildes0 pic S1(36) BINARY-1.
02 fildes1 pic S1(36) BINARY-1.
where
fildes0 is the file descriptor for the read end of the pipe.
fildes1 is the file descriptor for the write end of the pipe.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
7859 6137–009 6–105

CIFS$PIPE
Return Values
If the cifs$pipe service subprogram completes successfully, it does the following:
• Initializes the last accessed time, created time, and last modified time fields of the
pipe
• Returns 0 in cifs-status
Otherwise, cifs$pipe sets cifs-status to identify the specific error that was encountered.
Error Codes
If any of the following conditions occurs, the cifs$pipe service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EMFILE The calling process would exceed the maximum number of
file descriptors allowed.
Redirecting Standard Files to Pipes
Using Standard Files
To agree on the file descriptors for a pipe, programs follow the convention of using the C
standard files to correspond to the pipe's file descriptors, as follows:
C Standard File
COBOL Program
Name
Standard input file (stdin) CIFS-STDIN-FD 0
Standard output file
(stdout)
CIFS-STDOUT-FD 1
Standard error file (stderr) CIFS-STDERR-FD 2
Redirecting Standard Files
File
Descriptor
In your program, you can redirect the standard files to one end of a pipe. For example, to
redirect CIFS-STDOUT-FD to the write end of a pipe, do the following procedure:
1. Close CIFS-STDOUT-FD, making its file descriptor available for reuse.
2. Duplicate the write end of the pipe. The kernel always chooses the lowest available
number for a new file descriptor, which is the one previously assigned to
CIFS-STDOUT-FD.
3. Close the original write end of the pipe, leaving CIFS-STDOUT-FD as the write end.
6–106 7859 6137–009

CIFS$PRINTF
Application
CIFS$PRINTF
Use the cifs$printf service subprogram to write formatted output to the standard output.
Synopsis
CALL "cifs$printf" USING chars-out, format, [item...].
Description
The cifs$printf service subprogram is equivalent to calling cifs$fprintf using CIFS-
STDOUT-FILE as the file, as follows:
call "cifs$fprintf" using chars-out, cifs-stdout-file, format, ... .
chars-out
format
item
is a 1-word ( S1(36) BINARY-1 ) data item that contains the number of bytes written
out.
is an alphanumeric data item that controls the output by specifying how subsequent
arguments are converted before being output. See cifs$fprintf for a description of
the format argument.
is an alphanumeric data item that contains the data to be printed.
Return Values
If it completes successfully, the cifs$printf service subprogram returns the number of
characters transmitted in the chars-out parameter. Otherwise, cifs$printf returns a
negative value in the chars-out parameter.
7859 6137–009 6–107

CIFS$PUTC
CIFS$PUTC
Application
Use the cifs$putc service subprogram to write characters to an output stream.
Synopsis
CALL "cifs$putc" USING char, cifs-file, cifs-status.
Description
The cifs$putc service subprogram is equivalent to cifs$fputc.
char
cifs-file
is a 1-byte field used to hold the character to be placed into the output stream.
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$putc service subprogram completes successfully, it returns 0 in cifs-status.
Otherwise, cifs$putc sets cifs-status to identify the specific error that was encountered.
6–108 7859 6137–009

CIFS$PUTCHAR
Application
CIFS$PUTCHAR
Use the cifs$putchar service subprogram to write a character to standard output.
Synopsis
CALL "cifs$putchar" USING char, cifs-status.
Description
The cifs$putchar service subprogram is equivalent to calling cifs$putc with the second
argument (cifs-file) set to standard output.
char
is a 1-byte field used to hold the character to be placed into the standard output
stream.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$putchar service subprogram completes successfully, it returns 0 in cifs-status.
Otherwise, cifs$putchar sets cifs-status to identify the specific error that was
encountered.
7859 6137–009 6–109

CIFS$PUTS
CIFS$PUTS
Application
Use the cifs$puts service subprogram to write a string of characters to standard output.
Synopsis
CALL "cifs$puts" USING string, cifs-status.
Description
The cifs$puts service subprogram writes the string contained in the string argument to
the standard output stream, appending a newline (line feed) character to the output. The
nul character terminating the string is not written.
string
is an alphanumeric data item that contains the characters to be placed into the
standard output stream.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$puts service subprogram completes successfully, it returns 0 in cifs-status.
Otherwise, cifs$puts sets cifs-status to identify the specific error that was encountered.
6–110 7859 6137–009

CIFS$READ
Application
CIFS$READ
Use the cifs$read service subprogram to read data from a file at the current read/write
position. Use the cifs$lseek service subprogram to reposition the read/write offset, if
necessary. See the following subsections for more information: “Determining the
Number of Bytes Read,” “Starting Position for Different File Types,” and “Reading
Different File Types.”
Synopsis
CALL "cifs$read" USING fildes, buf, bytes-to-read, bytes-read, cifs-status.
Description
The cif$read service subprogram reads data from a file into a buffer, where:
fildes
buf
is a 1-word (S1(36) BINARY-1) data item which contains the file description of the file
to be read.
is an alphanumeric data item that receives the data as it is read.
bytes-to-read
is a 1-word ( 1(36) BINARY-1 ) data item that is the number of bytes to be read,
which is limited by the size of a data bank.
bytes-read
is a 1-word ( 1(36) BINARY-1 ) data item that is set to the actual number of bytes
read.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$read service subprogram completes successfully, it does the following:
• Updates the last accessed time field of the file (see the cifs$fstat and cifs$stat
service subprograms), if it reads any bytes
• Increments the read/write offset by the number of bytes actually read
7859 6137–009 6–111

CIFS$READ
• Returns the number of bytes actually read and placed into the buffer into the bytesread
parameter
• Return 0 in cifs-status
Otherwise, cifs$read sets cifs-status to identify the specific error that was encountered.
Error Codes
If any of the following conditions occurs, the cifs$read service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EAGAIN The file descriptor's CIFS-OFLAG-NONBLOCK flag is set and no data is
available.
CIFS-EBADF fildes is not a valid file descriptor open for reading.
CIFS-EFAULT One of the following errors occurred:
• buf is invalid, and bytes-to-read is greater than 0.
• buf is valid, but (buf + (bytes-to-read - 1)) points to an invalid
address.
CIFS-EIO An I/O error occurred during processing of the request.
Determining the Number of Bytes Read
The cifs$read service subprogram returns the number of bytes actually read and stored
in the buffer (bytes-read), which is never greater than bytes-to-read. The following
paragraphs relate this return value to the input value of bytes-to-read.
bytes-read = bytes-to-read
The cifs$read service subprogram read and stored the exact number of bytes requested.
bytes-read < bytes-to-read
The value returned is less than bytes-to-read if one of the following statements is true:
• Fewer than bytes-to-read bytes remain between the read/write offset and the end of
the file.
• The file is a pipe or FIFO that has fewer than bytes-to-read bytes immediately
available for reading.
bytes-read = 0
The value returned is 0 if one of the following statements is true:
• The value of bytes-to-read is 0; the service subprogram has no other effects.
• The value of bytes-to-read is not 0, but the read/write offset is at the end of file
(EOF).
6–112 7859 6137–009

Starting Position for Different File Types
CIFS$READ
The file type determines which byte in the file is the first to be read, as shown in the
following paragraphs.
Regular Files
The cifs$read service subprogram starts at the position given by the read/write offset
associated with the open file description corresponding to fildes. Before returning,
cifs$read increases the read/write offset by the number of bytes read.
Pipes and FIFO Files
The cifs$read service subprogram starts at the current position associated with the file
corresponding to fildes. The value of the read/write offset has no meaning for these file
types.
If the starting position is at or beyond the current end of file (EOF), the service
subprogram returns 0 and stores nothing into the buffer. Subsequent read operations
attempt to read from the device again, unless EOF is a hard EOF mark on standard input.
In this case, all subsequent read operations return 0 and store no data into the buffer.
Reading Different File Types
The file type determines the behavior of the cifs$read service subprogram, as shown in
the following paragraphs.
Empty Pipe or FIFO File
The cifs$read service subprogram performs as follows:
• If no process has the pipe or FIFO file open for writing, cifs$read returns 0 to
indicate the end of the file.
• If some process has the pipe or FIFO file open for writing and the
CIFS-OFLAG-NONBLOCK flag for the open file description corresponding to fildes is
set (see the cifs$open and cifs$fcntl service subprograms), cifs$read returns and
sets cifs-status to the value of CIFS-EAGAIN.
• If some process has the pipe or FIFO file open for writing and the
CIFS-OFLAG-NONBLOCK flag is clear, cifs$read waits until some data is written or
the pipe or FIFO file is closed by all processes that have the pipe or FIFO file open
for writing.
CIFS-MODE-1100BIN File Created Outside of CIFS
These files can contain areas of unwritten data that are indistinguishable from valid data.
Reading these areas results in bytes with indeterminate values. A process must never
assume these areas are zero-filled.
7859 6137–009 6–113

CIFS$READ
CIFS-MODE-1100SDF File
The cifs$read service subprogram performs as follows:
• Translates Fieldata images to ASCII
• Removes all SDF attributes from the text returned, so the process cannot use this
attribute to read SDF line numbers
6–114 7859 6137–009

CIFS$READDIR
Application
CIFS$READDIR
Use the cifs$readdir service subprogram to read the current entry in a directory stream
(that is, the entry at the current position); cifs$readdir then positions the directory stream
at the next entry. Before reading a directory stream, you must open it.
You can distinguish the end of the directory from error cases; see “Finding the End of
the Directory” in this subsection.
See cifs$opendir for opening a directory stream, cifs$closedir for closing an open
directory, and cifs$rewinddir for repositioning a directory stream at its beginning.
Synopsis
CALL "cifs$readdir" USING cifs-dir, entry-ino, entry-name, max-len,
true-len, cifs-status.
Description
The cifs$readdir service subprogram reads the next entry in a directory stream, where
cifs-dir is a directory stream from which to read the directory entry. The directory stream
must have been opened previously by cifs$opendir.
cifs-dir
is a 2-word (S1(72) BINARY-1) data item which contains the directory stream from
which to read. Use the COBOL COPY PROC CIFS-DIR for the declaration of this
variable.
entry-ino
is a 1-word ( S1(36) BINARY-1 ) data item that corresponds to a valid file serial
number.
entry-name
max-len
is an alphanumeric data item into which the directory name is placed.
is 1-word ( 1(36) BINARY-1 ) data item that contains the maximum length of the
entry name.
true-len
is 1-word ( 1(36) BINARY-1 ) data item that contains the actual length of the entry
name.
7859 6137–009 6–115

CIFS$READDIR
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Calling cifs$readdir Repeatedly
If a process opens a directory and then repeatedly calls cifs$readdir on the directory
stream, cifs$readdir returns one entry for each file continuously in the directory from the
time of the cifs$opendir call. This includes one entry for the dot file (entry-name is “ . “)
and one entry for the dot-dot file (entry-name is “ .. “).
Every time cifs$readdir reads the same directory stream; it overwrites the previous
directory entry returned.
Multiple Directory Streams
Performing cifs$readdir on one directory stream never interferes with entries in other
directory streams.
Finding the End of the Directory
Use the following procedure to distinguish the end of the directory from error cases:
1. Set cifs-status to 0.
2. Call cifs$readdir.
3. Check the value of cifs-status if cifs$readdir returns a true-len less than or equal to 0.
• If cifs-status equals 0, cifs$readdir reached the end of the directory.
• If cifs-status does not equal 0, cifs$readdir returned an error.
Return Values
If the cifs$readdir service subprogram completes successfully, it does the following:
• Updates the last accessed time field of the directory each time the directory is
actually read. The service subprogram can store several entries for one call in the
buffer and not do actual read operations for other calls. The update to last accessed
time field is not written to nonvolatile storage until the directory stream is closed by
one of the following events:
− A call to cifs$closedir
− Process termination
• Returns one of the following:
− The name of a directory entry
− A true-len less than or equal to 0, if no more entries exist. In this case,
cifs$readdir does not change the value of cifs-status.
Otherwise, cifs$readdir sets cifs-status to identify the specific error that was
encountered.
6–116 7859 6137–009

Error Codes
CIFS$READDIR
If any of the following conditions occurs, the cifs$readdir service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EBADF cifs-dir does not contain a valid directory stream.
CIFS-EFAULT cifs-dir is not valid.
7859 6137–009 6–117

CIFS$REMOVE
CIFS$REMOVE
Application
Use the cifs$remove service subprogram to remove any type of named file, including an
empty directory.
Synopsis
CALL "cifs$remove" USING path, cifs-status.
Description
The cifs$remove service subprogram causes a file or directory to be removed, where
path contains the name of the file or directory. If the file is open, any subsequent input or
output operations to the file do not fail. Subsequent attempts to open the file fail unless
the file is re-created.
path
is a nul-terminated character string that contains the path name of the file or
directory to remove.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$remove service subprogram completes successfully, it returns a value of 0 in
the cifs-status parameter. Otherwise, cifs$remove sets cifs-status to identify the specific
error that was encountered.
6–118 7859 6137–009

CIFS$RENAME
Application
CIFS$RENAME
Use the cifs$rename service subprogram to change the path name of an existing file.
The new entry can be in the same directory or in different directories. If it is in the same
directory, the file name must be unique.
If the new path name also resolves to an existing file, the link to that file is removed
before the name is reused; this possibly removes the unlinked file from the file system
(see “General Rules for Renaming Files” in this subsection).
See the cifs$link service subprogram for creating new directory entries for a file and the
cifs$unlink service subprogram for removing file links.
Synopsis
CALL "cifs$rename" USING old-path, new-path, cifs-status.
Description
The cifs$rename service subprogram changes the path name of an existing file, where:
old-path
is an alphanumeric variable that contains the name of the file to rename.
new-path
is an alphanumeric variable that contains the new path name to attach to the file.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Neither old-path nor new-path can refer to a character file.
Example 1
The following example illustrates a simple rename operation within a directory:
7859 6137–009 6–119

CIFS$RENAME
Example 2
The following diagram illustrates a simple rename operation between two directories:
Example 3
The following diagram illustrates a complex rename operation, where the new path
name resolves to an existing file. The existing link to /dir_2/file_2 is removed first; then
the rename operation is similar to example 2, with a different file name.
6–120 7859 6137–009

General Rules for Renaming Files
The following general rules apply to renaming files:
• If the old and new path names resolve to the same file, cifs$rename returns
successfully without making any changes.
CIFS$RENAME
• If the old and new path names do not resolve to the same file, the following rules
apply:
− The process must have write-access permission to the directory containing the
link to the old file.
− The process must have write-access permission to the directory that contains
the new link.
• If the new path name resolves to an existing file, the file is unlinked from the last
directory in the new path name before its name is reused for old-path. If no other
links to the file exist, the file is removed from the file hierarchy as soon as all
references to it are closed (see the cifs$close service subprogram). The dot and
dot-dot entries cannot be manipulated by the cifs$rename and cifs$rmdir service
subprograms. These entries are automatically deleted from a directory when its last
link is removed.
Special Rules for Renaming a Directory
The following special rules apply to renaming a directory:
• The process must have write-access permission to the old directory.
• If the new path name exists in the file system, it must resolve to a directory.
• If the new path name resolves to an existing directory, the process must have writeaccess
permission to it and it must be empty.
• The old path name must not resolve to a directory contained in the new path name.
Special Rules for Renaming a Nondirectory File
The new path name must not resolve to an existing directory.
Return Values
If the cifs$rename service subprogram completes successfully, it does the following:
• Updates the last accessed time and last modified fields of the parent directory of
each file
• Returns 0 in cifs-status
Otherwise, cifs$rename sets cifs-status to identify the specific error that was
encountered.
7859 6137–009 6–121

CIFS$RENAME
Error Codes
If any of the following conditions occurs, the cifs$rename service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EACCES Any of the following errors occurred:
• The calling process is denied search permission to a
component of either path name.
• The calling process is denied write permission to directories
containing either old-path or new-path.
• The calling process is denied write permission to directories
to which either old -path or new-path point.
CIFS-EEXIST The link named by new-path is a directory with entries other than
dot and dot-dot; that is, it is not an empty directory.
CIFS-EFAULT The value specified by old-path or new-path is invalid.
CIFS-EINVAL One of the following errors occurred:
• The directory path name in new-path contains the directory
name in old-path.
• The last component of either old-path or new-path is either
dot or dot-dot.
CIFS-EISDIR The path name in new-path resolves to a directory, and the path
name in old-path resolves to a file that is not a directory.
CIFS-ENOENT Either of the following errors occurred:
• The link named by old-path does not exist.
• Either old-path or new-path points to an empty string.
CIFS-ENOSPC The parent directory of new-path has too many entries.
CIFS-ENOTDIR Either of the following errors occurred:
• A component of either path name prefix is not a directory.
• old-path names a directory, and new-path names a file that is
not a directory.
6–122 7859 6137–009

CIFS$REWIND
Application
CIFS$REWIND
Use the cifs$rewind service subprogram to set the file position indicator to the beginning
of a stream.
Synopsis
CALL "cifs$rewind" cifs-file, cifs-status.
Description
The cifs$rewind service subprogram is equivalent to the following call to cifs$fseek:
call "cifs$fseek" using cifs-file, 0, 0, cifs-status.
cifs-file
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$rewind service subprogram completes successfully, it returns 0 in cifs-status.
Otherwise, cifs$rewind sets cifs-status to identify the specific error that was
encountered.
7859 6137–009 6–123

CIFS$REWINDDIR
CIFS$REWINDDIR
Application
Use the cifs$rewinddir service subprogram to reposition a directory stream at its
beginning. The cifs$rewinddir service subprogram updates the directory stream to
reflect the current state of the directory, making visible any directory entries added since
the directory stream was opened.
You can distinguish a successful call to cifs$rewinddir from error cases; see “Detecting
Error Cases” in this subsection.
See cifs$opendir for opening a directory, cifs$closedir for closing an open directory, and
cifs$readdir for reading the next directory entry.
Synopsis
CALL "cifs$rewinddir" USING cifs-dir, cifs-status.
Description
The cifs$rewinddir service subprogram resets the position of the directory stream to its
beginning, where cifs-dir is the directory stream to rewind. The directory stream must
have been opened previously by cifs$opendir.
cifs-dir
is a 2-word (S1(72) BINARY-1) data item into which the directory stream is returned.
Use the COBOL COPY PROC CIFS-DIR for the declaration of this variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Detecting Error Cases
Use the following procedure to detect error cases:
1. Set cifs-status to 0.
2. Call cifs$rewinddir.
3. Check the value of cifs-status.
• If cifs-status equals 0, cifs$rewinddir did not detect an error.
• If cifs-status does not equal 0, cifs$rewinddir detected an error.
Return Values
The cifs$rewinddir service subprogram returns no value.
6–124 7859 6137–009

Error Codes
CIFS$REWINDDIR
If any of the following conditions occurs, the cifs$rewinddir service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EBADF cifs-dir does not contain a valid directory object representing
an open directory stream.
CIFS-EFAULT cifs-dir is not a valid value.
7859 6137–009 6–125

CIFS$RMDIR
CIFS$RMDIR
Application
Use the cifs$rmdir service subprogram to remove an empty directory from the file
system.
Synopsis
CALL "cifs$rmdir" USING path, cifs-status.
Description
The cifs$rmdir service subprogram removes an empty directory and its dot and dot-dot
entries, where path contains the value of the directory to remove. The directory cannot
be the system root directory.
If any process has the directory open or has an open directory stream (see the
cifs$opendir service subprogram) when cifs$rmdir removes the last link, the directory
contents remain accessible until all references are closed.
path
is a nul-terminated character string that contains the path name of the directory to be
removed.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$rmdir service subprogram completes successfully, it does the following:
• Updates the last accessed and last modified fields of the parent directory
• Returns 0 in the cifs-status field
Otherwise, cifs$rmdir sets cifs-status to identify the specific error that was encountered.
Error Codes
If any of the following conditions occurs, the cifs$rmdir service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EACCES Any of the following errors occurred:
• The calling process is denied search permission to a
component of the path name.
• The calling process is denied write permission to the parent
directory of the directory to be removed.
6–126 7859 6137–009

CIFS-EEXIST path names a directory that is not empty.
CIFS-EFAULT The value specified by path is invalid.
CIFS$RMDIR
CIFS-EINVAL The calling process is requesting that the dot or dot-dot entry in a
directory be removed.
CIFS-EIO An I/O error prevented the completion of the service subprogram.
CIFS-ENOENT Either of the following errors occurred:
• The directory does not exist.
• path contains an empty string.
CIFS-ENOTDIR A component of the path name is not a directory.
7859 6137–009 6–127

CIFS$SCANF
CIFS$SCANF
Application
Use the cifs$scanf service subprogram to read formatted input from the standard input.
Synopsis
CALL "cifs$scanf" USING items-scanned, format, [item...].
Description
The cifs$scanf service subprogram is equivalent to calling cifs$fscanf using CIFS-STDIN-
FILE as the file, as follows:
call "cifs$fscanf" using items-scanned, cifs-stdin-file, format, ... .
items-scanned
format
item
is a 1-word ( S1(36) BINARY-1 ) data item that contains the number of assigned input
items.
See cifs$fscanf for a description of the format argument.
is an alphanumeric data item that contains the data to be scanned.
Return Values
If it completes successfully, the cifs$scanf service subprogram returns either of the
following:
• The number of assigned input items, which can be 0 in the event of an early conflict
between an input character and the format
• EOF, if it encounters end of file before the first conflict or conversion
Otherwise, cifs$scanf returns when it encounters the end of the format string.
6–128 7859 6137–009

CIFS$SHARE
Application
CIFS$SHARE
Use the cifs$share service subprogram to specify the network-visible name for the given
directory. The share name cannot be more than 31 characters long.
Notes:
• There is no POSIX equivalent to cifs$share.
• Many network clients cannot access share names with more than 12 characters.
Synopsis
CALL "cifs$share" USING path, sharename, cifs-status.
Description
The path parameter must specify a directory to which the caller has full access. The
sharename parameter must be a string of 31 or fewer characters from the printable
ASCII set, not including the slash (/), back slash (\), question mark (?), asterisk (*), or
comma (,) characters. If the sharename is an empty string, the call removes network
visibility for the directory. If the sharename string contains invalid characters, the
network visibility for the directory is unchanged. Otherwise, the sharename becomes the
network name for the directory, replacing any existing name.
path
is a nul-terminated character string that contains the path name of the file.
sharename
is a nul-terminated character string that contains the share name to be established
for the file.
cifs-status
is a 1-word (1(36) BINARY-1) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$share service subprogram completes successfully, it returns a value of 0 in
the cifs-status parameter. Otherwise, cifs$share sets cifs-status to identify the specific
error that was encountered.
7859 6137–009 6–129

CIFS$SPRINTF
CIFS$SPRINTF
Application
Use the cifs$sprintf service subprogram to write formatted output to a character array.
Synopsis
CALL "cifs$sprintf" USING chars-out, dest-string, format, [item...].
Description
The cifs$sprintf service subprogram is equivalent to cifs$fprintf, except that the
argument dest-string specifies an alphanumeric data item to which the generated output
is written (rather than to a stream). A nul character is appended after the characters are
written, but the nul character is not counted as part of the returned sum.
chars-out
is a 1-word ( S1(36) BINARY-1 ) data item that contains the number of bytes written
out.
dest-string
format
item
is an alphanumeric data item to which the output is written.
is an alphanumeric data item that controls the output by specifying how subsequent
arguments are converted before they are output. See the cifs$fprintf for further
details about this parameter.
is an alphanumeric data item that contains the data to be printed.
Return Values
The cifs$sprintf service subprogram returns the number of characters written to the
destination string, not counting the terminating nul character.
6–130 7859 6137–009

CIFS$SSCANF
Application
Use the cifs$sscanf service subprogram to read formatted input from a string.
Synopsis
CIFS$SSCANF
CALL "cifs$sscanf" USING items-scanned, scan-string, format, [item...].
Description
The cifs$sscanf service subprogram is equivalent to cifs$fscanf, except that the
argument scan-string specifies a string from which the input is read (rather than from a
stream). Reaching the end of the string is equivalent to encountering end of file for the
cifs$fscanf service subprogram.
items-scanned
is a 1-word ( S1(36) BINARY-1 ) data item that contains the number of assigned input
items.
scan-string
format
item
is an alphanumeric data item from which the input is read.
controls the input by specifying how input text is converted for assignment.
Subsequent arguments are objects that receive the converted input. If there are
insufficient arguments for the format, a signal is generated. If the program recovers
from the signal, it treats it as if an asterisk flag were specified. If the format is
exhausted while arguments remain, cifs$fscanf evaluates the excess arguments but
otherwise ignores them.
is an alphanumeric data item that contains the data to be scanned.
Return Values
If it completes successfully, the cifs$sscanf service subprogram returns the number of
assigned input items (which can be 0 in the event of an early conflict between an input
character and the format) into the items-scanned argument. Otherwise, cifs$sscanf
returns when it encounters the end of the format string.
7859 6137–009 6–131

CIFS$STAT
CIFS$STAT
Application
Use the cifs$stat service subprogram to retrieve information about a named file. In
particular, you can get information about the file mode, security attributes, file size, and
access times.
The cifs$stat service subprogram uses a path name to identify the file. See the cifs$fstat
service subprogram for a similar service subprogram that uses a file descriptor.
Synopsis
CALL "cifs$stat" USING path, cifs-stat, cifs-status.
Description
The cifs$stat service subprogram returns information about a file into the cifs-stat
structure, where:
path
cifs-stat
is a nul-terminated character string that contains the path name of the file.
is a group item in which cifs$fstat returns the file information. Use the COBOL
COPY PROC CIFS-STAT for the declaration of this variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
The calling process does not need read, write, or execute permission for the file; but it
must have search permission for all directories in the path name leading to the file.
Refer to the cifs$fstat service subprogram for a table that describes the cifs-stat
structure.
Return Values
If the cifs$stat service subprogram completes successfully, it returns 0 in cifs-status.
Otherwise, cifs$stat sets cifs-status to identify the specific error that was encountered.
6–132 7859 6137–009

Error Codes
CIFS$STAT
If any of the following conditions occurs, the cifs$stat service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EACCES The calling process is denied search permission to a directory in
the path name.
CIFS-EFAULT The value specified by path is invalid.
CIFS-ENOENT Either of the following errors occurred:
• The file or directory does not exist.
• path contains an empty string.
CIFS-ENOTDIR A component of the path name prefix is not a directory.
7859 6137–009 6–133

CIFS$STDERR
CIFS$STDERR
Application
Use the cifs$stderr service subprogram to set the opaque data item that describes an
open instance of the standard error file.
Synopsis
CALL "cifs$stderr" USING cifs-file.
Description
The cifs$stderr service subprogram sets the argument cifs-file to an open instance of the
standard error file.
cifs-file
is an opaque data item that describes an open instance of a file. It is a 2-word (S1(72)
BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the declaration of
this variable.
Return Values
The value of the parameter cifs-file is set to a value that describes an open instance of a
file.
6–134 7859 6137–009

CIFS$STDIN
Application
CIFS$STDIN
Use the cifs$stdin service subprogram to set the opaque data item that describes an
open instance of the standard input file.
Synopsis
CALL "cifs$stdin" USING cifs-file.
Description
The cifs$stdin service subprogram sets the argument cifs-file to an open instance of the
standard input file.
cifs-file
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
Return Values
The value of the parameter cifs-file is set to a value that describes an open instance of a
file.
7859 6137–009 6–135

CIFS$STDOUT
CIFS$STDOUT
Application
Use the cifs$stdout service subprogram to set the opaque data item that describes an
open instance of the standard output file.
Synopsis
CALL "cifs$stdout" USING cifs-file.
Description
The cifs$stdout service subprogram sets the argument cifs-file to an open instance of
the standard output file.
cifs-file
is an opaque data item that describes an open instance of a file. It is a 2-word
(S1(72) BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the
declaration of this variable.
Return Values
The value of the parameter cifs-file is set to a value that describes an open instance of a
file.
6–136 7859 6137–009

CIFS$STRERROR
Application
CIFS$STRERROR
Use the cifs$strerror service subprogram to retrieve the error message associated with a
particular error number.
Synopsis
CALL "cifs$strerror" USING errnum, message-string [insert-string...].
Description
The cifs$strerror service subprogram retrieves the ELMS text for the specified error
number, errnum, using first the CIFS component, and then the URTS component if the
message does not exist within CIFS. The optional parameters (insert-string) are character
strings that are used as inserts in the error message text.
errnum
is a 1-word ( 9(10) BINARY ) data item that contains the error number of the
message to be retrieved.
message-string
is an alphanumeric character data item into which the retrieved error message can
be returned.
insert-string
is an alphanumeric character data item that contains text to be used as an insert in
the error message.
Return Values
The cifs$strerror service subprogram returns a retrieved message text with any inserts
applied to the message-string parameter. This area is modifiable by the caller and is
overwritten on subsequent calls to cifs$strerror.
7859 6137–009 6–137

CIFS$TMPFILE
CIFS$TMPFILE
Application
Use the cifs$tmpfile service subprogram to create a temporary file for use while a
program executes.
Synopsis
CALL "cifs$tmpfile" USING cifs-file, cifs-status.
Description
The cifs$tmpfile service subprogram creates a temporary file, where cifs-file is an
opaque data item that describes an open instance of a file. The file is opened for update
and automatically removed at program termination.
cifs-file
is a 2-word (S1(72) BINARY-1) data item into which the value of the open instance of
the file is stored. Use the COBOL COPY PROC CIFS-FILE for the declaration of this
variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Default Permissions When Creating a File
If the cifs$tmpfile service subprogram creates a file, it assigns read and write
permissions to the owner, group, and other permission classes by default.
Return Values
The cifs$tmpfile service subprogram returns a value to the stream of the file that it
created in the cifs-file parameter and returns a 0 value in the cifs-status parameter. If the
file cannot be created, cifs$tmpfile sets cifs-status to identify the specific error that was
encountered.
6–138 7859 6137–009

CIFS$TMPNAM
Application
CIFS$TMPNAM
Use the cifs$tmpnam service subprogram to generate a string to use as a file name that
is different from any existing file name.
Synopsis
CALL "cifs$tmpnam" USING name-string, cifs-status.
Description
The cifs$tmpnam service subprogram generates a string that is not the same as the
name of an existing file.
name-string
is an alphanumeric data item that contains the file name returned by the service
subprogram
cifs-status
is a 1-word (1(36) BINARY-1) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
The cifs$tmpnam service subprogram generates a different string each time it is called.
Note: Files created using strings generated by the cifs$tmpnam service subprogram
are temporary only in the sense that their names must not conflict with those generated
by conventional naming rules for the implementation. You must still use the cifs$remove
service subprogram to remove such files when their use is ended and before program
termination.
Return Values
If the cifs$tmpnam service subprogram completes successfully, it returns 0 in cifs-status
and the file name is returned in name-string. Otherwise, cifs$tmpnam sets cifs-status to
identify the specific error that was encountered.
7859 6137–009 6–139

CIFS$TRUNCATE
CIFS$TRUNCATE
Application
Use the cifs$truncate service subprogram to set the end-of-file position for an existing
regular file.
Synopsis
CALL "cifs$truncate" USING path, length, cifs-status.
Description
A regular file whose name is given by path has its size (in bytes) set to length. If the file
was previously longer than the length specified, those bytes are no longer accessible. If
the file was previously shorter than the length specified, bytes between the old end of
file and the specified length are read as zeroes. For cifs$truncate, the caller must have
write access to the file.
For files stored in SDF format, the length value of 34359738367 (defined as INT_MAX in
the limits.h header file) has special meaning. CIFS treats this as an indication that it must
recalculate the actual size of the file when it is next read based on the position of the
EOF record, rather than pad the file with zeroes.
path
length
is a nul-terminated character string that contains the path name of the file.
is a 1-word ( 1(36) BINARY-1 ) data item that contains the length to set the file to.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$truncate service subprogram completes successfully, it returns 0 in
cifs-status. Otherwise, cifs$truncate sets cifs-status to identify the specific error that
was encountered.
6–140 7859 6137–009

CIFS$UMASK
Application
CIFS$UMASK
Use the cifs$umask service subprogram to create the file mode creation mask for the
calling process and save its previous version.
Synopsis
CALL "cifs$umask" USING new-cifs-mode, old-cifs-mode, cifs-status.
Description
The cifs$umask service subprogram sets the file mode creation mask, where
new-cifs-mode contains the value for the mask.
The file mode creation mask is a process attribute that limits the permissions the
process can attach to a file. The mask is a set of attributes corresponding to read, write,
and search/execute permissions for each of the owner, group, and other permission
classes. If an attribute is set in the mask, that permission is denied when files are
created. For example, to prohibit anyone in the group and other permission classes from
writing to a file, set the corresponding attributes in the file mode creation mask before
creating the file.
new-cifs-mode
is a 1-word (1(36) BINARY-1) data item that contains the new settings for the file
permissions. Use the COBOL COPY PROC CIFS-MODE for the declaration of this
variable.
old-cifs-mode
is a 1-word (1(36) BINARY-1) data item that contains the new settings for the file
permissions. Use the COBOL COPY PROC CIFS-MODE for the declaration of this
variable.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Service subprograms that create files request file permissions through a mode argument
in the call statement. However, they first apply the file mode creation mask to turn off
corresponding permissions that are set in the mode argument. For example, if the
attributes for group and other write permissions are set in the file mode creation mask,
those permissions are not set for files created subsequently.
7859 6137–009 6–141

CIFS$UMASK
Setting the File Mode Creation Mask
You can set the file mode creation mask using any of the symbolic constants for the
individual or group permission settings, as follows:
compute cifs-mode-irwxg = cifs-mode-iread + cifs-mode-iwrite.
compute cifs-mode-irwxo = cifs-mode-iread + cifs-mode-iwrite.
call "cifs$umask" using cifs-mode, old-cifs-mode, cifs-status.
The previous code sets the file mode creation mask to contain both of the following:
• Write access by the group class
• Any access by the other class
The mask, then, prohibits those permissions for service subprograms that apply the
mask to the new-cifs-mode argument.
Return Values
The cifs$umask service subprogram returns the previous value of the file mode creation
mask. If the cifs$uname service subprogram completes successfully, it returns 0 in
cifs-status. Otherwise, cifs$umask sets cifs-status to identify the specific error that was
encountered.
6–142 7859 6137–009

CIFS$UNAME
Application
CIFS$UNAME
Use the cifs$uname service subprogram to retrieve version information about the CIFS
subsystem.
Note: There is no POSIX equivalent to cifs$uname.
Synopsis
CALL "cifs$uname" USING cifs-ss-bdi, cifs-ss-name, cifs-status.
Description
The cifs$uname service subprogram returns version information about the CIFS
subsystem. The cifs-ss-bdi parameter receives the bank descriptor index (BDI) of the
subsystem gate bank, in symbolic form. The data item cifs-ss-bdi must be able to hold 8
characters. The cifs-ss-name parameter is filled with the subsystem name, the date and
time of the subsystem construction, and the build number. The cifs-ss-name data item
must be at least 48 characters long.
cifs-ss-bdi
is an alphanumeric data item that contains Bank Descriptor Index (BDI) of the
subsystem gate bank.
cifs-ss-name
is an alphanumeric data item that contains the subsystem name, the date and time
of the subsystem construction, and the build number.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Return Values
If the cifs$uname service subprogram completes successfully, it returns 0 in cifs-status.
Otherwise, cifs$uname sets cifs-status to identify the specific error that was
encountered.
7859 6137–009 6–143

CIFS$UNGETC
CIFS$UNGETC
Application
Use the cifs$ungetc service subprogram to return a character to the input stream,
causing the next read operation to read that character.
Synopsis
CALL "cifs$ungetc" USING prev-char, cifs-file, rtn-char, cifs-status.
Description
The cifs$ungetc service subprogram pushes a character back onto the input stream,
where:
prev-char
cifs-file
is an alphanumeric data item that specifies the character to be returned.
is an opaque data item that describes an open instance of a file. It is a 2-word (S1(72)
BINARY-1) data item. Use the COBOL COPY PROC CIFS-FILE for the declaration of
this variable.
rtn-char
is an alphanumeric data item that contains the character to be returned.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
The character is returned by the next read on that stream, provided no intervening call to
cifs$fseek erases all memory of pushed-back characters.
Notes:
• cifs$ungetc at end of file is legal; it causes cifs$feof to return false until the character
is reread.
• cifs$ungetc does not change the value of the file.
• cifs$ungetc is not allowed for output operations.
Return Values
If it completes successfully, the cifs$ungetc service subprogram returns the character
pushed back to the input stream (rtn-char) and places a 0 in cifs-status. Otherwise,
cifs$ungetc sets cifs-status to identify the specific error that was encountered.
6–144 7859 6137–009

CIFS$UNLINK
Application
CIFS$UNLINK
Use the cifs$unlink service subprogram to remove a link from a named, nondirectory file,
which decreases the file's link count by 1. If the link count becomes 0, cifs$unlink
deletes the file from the file system.
See the cifs$rename service subprogram for changing the name of a file and the
cifs$link service subprogram for creating new directory entries for a file.
Synopsis
CALL "cifs$unlink" USING path, cifs-status.
Description
The cifs$unlink service subprogram removes a link from a file, where path contains the
file link to be removed. Path cannot contain a directory; use cifs$rmdir to remove a
directory.
path
is a nul-terminated character string that contains the path name of the file.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
If a process has the file open when it is being removed, that process can continue to
access the file through the open file descriptor.
Return Values
If the cifs$unlink service subprogram completes successfully, it does the following:
• Updates the cifs-stat-atime and cifs-stat-mtime fields of the parent directory
• Updates the cifs-stat-atime field of the file, if the file's link count is not 0
• Returns 0 in the cifs-status parameter.
Otherwise, cifs$unlink sets cifs-status to identify the specific error that was
encountered.
Error Codes
If any of the following conditions occurs, the cifs$unlink service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
7859 6137–009 6–145

CIFS$UNLINK
CIFS-EACCES Any of the following errors occurred:
• The calling process is denied search permission to a component
of the path name.
• The calling process is denied write permission to the directory
containing the link to be removed.
CIFS-EFAULT The value specified by path is invalid.
CIFS-ENOENT Either of the following errors occurred:
• The file does not exist.
• path contains an empty string.
CIFS-ENOTDIR A component of the path name prefix is not a directory.
6–146 7859 6137–009

CIFS$UTIME
Application
CIFS$UTIME
Use the cifs$utime service subprogram to change the access time and modification time
of a file, using an arbitrary time setting. You can retrieve these values into a CIFS-STAT
data item using the cifs$stat service subprogram.
These times are also changed by service subprograms that perform input and output
operations on the file; check the paragraphs under “Return Values” for each service
subprogram to see which time fields the service subprogram updates, if any.
Privilege Requirement
For a process to change the access time and modification time of a file, one of the
following must be true:
• The process is privileged.
• The effective user ID of the process is equal to the owning user ID of the file.
Synopsis
CALL "cifs$utime" USING path, timbuf, cifs-status.
Description
The cifs$utime service subprogram sets the access time and modification time of a file
to the values in the timbuf parameter, where:
path
timbuf
is a nul-terminated character string that contains the path name of the file.
is a COBOL group item that controls how cifs$utime sets the access time and
modification time. It must be defined as follows:
01 timbuf.
02 actime pic 1(36) binary-1.
02 modtime pic 1(36) binary-1.
cifs$utime sets the access time and modification time of the file to the values in
timbuf if the calling process is allowed to change the times (see “Privilege
Requirement” in this subsection). Whether the process has write permission to the
file is immaterial.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
7859 6137–009 6–147

CIFS$UTIME
The timbuf Data Item
The following table describes the timbuf data item:
Member
Name Description **
actime This value is put into the last accessed field of the file.
modtime This value is put into the last modified field of the file.
** Time values are measured in seconds from 00:00:00 January 1, 1970, local time.
Setting Values in the timbuf Data Item
The following program fragment sets the values in the timbuf data item to May 18, 2004
6:35:15. It then uses these values to update the last accessed and last modified fields
for the file /my_dir/my_file.
01 argument-1.
03 arg1 PIC X(15).
03 filler PIC X value nul.
01 r1 pic 9(10) binary.
01 r2 pic 9(10) binary.
01 r3 pic 9(10) binary.
01 timbuf.
02 actime pic 1(36) binary-1.
02 modtime pic 1(36) binary-1.
...
compute r1 = function integer-of-date(19700101).
compute r2 = function interger-of-date(20040518).
*
* Calculate the number of seconds from 01/01/1970 to 05/18/2004
*
compute r3 = (r2 - r1) * 24 * 60 * 60.
*
* Add the number of seconds from midnight 05/18/2004 to 06:35:15 to
* total
*
compute r3 = r3 + (6 * 60 * 60) + (35 * 60) + 15.
move r3 to actime modtime.
move '/my_dir/my_file' to arg1.
call "CIFS$UTIME" using arg1, timbuf, cifs-status.
if cifs-status NOT = 0
call "CIFS$PERROR" using cifs-status.
Return Values
If the cifs$utime service subprogram completes successfully, it returns a value of 0 in
the cifs-status parameter. Otherwise, cifs$utime sets cifs-status to identify the specific
error that was encountered.
6–148 7859 6137–009

Error Codes
CIFS$UTIME
If any of the following conditions occurs, the cifs$utime service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
EACCES Either of the following errors occurred:
• The calling process is denied search permission on a directory in
the path name.
• timbuf is null, and all of the following are true:
− The effective user ID of the calling process does not match
the user ID of the owner of the file.
− The calling process is denied write permission for the file.
− The process is not privileged.
EFAULT The value specified by path is invalid.
ENOENT Either of the following errors occurred:
• The file does not exist.
• path points to an empty string.
ENOTDIR A component of the path name prefix is not a directory.
EPERM All of the following are true:
• timbuf is not null.
• The effective user ID of the calling process does not match the
file's owner.
• The process is not privileged.
7859 6137–009 6–149

CIFS$WRITE
CIFS$WRITE
Application
Use the cifs$write service subprogram to write data to a file at the current read/write
position. Use the cifs$lseek service subprogram to reposition the read/write offset. See
the following subsections for more information: “Determining the Number of Bytes
Written,”“Starting Position for Different File Types,” “Writing to Different File Types,”
and “Translating Special Characters.”
Synopsis
CALL "cifs$write" USING fildes, buffer, bytes-to-write,
bytes-written, cifs-status.
Description
The cifs$write service subprogram writes data from a buffer to an open file, where:
fildes
buffer
is a 1-word (S1(36) BINARY-1) data item which contains the file description of the file
to be read.
is an alphanumeric data item holding the data to write.
bytes-to-write
is a 1-word (S1(36) BINARY-1) data item that is the number of bytes to write, which
is limited by the size of a data bank.
bytes-written
is a 1-word (1(36) BINARY-1) data item that is set to the actual number of bytes
written.
cifs-status
is a 1-word (1(36) BINARY-1) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
Attempting to Write Beyond the Limits
The cifs$write service subprogram fails if the file position exceeds the maximum size of
the file.
6–150 7859 6137–009

Return Values
CIFS$WRITE
If the cifs$write service subprogram completes successfully, it does the following:
• Updates the last accessed time and last modified time fields (see the cifs$fstat and
cifs$stat service subprograms) of the file, if the service subprogram wrote any bytes
• Returns the number of bytes actually written to the file
• Returns 0 in cifs-status
Otherwise, cifs$write sets cifs-status to identify the specific error that was encountered.
Error Codes
If any of the following conditions occurs, the cifs$write service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-EAGAIN The CIFS-OFLAG-NONBLOCK flag is set, the calling process is
writing to a pipe or FIFO file, and one of the following conditions
occurred:
• The pipe or FIFO file is full.
• The pipe or FIFO file does not have bytes-to-write space
available.
CIFS-EBADF fildes is not a valid file descriptor open for writing.
CIFS-EFAULT One of the following errors occurred:
• buffer points to an invalid address, and bytes-to-write is
greater than 0.
• buffer is valid, but (buffer + (bytes-to-write - 1)) points to an
invalid address.
CIFS-EFBIG The calling process is attempting to write at a starting position
beyond the highest position allowed for the file.
CIFS-EIO A disk error occurred.
CIFS-EPIPE One of the following errors occurred:
• An attempt is made to write to a pipe or FIFO file that is not
open for reading by any process.
• While waiting for room in a pipe, all file descriptors open for
reading the pipe are closed.
7859 6137–009 6–151

CIFS$WRITE
Determining the Number of Bytes Written
The cifs$write service subprogram returns the number of bytes actually written
(bytes-written) from the buffer to the file, which is never greater than bytes-to-write. The
following paragraphs relate this return value to the input value of bytes-to-write.
bytes-written = bytes-to-write > 0
The cifs$write service subprogram wrote and stored the exact number of bytes
requested.
bytes-written < bytes-to-write
The value returned is less than bytes-to-write if one of the following statements is true:
• Fewer than bytes-to-write bytes can be written without exceeding the maximum
size of the file.
• The file is a pipe or FIFO that has fewer than bytes-to-write bytes immediately
available for writing.
bytes-written = 0
The value returned is 0 if the value of bytes-to-write is 0.
Starting Position for Different File Types
The file type determines the first byte in the file to be written, as shown in the following
paragraphs.
Regular Files
The service subprogram starts at the current position of the read/write offset associated
with the open file description corresponding to fildes. Before returning, cifs$write
increases the read/write offset by the number of bytes written to the file.
If the CIFS-OFLAG-APPEND flag associated with the open file description corresponding
to fildes is set, the read/write offset is set to the end of the file immediately before each
write operation.
Writing data to locations beyond the end of the file causes the file to expand
automatically.
Pipes and FIFO Files
The service subprogram starts at the current position associated with the file
corresponding to fildes.
6–152 7859 6137–009

Writing to Different File Types
CIFS$WRITE
The file type determines the behavior of the cifs$write service subprogram, as shown in
the following paragraphs.
Regular Files
Data accumulates in buffers, which are written to nonvolatile storage when all processes
have closed the file (see the cifs$close service subprogram).
Pipes and FIFO Files
Pipes and FIFO files have a storage capacity of 7,168 bytes to store data until it is read.
No data is written to nonvolatile storage.
If the pipe or FIFO file is full, a process must wait for data to be read from it before
writing data to it. The CIFS-OFLAG-NONBLOCK flag associated with the open file
description corresponding to fildes (see the cifs$open and cifs$fcntl service
subprograms) determines the behavior of cifs$write for pipes and FIFO files, as follows:
CIFS-OFLAG-
NONBLOCK
Set cifs$write does one of
the following:
Value of bytes-to-write
≤ 7,168* > 7,168**
• Successfully
writes all the data
• Returns an error
condition if there
is not room for all
the data
Clear cifs$write waits for
room in the file for all
the data
cifs$write does one of the
following:
• Writes as much data as
immediately possible and
returns the number of
bytes written. (If the pipe
or FIFO file is empty,
cifs$write transfers 7,168
bytes.)
• Returns an error condition
if the pipe or FIFO file is
full.
cifs$write transfers data to the
pipe, not returning until one of
the following occurs:
• The bytes-to-write bytes
are written.
• If the pipe is empty,
cifs$write transfers at
least 7,168 bytes before
returning.
* If a process writes 7,168 bytes or less to a pipe, the data in the pipe is guaranteed to be
contiguous.
** If a process writes more than 7,168 bytes to a pipe, the data can alternate with data from
other processes writing to the pipe.
7859 6137–009 6–153

CIFS$WRITE
The call returns an error condition if one of the following occurs:
• No process has the pipe open for reading.
• While cifs$write is waiting for data to be read from a pipe, all file descriptors open
for reading the pipe are closed.
Translating Special Characters
The newline (line feed) characters have special meaning for a write operation when fildes
refers to CIFS-STDOUT-FD, CIFS-STDERR-FD, or an SDF file. The newline character
causes cifs$write to write the characters preceding the newline since the end of the last
line as either of the following:
• One line to CIFS-STDOUT-FD or CIFS-STDERR-FD
• One image to the SDF file
6–154 7859 6137–009

CIFS$XLATE
Application
CIFS$XLATE
Use the cifs$xlate service subprogram to set or retrieve the translation attributes for a
directory.
Note: There is no POSIX equivalent to cifs$xlate.
Synopsis
CALL "cifs$xlate" USING path, cifs-xlate, ccs-in, ccs-out, cifs-status.
Description
path
is a nul-terminated character string that contains the path name of the file.
cifs-xlate
ccs-in
is a 1-word (1(72) BINARY-1) data item which contains the translate information. Use
the COBOL COPY PROC CIFS-XLATE for the declaration of this variable.
ccs-out
is an alphanumeric data item that contains a CCS name.
is an alphanumeric data item that contains a CCS name.
cifs-status
is a 1-word ( 1(36) BINARY-1 ) data item that contains the error information returned
by the service subprogram. Use the COBOL COPY PROC CIFS-API for the
declaration of this variable.
The path parameter specifies the directory for which translation information is set or
retrieved. The cifs-xlate data item must be set by one of the following commands:
set cifs-xlate-get to true.
set cifs-xlate-set-in to true.
set cifs-xlate-set-out to true.
set cifs-xlate-set-both to true.
For cifs-xlate-get set to true, ccs-in and ccs-out specify where to return the coded
character set (CCS) names for the directory; the resulting values are empty strings if
translation is not enabled for the specified directory.
For cifs-xlate-set-in or cifs-xlate-set-both set to true, ccs-in is the CCS name used to
establish the translation mode for files written into the directory; an empty string turns
off translation.
7859 6137–009 6–155

CIFS$XLATE
For cifs-xlate-set-out set to true, ccs-out is the CCS name used to establish the
translation mode for files read from the directory; an empty string turns off translation.
See the CIFSUT xlate command for a list of valid CCS names.
Return Values
If the cifs$xlate service subprogram completes successfully, it returns a value of 0 in the
cifs-status parameter. Otherwise, cifs$xlate sets cifs-status to identify the specific error
that was encountered.
Error Codes
If any of the following conditions occurs, the cifs$xlate service subprogram returns a
nonzero value in the cifs-status parameter. The following COBOL level 88 condition
names (defined in the COBOL COPY PROC CIFS-API) can be checked in order to
determine the error that was returned:
CIFS-ECCSNAME One or both of the requested CCS names are not known to
CIFS.
CIFS-ENOTDIR The requested path is not a directory.
6–156 7859 6137–009

Example Program
Example Program
The following example program can be used to list the contents of a file/directory that
resides on the 2200, or it can be used to copy a file/directory from one location to
another. If uses many of the service programs that were discussed earlier in this section.
First, compile the program. Be sure to perform the following command prior to the
compilation:
@use cob$pf.,sys$lib$*cifs$lib.
IDENTIFICATION DIVISION.
PROGRAM-ID.
CIFS-TEST.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. UNISYS-2200.
OBJECT-COMPUTER. UNISYS-2200.
*
* Control characters commonly used in C strings.
*
SPECIAL-NAMES.
SYMBOLIC nul, lf IS 1, 11.
DATA DIVISION.
WORKING-STORAGE SECTION.
*
* General CIFS definitions.
*
COPY CIFS-API.
*
* Definitions for OFLAG bits used on open() calls.
*
COPY CIFS-OFLAG.
*
* Definitions for MODE bits used when creating files.
*
COPY CIFS-MODE.
*
* Space for a pointer to the standard output and standard error
* stream control structures.
*
COPY CIFS-FILE REPLACING CIFS-FILE BY CIFS-STDERR-FILE.
COPY CIFS-FILE REPLACING CIFS-FILE BY CIFS-STDOUT-FILE.
*
* Command parsing control string, result fields, and error messages.
*
01 COMMAND-FORMAT.
03 FILLER PIC X(8) VALUE " %n%3s%n".
03 FILLER PIC X(7) VALUE " %4095s".
03 FILLER PIC X(7) VALUE " %4095s".
03 FILLER PIC X(4) VALUE " %1s".
03 FILLER PIC X VALUE nul.
7859 6137–009 6–157

Example Program
77 FIELD-COUNT PIC S1(36) BINARY-1.
01 COMMAND-LINE.
03 COMMAND-BYTE PIC X OCCURS 4.
77 COMMAND-START PIC S1(36) BINARY-1.
77 COMMAND-STOP PIC S1(36) BINARY-1.
77 COMMAND-BYTES PIC S1(36) BINARY-1.
77 ARGUMENT-1 PIC X(4096).
77 ARGUMENT-2 PIC X(4096).
77 ARGUMENT-3 PIC X.
01 COMMAND-ERROR-MESSAGE.
03 FILLER PIC X(27)
VALUE "*Error reading command line".
03 FILLER PIC X VALUE nul.
01 SYNTAX-ERROR-FORMAT.
03 FILLER PIC X(24)
VALUE "Unrecognized input: ".
03 FILLER PIC X VALUE lf.
03 FILLER PIC X VALUE nul.
*
* Error and informational messages for file access.
*
01 OPEN-ERROR-FORMAT.
03 FILLER PIC X(21)
VALUE "*Error opening : ".
03 FILLER PIC X VALUE nul.
01 READ-ERROR-MESSAGE.
03 FILLER PIC X(25)
VALUE "*Error reading input file".
03 FILLER PIC X VALUE nul.
01 WRITE-ERROR-MESSAGE.
03 FILLER PIC X(26)
VALUE "*Error writing output file".
03 FILLER PIC X VALUE nul.
01 CLOSE-ERROR-MESSAGE.
03 FILLER PIC X(26)
VALUE "*Error closing output file".
03 FILLER PIC X VALUE nul.
01 COPY-FORMAT.
03 FILLER PIC X(15)
VALUE "%d bytes copied".
03 FILLER PIC X VALUE lf.
03 FILLER PIC X VALUE nul.
*
* Data fields used in reading and writing files.
*
77 READ-FD PIC S1(36) BINARY-1.
77 WRITE-FD PIC S1(36) BINARY-1.
COPY CIFS-DIR.
77 BYTES-READ PIC S1(36) BINARY-1.
77 BYTES-WRITTEN PIC S1(36) BINARY-1.
77 BYTES-TOTAL PIC S1(36) BINARY-1.
01 DATA-BUFFER.
6–158 7859 6137–009

03 DATA-BYTE PIC X OCCURS 131072.
*
* Error and informational messages for listing directory entries.
*
01 GETCWD-ERROR-MESSAGE.
03 FILLER PIC X(35)
VALUE "*Error retrieving current directory".
03 FILLER PIC X VALUE nul.
01 CHDIR-ERROR-FORMAT.
03 FILLER PIC X(25)
VALUE "*Error changing to : ".
03 FILLER PIC X VALUE nul.
01 DIRECTORY-ERROR-MESSAGE.
03 FILLER PIC X(24)
VALUE "*Error reading directory".
01 STAT-ERROR-FORMAT.
03 FILLER PIC X(26)
VALUE "*Error on stat() of : ".
03 FILLER PIC X VALUE nul.
01 STAT-ENTRY-FORMAT.
03 FILLER PIC X(6) VALUE " %-18s".
03 FILLER PIC X(6) VALUE " %012o".
03 FILLER PIC X(4) VALUE " %8i".
03 FILLER PIC X(4) VALUE " %5i".
03 FILLER PIC X(5) VALUE " %11i".
03 FILLER PIC X VALUE lf.
03 FILLER PIC X VALUE nul.
01 ISTAT-ERROR-FORMAT.
03 FILLER PIC X(35)
VALUE "*Error on istat() of , ino %d: ".
03 FILLER PIC X VALUE nul.
01 ISTAT-FILE-FORMAT.
03 FILLER PIC X(11) VALUE " %s#%s(%d)".
03 FILLER PIC X VALUE nul.
01 ISTAT-TYPE-FORMAT.
03 FILLER PIC X(10) VALUE " (%hd.%hd)".
03 FILLER PIC X VALUE nul.
01 ISTAT-OWNER-FORMAT.
03 FILLER PIC X(7) VALUE " %s/%s".
03 FILLER PIC X VALUE lf.
03 FILLER PIC X VALUE nul.
*
* Data fields used in listing directories.
*
01 DOT-NAME.
03 FILLER PIC X VALUE ".".
03 FILLER PIC X VALUE nul.
77 INODE-NUMBER PIC S1(36) BINARY-1.
01 ENTRY-NAME.
03 ENTRY-BYTE PIC X OCCURS 4096.
COPY CIFS-STAT.
*
Example Program
7859 6137–009 6–159

Example Program
*
*
PROCEDURE DIVISION.
COMMAND-LOOP SECTION.
GET-COMMAND.
*
* Retrieve the FILE struct pointers for use on normal and
* error messages.
*
CALL "CIFS$STDOUT" USING CIFS-STDOUT-FILE.
CALL "CIFS$STDERR" USING CIFS-STDERR-FILE.
*
* Main loop to read, parse, and dispatch commands.
*
PERFORM TEST AFTER UNTIL COMMAND-BYTES = 0
*
* Read a command line from standard input.
*
CALL "CIFS$READ" USING CIFS-STDIN-FD,
DATA-BUFFER,
131071,
COMMAND-BYTES,
CIFS-STATUS
IF BYTES-READ < 0
CALL "CIFS$PERROR" USING CIFS-STATUS,
COMMAND-ERROR-MESSAGE
STOP RUN
END-IF
*
* Insure the image is nul terminated for sscanf().
*
IF COMMAND-BYTES > 0 AND DATA-BYTE(COMMAND-BYTES) = lf
MOVE nul to DATA-BYTE(COMMAND-BYTES)
ELSE
MOVE nul TO DATA-BYTE(COMMAND-BYTES + 1)
END-IF
*
* Clear command field before parsing into it.
*
MOVE SPACES TO COMMAND-LINE
CALL "CIFS$SSCANF" USING FIELD-COUNT,
DATA-BUFFER,
COMMAND-FORMAT,
COMMAND-START,
COMMAND-LINE,
COMMAND-STOP,
ARGUMENT-1,
ARGUMENT-2,
ARGUMENT-3
*
* If anything was input, replace the terminating nul with a space to
* allow COBOL comparisons to work, then branch to the proper handler.
6–160 7859 6137–009

Example Program
*
IF FIELD-COUNT > 0
SUBTRACT COMMAND-START FROM COMMAND-STOP GIVING
COMMAND-BYTES
MOVE SPACE TO COMMAND-BYTE(COMMAND-BYTES + 1)
EVALUATE COMMAND-LINE ALSO FIELD-COUNT
WHEN "cp" ALSO 3 PERFORM COPY-FILE
WHEN "ls" ALSO 2 PERFORM LIST-DIRECTORY
WHEN OTHER PERFORM SYNTAX-ERROR
END-EVALUATE
END-IF
END-PERFORM.
STOP RUN.
*
* Indicate input does not comply with syntax rules.
*
SYNTAX-ERROR.
CALL "CIFS$FPRINTF" USING BYTES-WRITTEN,
CIFS-STDERR-FILE,
SYNTAX-ERROR-FORMAT,
DATA-BUFFER.
*
* Section to copy a file to a new location.
*
COPY-FILE SECTION.
*
* Open the source file read-only. Display an error message and give
* up if the open() fails.
*
OPEN-INPUT-FILE.
MOVE 0 TO CIFS-OFLAG.
MOVE 1 TO CIFS-OFLAG-RDONLY.
MOVE 0 TO CIFS-MODE.
CALL "CIFS$OPEN" USING ARGUMENT-1,
CIFS-OFLAG,
CIFS-MODE,
READ-FD,
CIFS-STATUS.
IF READ-FD < 0
CALL "CIFS$FPRINTF" USING BYTES-WRITTEN,
CIFS-STDERR-FILE,
OPEN-ERROR-FORMAT,
ARGUMENT-1
CALL "CIFS$PERROR" USING CIFS-STATUS
GO TO COPY-DONE
END-IF.
*
* Now try to create the output file. If the specific file already
* exists in a writable state, it will be erased and overwritten.
* Otherwise, a new file will be created. Any errors result in a
* message being displayed and abandonment of the copy.
*
7859 6137–009 6–161

Example Program
OPEN-OUTPUT-FILE.
MOVE 0 TO CIFS-MODE.
COMPUTE CIFS-MODE-IRWXU = CIFS-MODE-IREAD +
CIFS-MODE-IWRITE.
COMPUTE CIFS-MODE-IRWXG = CIFS-MODE-IREAD;
COMPUTE CIFS-MODE-IRWXO = CIFS-MODE-IREAD;
CALL "CIFS$CREAT" USING ARGUMENT-2,
CIFS-MODE,
WRITE-FD,
CIFS-STATUS.
IF WRITE-FD < 0
CALL "CIFS$FPRINTF" USING BYTES-WRITTEN,
CIFS-STDERR-FILE,
OPEN-ERROR-FORMAT,
ARGUMENT-2
CALL "CIFS$PERROR" USING CIFS-STATUS
CALL "CIFS$CLOSE" USING READ-FD,
CIFS-STATUS
GO TO COPY-DONE
END-IF.
*
* Both input and output files are open, so start reading and writing.
* Display a message and punt if any errors encountered.
*
COPY-INPUT-TO-OUTPUT.
MOVE 0 TO BYTES-TOTAL.
PERFORM TEST AFTER UNTIL BYTES-READ = 0
CALL "CIFS$READ" USING READ-FD,
DATA-BUFFER,
131072,
BYTES-READ,
CIFS-STATUS
IF BYTES-READ < 0
CALL "CIFS$PERROR" USING CIFS-STATUS,
READ-ERROR-MESSAGE
GO TO CLOSE-FILES
END-IF
IF BYTES-READ > 0
CALL "CIFS$WRITE" USING WRITE-FD,
DATA-BUFFER,
BYTES-READ,
BYTES-WRITTEN,
CIFS-STATUS
IF BYTES-WRITTEN < 0
CALL "CIFS$PERROR" USING CIFS-STATUS,
WRITE-ERROR-MESSAGE
GO TO CLOSE-FILES
END-IF
ADD BYTES-WRITTEN TO BYTES-TOTAL
END-IF
END-PERFORM.
*
6–162 7859 6137–009

Example Program
* Indicate progress, then close both files. Note that we
* ignore the status on closing the input file, but do report
* a problem with the output, since that may result in the
* underlying element not being created.
*
CLOSE-FILES.
CALL "CIFS$PRINTF" USING BYTES-WRITTEN,
COPY-FORMAT,
BYTES-TOTAL.
CALL "CIFS$CLOSE" USING READ-FD,
CIFS-STATUS.
CALL "CIFS$CLOSE" USING WRITE-FD,
CIFS-STATUS.
IF CIFS-STATUS NOT = 0
CALL "CIFS$PERROR" USING CIFS-STATUS,
CLOSE-ERROR-MESSAGE
END-IF.
COPY-DONE.
EXIT.
*
* Section to display the entries in a directory.
*
LIST-DIRECTORY SECTION.
*
* Save the current directory, and switch to the requested one.
*
CHANGE-CURRENT-DIRECTORY.
CALL "CIFS$GETCWD" USING DATA-BUFFER,
131072,
CIFS-STATUS.
IF CIFS-STATUS NOT = 0
CALL "CIFS$PERROR" USING CIFS-STATUS,
GETCWD-ERROR-MESSAGE
GO TO LIST-DONE
END-IF.
CALL "CIFS$CHDIR" USING ARGUMENT-1,
CIFS-STATUS.
IF CIFS-STATUS NOT = 0
CALL "CIFS$FPRINTF" USING BYTES-WRITTEN,
CIFS-STDERR-FILE,
CHDIR-ERROR-FORMAT,
ARGUMENT-1
CALL "CIFS$PERROR" USING CIFS-STATUS
GO TO LIST-DONE
END-IF.
*
* Open the requested directory. Display a message and get out if there
* are any errors.
*
OPEN-DIRECTORY.
CALL "CIFS$OPENDIR" USING DOT-NAME,
CIFS-DIR,
7859 6137–009 6–163

Example Program
CIFS-STATUS.
IF CIFS-STATUS NOT = 0
CALL "CIFS$FPRINTF" USING BYTES-WRITTEN,
CIFS-STDERR-FILE,
OPEN-ERROR-FORMAT,
ARGUMENT-1
CALL "CIFS$PERROR" USING CIFS-STATUS
GO TO RESTORE-CURRENT-DIRECTORY
END-IF.
*
* Scan the directory, do stat() and istat() on each entry, and
* display the info.
*
READ-DIRECTORY.
PERFORM TEST AFTER UNTIL BYTES-READ = 0
CALL "CIFS$READDIR" USING CIFS-DIR,
INODE-NUMBER,
ENTRY-NAME,
4095,
BYTES-READ,
CIFS-STATUS
MOVE nul to ENTRY-BYTE(BYTES-READ + 1)
IF BYTES-READ SPACES
CALL "CIFS$PRINTF" USING
BYTES-WRITTEN,
ISTAT-FILE-FORMAT,
CIFS-ISTAT-DIRECTORY,
CIFS-ISTAT-CONTAIN,
CIFS-ISTAT-CYCLE
6–164 7859 6137–009

END-IF
IF CIFS-ISTAT-ELEMENT-NAME > SPACES
CALL "CIFS$FPUTC" USING '.',
CIFS-STDOUT-FILE,
CIFS-STATUS
IF CIFS-STATUS NOT = 0
CALL "CIFS$PERROR" USING CIFS-STATUS
STOP RUN
END-IF
CALL "CIFS$FPUTS" USING
CIFS-ISTAT-ELEMENT-NAME,
CIFS-STDOUT-FILE,
BYTES-WRITTEN,
CIFS-STATUS
IF CIFS-ISTAT-ELEMENT-VERSION > SPACES
CALL "CIFS$FPUTC" USING '/',
CIFS-STDOUT-FILE,
CIFS-STATUS
CALL "CIFS$FPUTS" USING
CIFS-ISTAT-ELEMENT-VERSION,
CIFS-STDOUT-FILE,
BYTES-WRITTEN,
CIFS-STATUS
END-IF
CALL "CIFS$PRINTF" USING
BYTES-WRITTEN,
ISTAT-TYPE-FORMAT,
CIFS-ISTAT-ELEMENT-TYPE,
CIFS-ISTAT-ELEMENT-SUB-TYPE
END-IF
CALL "CIFS$PRINTF" USING BYTES-WRITTEN,
ISTAT-OWNER-FORMAT,
CIFS-ISTAT-OWNER,
CIFS-ISTAT-ACR
ELSE
CALL "CIFS$FPRINTF" USING BYTES-WRITTEN,
CIFS-STDERR-FILE,
ISTAT-ERROR-FORMAT,
ENTRY-NAME,
CIFS-STAT-INO
CALL "CIFS$PERROR" USING CIFS-STATUS
END-IF
ELSE
CALL "CIFS$FPRINTF" USING BYTES-WRITTEN,
CIFS-STDERR-FILE,
STAT-ERROR-FORMAT,
ENTRY-NAME
CALL "CIFS$PERROR" USING CIFS-STATUS
END-IF
END-PERFORM.
*
* Close the directory we were reading. Ignore any errors.
Example Program
7859 6137–009 6–165

Example Program
*
CLOSE-DIRECTORY.
CALL "CIFS$CLOSEDIR" USING CIFS-DIR,
CIFS-STATUS.
*
* Reestablish the directory we were in when we started.
*
RESTORE-CURRENT-DIRECTORY.
CALL "CIFS$CHDIR" USING DATA-BUFFER,
CIFS-STATUS.
IF CIFS-STATUS NOT = 0
CALL "CIFS$FPRINTF" USING BYTES-WRITTEN,
CIFS-STDERR-FILE,
CHDIR-ERROR-FORMAT,
DATA-BUFFER
CALL "CIFS$PERROR" USING CIFS-STATUS
END-IF.
LIST-DONE.
EXIT.
END PROGRAM CIFS-TEST.
Following the compilation, the program can be executed. In order to list the contents of
the 2200 file sys$lib$*ucob, perform the following commands:
@xqt object-module
ls /os2200/sys$lib$/ucob
This must result in output that looks like this:
. 000000040777 455956 2 2983
STD#sys$lib$*ucob(53) lewis/PUBLIC
.. 000000040777 9 1062 38413
cifs-admin/PRIVATE
ucob-fgss..abs 100001100777 767829 1 2907640
STD#sys$lib$*ucob(53).ucob-fgss (6.1) lewis/PUBLIC
ucob-fgssf..abs 100001100777 768187 1 2975736
STD#sys$lib$*ucob(53).ucob-fgssf (6.1) lewis/PUBLIC
ucob..abs 100001100777 767896 1 72248
STD#sys$lib$*ucob(53).ucob (6.3) lewis/PUBLIC
ivp 100002100777 767910 1 14224
STD#sys$lib$*ucob(53).ivp (1.9) lewis/PUBLIC
solar$sgs 100002100777 767894 1 6832
STD#sys$lib$*ucob(53).solar$sgs (1.1) lewis/PUBLIC
deact-scss 100002100777 767895 1 1568
STD#sys$lib$*ucob(53).deact-scss (1.1) lewis/PUBLIC
6–166 7859 6137–009

Example Program
In order to copy the file sys$lib$*ucob.ivp to another location, perform the following
commands:
@xqt object-module
cp /os2200/sys$lib$/ucob/ivp /os2200/my/file/ivp
This must result in the following output:
12674 bytes copied
The file sys$lib$*ucob.ivp must now be copied to the file my*file.ivp.
The following example illustrates what happens if the file that you are attempting to copy
from does not exist:
@xqt object-module
cp /os2200/invalid/file/ivp /os2200/my/file/ivp
This must result in the following output:
*Error opening : *ERROR CFS000002: Object with specified
name does not exist.
7859 6137–009 6–167

Example Program
6–168 7859 6137–009

Section 7
CIFS Client
The 5R1 and higher levels of CIFS includes a client capability, enabling CIFS-aware 2200
programs to directly access files on remote servers, including other 2200s, Windows 98,
Windows NT, Windows 2000, Windows XP, Windows 2003, Windows Vista, and Linux
or UNIX systems running Samba. Other 2200s must be running the 5R1 or higher level in
order for the client to connect to them, due to enhanced security requirements of the
client.
Accessing a Remote System
To access a remote system, you must use a URL-like remote path reference:
//[[domain;]userid[:password]@][server][:port]/share[/path...]
This remote path reference may be used in most of the CIFS APIs that use paths, such
as open(), opendir(), stat(), and so on. It may not be used in APIs that implement purely
server functions, such as share(), or ones that manipulate security attributes, such as
chmod(). Likewise, a remote path reference can be used in most CIFSUT commands,
since CIFSUT serves primarily as a front end to the CIFS APIs.
The CIFS client obtains the user ID and password for the remote server from one of the
following, in the order listed:
1. The specified remote reference
2. The most recent connection to the same remote server
3. Environnent variables (CIFS$USER, CIFS$PW)
4. The most recent connection to anywhere
5. The user's OS 2200 credentials
Only the first non-null source of credentials is used, although user ID and password are
handled independently (for example, the user ID could come from the URL, the
password from the environment variable).
7859 6137–009 7–1

CIFS Client
Example
For example, to list executable files in a directory on the OS 2200 system RS17FE from a
run on another 2200 (inputs are in bold):
>@cifsut
CIFSUT 5R1Q1 (2003/Aug/18 13:30:20) 2003 Aug 18 Mon 15:24:16
>dir \\crc:MYPASS@rs17fe\caldarale\testing\*.abs
2003/07/09 17:13:26 25779384 jvmhssg..abs
1994/12/30 10:19:04 3032 fasg..abs
1986/10/02 16:01:42 97000 fed..abs
2002/11/14 15:10:04 307560 hjavag..abs
2003/05/02 07:45:56 563928 memtime..abs
2003/07/23 08:17:16 1032424 uedit..abs
or all files in a Windows 2000 directory:
>set CIFS$USER=na;caldarcr
>set CIFS$PW=myNetworkPassword
>ls -l //USRV-CALDARCR.na.uis.unisys.com/c$/test-dir
-rwxr-xr-x 0 1275904 2003/08/17 21:58:21 cifs$util..omn
-rwxr-xr-x 0 3032 2003/08/17 12:01:32 fasg..abs
or to copy a directory tree to another 2200:
>pwd
/os2200/caldarale
>cp -r stjdk //rs17fe/caldarale
Note: If your user ID and password for the server are the same as those on the client,
you can leave the environment variables blank and leave off the fields on the remote
reference; the client credentials are used automatically.
7–2 7859 6137–009

Using Passwords
CIFS Client
Passwords for the CIFS client are always case-sensitive, so you need to use uppercase
to access most 2200s. Also, CIFS environment variable names must always be specified
in uppercase. The environment variable is preferred over specifying the password
directly in the remote reference, since that minimizes the possibility of displaying a
password when echoing the path for an error message.
Note that passwords are never sent over the network by CIFS, unlike telnet and FTP.
Instead, CIFS uses at a minimum NTLM authentication, which creates a hash value from
the password, and then uses that hash value as an encryption key against a
server-supplied random challenge. Only the result of that one-way encryption is sent to
the server, which compares it with its own computation to determine whether to allow
the connection.
7859 6137–009 7–3

CIFS Client
7–4 7859 6137–009

Section 8
ZIPUT Processor
ZIPUT is an OS 2200 command line utility that allows you to create, update, view, and
extract ZIP files on the 2200 mainframe. ZIPUT is written primarily in Java, and therefore
requires that the Virtual Machine for the Java Platform (informally, JVM) product be
installed on the system.
Using the ZIPUT Processor
Use the following syntax when using the ZIPUT processor.
Format 1
ZIPUT is normally called using the unformatted processor call technique. In this case, the
format would be the following:
or
@'ZIPUT [options] ZipFileName [EntryName1 [EntryName2]...]
@'ZIPUT -g ArgsPathName
Format 2
ZIPUT can also be called using standard ECL with an element name specifying the
location of the ZIPUT arguments. For example:
@ZIPUT [[[[qual]*]file].]elt[/ver]
where [[[[qual]*]file].]elt[/ver] contains the following:
[option1]
[option2]
...
ZipFileName
[EntryName1]
[EntryName2]
...
7859 6137–009 8–1

ZIPUT Processor
Upon termination, ZIPUT sets T3 of the run condition word to one of the following four
values:
0 – Execution completed normally
1 – Warnings generated, but execution completed
2 – Errors detected; some processing accomplished
3 – Fatal condition encountered; execution halted
The run condition word can be examined with @TEST in an ECL script.
ZIPUT Arguments
The basic syntax of the ZIPUT arguments is
[options] ZipFileName [EntryName1 [EntryName2]...]
The arguments can either be supplied on the same line if you are using the unformatted
processor call technique, or on the line following the @XQT of ZIPUT. ZipFileName and
all EntryName parameters must be specified as CIFS pathnames. Each may be
expressed as either an absolute path starting with a forward slash (‘/’) character, or as a
relative path without a leading forward slash. For relative paths, the current working
directory name (as shown by the CIFS$CD environment variable value) is inserted before
the specified name when ZIPUT is locating any file.
If ZipFileName does not end with a .zip or .*ar extension, .zip is added to the name
automatically. This prevents overwriting of the first EntryName file, if the ZipFileName is
accidentally omitted.
Note: ZIPUT operates only on ZIP-based archive formats, such as .jar, .war, .ear, and
Java EE .rar files; it cannot create or read files in Winrar or UNIX .tar and .ar formats.
Since the ZIPUT-created files must have an extension, they cannot be located at the
/os2200// level of the directory tree, but rather must be somewhere below
that in the hierarchy or not under /os2200 at all.
ZIPUT allows "*" and "?" characters to be used as masking characters. A "*'matches zero
or more characters and a "?" matches any single character. Mask characters may appear
in any component of an EntryName path.
Basic Argument Syntax
The options that use the basic argument syntax are as follows:
-a
The -a option adds the EntryName(s) to ZipFileName. Each entry name placed into
ZipFileName is as specified on the call line. If an EntryName already exists in
ZipFileName, it is updated. If the ZipFileName does not currently exist, it is created.
If ZipFileName and at least one EntryName are specified without any of the -a, -d, -v,
-g, or -u options, the -a option is assumed.
8–2 7859 6137–009

-n
ZIPUT Processor
If this option is specified along with the -a option, then any EntryName placed in
ZipFileName contains the full path name, even if the EntryName is specified as a
relative path.
-b
If this option is specified along with the -a option, then any EntryNames placed in
ZipFileName is added in binary form.
-d
The -d option deletes the specified EntryName entries from ZipFileName. The entry
name must be specified exactly as it is named in ZipFileName.
-u
The unzip option decompresses the entries contained in ZipFileName into CIFS
directories. Entries are not removed from ZipFileName. When no EntryName(s) are
specified, all the files contained in ZipFileName are decompressed into CIFS files
having the same names. If a CIFS file has the same name as an entry in
ZipFileName, the CIFS file is overwritten. If the zip entry name does not contain a
leading forward slash character, the zip entry is decompressed into
/.
-v
The view option displays the contents of ZipFileName. This view includes each
EntryName, size, and modification time. If no EntryName(s) are specified, all entries
in ZipFileName are displayed. The -v option must not be used with other options.
-r
This option causes recursion into subdirectories, and may only be used with the -a
option. The starting directory is specified as part of each EntryName. For example, if
the following options are specified
-a -n -r /a/b/c/x.y z.txt bbb/ccc/w.class
the directory in which the search for x.y begins is /a/b/c. If the specified path is
relative, the current working directory (as indicated by the CIFS$CD environment
variable) is prefixed to the specified path to determine where to begin the search.
The directory in which the search for z.txt starts is the current working directory; the
starting directory for the search for w.class is
-q
/bbb/ccc
If this option (quiet mode) is specified, then no file addition, deletion, or
decompression messages are displayed to standard output.
7859 6137–009 8–3

ZIPUT Processor
Additional Syntax
Arguments using a different syntax are as follows:
-e compression_level
This option allows you to set the compression level when adding to ZipFileName.
The compression_level can be a number from 0 to 9, where 9 gives the strongest
and slowest level of compression, and 0 results in no compression.
-z SourceZipFile
Indicates that entries added to ZipFileName are taken from the specified ZIP file
rather than the CIFS file system. May only be used when the -a option is in effect.
This option allows the merging of ZIP files without having to expand them first.
-g ArgsPathName1 [ArgsPathName2 [ArgsPathName3 ]... ]
The -g option processes the arguments contained in each ArgsPathName. The -g
option must be the only option on the command line. Each ArgsPathName may be
expressed as either an absolute or relative path. Within each ArgsPathName,
multiple arguments are allowed, but each argument must be on a separate line
(leading spaces are ignored).
-h
The help option displays all ZIPUT options and parameters and a short description of
what each option does. If no other options or names are specified on the call line,
the -h option is assumed. The -h option must be the only option on the command
line.
Multiple compatible options may be grouped together (for example, -ar); however, when
used, the e-, g-, or z-option must be the last in any such group.
8–4 7859 6137–009

Section 9
Administration
CIFS is installed with SOLAR and becomes active when the associated background run
initializes the shared subsystem component. The /os2200 directory is initially populated
during the first execution of the background run. After initial population, CIFS monitors
system log entries as described below (see “Directory Synchronization”) to keep the
/os2200 directory in sync with the Exec MFD directories.
Administrative tasks include:
• Setting system environment variables.
• Ensuring that CIFS-BACK is running at all times.
• Running CIFS-POP as needed.
• Stopping CIFS if necessary, using CIFS-DEACT or the E CIFSB keyin.
Information about performing each action is provided below.
CIFS Installation Overview
At CIFS installation time, the following elements are placed in SYS$LIB$*CIFS$LIB:
• CIFS-BACK (runstream element for Monitor Services and network access)
• CIFS-POP (runstream element for Populate)
• CIFS-DEACT (runstream to deactivate the CIFS subsystem and stop CIFSB)
• CIFS-BACK-Z (object module for Monitor Services and network access)
• CIFS-POP-Z (object module for Populate)
• CIFS-DEACT-Z (object module for deactivating the CIFS subsystem)
In addition, the following elements are placed in the file SYS$LIB$*RUN$:
• CIFS-BACK (runstream element for Monitor Services and network access)
• CIFS-POP (runstream element for Populate)
• CIFS-DEACT (runstream to deactivate the CIFS subsystem and stop CIFSB)
Also, the following @START image is placed in SYS$LIB$*RUN$.AUTO$START:
@START SYS$LIB$*RUN$.CIFS-BACK,,,
7859 6137–009 9–1

Administration
Notes:
• The “” used on this @START image can be specified by SOLAR SGS
statements during installation. Use the SOLAR SGSs,
DEFAULT_RUNSTREAM_ACCOUNT and DEFAULT_RUNSTREAM_USERID, to
specify the account/user ID on the @START images.
• The / of CIFS-BACK and CIFS-POP requires
− ER MODPS$ capability
− Real-time capability
• The account used must allow access by the subsystem user ID, if
QUOTA_ENFORCEMENT_BY_USERID = TRUE. (See “CIFS Subsystem User ID” in
this section.)
• The run ID used by CIFS-BACK runstream is CIFSB.
• The run ID used by the Populate run, automatically started by CIFSB, is CIFSP.
• The user ID for CIFS-DEACT must have read and write access to
SYS$LIB$*CIFS$SS and MODPS$ capability.
• For Fundamental Security systems, the site administrator must modify the CIFS-
DEACT runstream to include any keys used for assignment of the subsystem file.
• If the Exec configuration tag APL_BANK_BDI_GT4K is set to TRUE, CIFS allocates its
application level data banks from the bank descriptor index range above 4095. This
reduces the impact on relatively scarce “low” BDIs.
• The CIFS background run must be used to initialize the subsystem. All other
requests to the subsystem are held until the background run has completed
initialization.
Directory Synchronization
CIFS monitors the system log entries for purposes of keeping the CIFS directories
synchronized with the Exec Master File Directories (MFDs). Specifically, CIFS retrieves
the following entries from the system log, through Monitor Services (MSCP):
• 403 - fixed file @ASG, @FREE, or @CAT
• 407 - removable file @ASG, @FREE, or @CAT
• 807 - ER SUMOD$ (file attributes change)
As a result, every file that is cataloged, deleted, or has its accessibility changed in an
Exec MFD automatically causes the associated update in the CIFS directories. These are
additional considerations:
• The original contents of the /os2200 directory in CIFS is created from the Exec MFDs
when CIFS is initialized or reloaded (through the CIFS-POP runstream). This retrieval
of the current MFD information is termed Populate.
• Files in the shared MFD that are created on a file sharing host other than where CIFS
is running cannot be immediately detected by CIFS, because a log entry is not
currently created on the other participating hosts.
9–2 7859 6137–009

Administration
• Changes in public and private accessibility for unowned files are not monitored by
CIFS. The CIFS and Exec directories is resynchronized the next time CIFS-POP is
run, and direct references to the file created on the other host also causes its
inclusion in the CIFS file hierarchy.
• Files that are deleted by F-cycling, for example @CYCLE, are not monitored.
• Files introduced or removed with removable pack file registration and deregistration
are not monitored.
During initialization, CIFS performs the following processing to insure its directories are
up to date:
• The CIFS-BACK runstream (automatically started at Exec reboot) initializes system
log monitoring through MSCP.
• The CIFS-POP runstream is started by CIFS through @START,A/X to perform the
Populate process. This runstream is started even if CIFS-BACK fails to connect with
MSCP.
• While Populate is running, log entry processing for status changes to existing files
are deferred until Populate completes, because such files might not yet have been
entered into the CIFS directory by Populate. That is, if a file was cataloged when
CIFS was not active or not connected to Monitor Services, then Populate finds out
and enter it into the CIFS directories. However, file accessibility changes (such as
from public to private) cannot be processed until Populate completes its
synchronization.
If CIFS-BACK is not running properly, the CIFS directory cannot be synchronized with the
Exec MFD. Viewing /os2200 files with CIFS might result in the display of files that have
been deleted from the Exec MFD, or recently cataloged Exec files might not be
displayed.
The CIFS-BACK background run breakpoints its output to SYS$CIFS$*BACK-BRKPT. If
the CIFS-BACK run errors, this file might contain useful diagnostic information.
Scanning a CIFS directory associated with a rolled out or exclusively assigned program
file does not result in an error or initiation of a ROLBAK request for the file. However,
CIFS can return outdated directory entries if the file was modified between the last time
it was accessed through CIFS and the time when it became unavailable. CIFS
automatically updates the directory entries when the program file is again available
during a CIFS access.
7859 6137–009 9–3

Administration
CIFS Subsystem User ID
Populate
The user ID of the CIFS subsystem must have the following properties:
• On Fundamental systems, the user ID must be the Security Officer.
• On Security Option 1 or higher, the SERVE$ and MODPS$ ERs are required as well
as these privileges:
− SSAUTHNTICAT
− SSBAFC
− SSBPFC
− SSBYPASSOWNR
− SSCONSOLE
− SSDRG
− SSGAP
− SSLASH
− SSMROOC
− SSRUNXOPT
• On Security Option 1 or higher, the subsystem user ID must not have the SSBROD
privilege.
• On Security Option 1 or higher, the subsystem user ID must not be set to create
unowned files.
• If QUOTA_ENFORCEMENT_BY_USERID = TRUE, then the account used on the
CIFS-BACK run must be accessible by the subsystem user ID.
• Clearance Level must not have a range. That is, the minimum and maximum
clearance levels must be the same; for example, 0 to 0, or 20 to 20.
• Compartment Set must be NULL. Compartments are not supported.
The process of updating the CIFS directories with information from the Exec master file
directories is called Populate. This process is run every time the CIFS-BACK runstream is
executed, thereby synchronizing the two sets of directories.
Unless Populate is explicitly disabled, it runs for every two hours during the time when
Monitor Services is not available.
Populate can also be run at any time, independently of the CIFS-BACK runstream, by
using the following console ST keyin:
ST CIFS-POP,,,
where the can be the same as used for CIFS-BACK. On Security Option
1 systems, the only attribute required is ER MODPS$.
9–4 7859 6137–009

Administration
The Populate background run breakpoints its output to SYS$CIFS$*POP-BRKPT.
Information on the number of files populated is written to this file, as well as any errors
that occur.
When Populate fails to start automatically, the CIFS-BACK run issues the following
message:
*ERROR* The CIFS-POP run failed to start: status.
The CIFS directory will not be in sync with the Exec MFD.
CIFS warning issued above. Answer OK
where status is the 12-digit octal ACSF$ value returned by the @START attempt. On
systems running with Security Option 1 or higher, the likely cause is that the CIFS
background run user ID does not have the SSRUNXOPT privilege.
If the Populate run encounters an error, the following console message is displayed:
*ERROR* the CIFS-POP run has failed.
The CIFS directory will not be in synch with the Exec MFD.
Diagnostics can be found in file SYS$CIFS$*CIFS$TRACE$$.
CIFS warning issued above. Answer OK
Starting the CIFS Background Run
Before you start CIFS-BACK, MSCP must be running. Additionally, to enable the network
access you must enable the desired Communications Application Program Interface
modes and either CMS 1100 or Communications Platform (or both).
CIFS displays a console message if MSCP is not active, since accuracy of the /os2200
directory hierarchy is not assured without MSCP. CIFS does not display a message if
communication with the network cannot be established, but it does automatically retry
connecting with the selected Communications Application Program Interface
subsystems (one or more) every 30 seconds.
The following console keyin is used to activate the CIFS background run:
ST CIFS-BACK,,,
Use the 1 in the SETC value field of the ST keyin to force CIFS directory verification. See
the V option under CIFS Background Run Options for more information.
The account and user ID for the CIFS-BACK run require the following attributes:
• On Fundamental Security systems, the security officer user ID must be used for the
runstreams.
• On Security Option 1 or higher, the following attributes are required:
− Must have the capability to perform ER MODPS$
− Must have the SSCONSOLE and SSRUNXOPT privileges
7859 6137–009 9–5

Administration
− Must have real-time capability of level 30 or better (a value less than or equal to
30)
− Must not have the SSBROD privilege
− Must not be set to create unowned files.
Note: The account used on the CIFS-BACK run must be usable by the CIFS
subsystem user ID, if the configuration parameter,
QUOTA_ENFORCEMENT_BY_USERID, is TRUE.
At system recovery, this run must be allowed out of backlog.
To determine the status of the CIFS background run, perform an RC keyin (RC CIFSB).
The response must indicate realtime (R/T) mode, not BATCH mode. However, during
directory verification CIFSB is in batch mode.
Handling Errors from the CIFS Background Run
The following are some of the error conditions that can occur during the CIFS
background run, including those related to Monitor Services:
• If the account attributes of the background run do not allow real-time capability, the
following console message is displayed:
*ERROR* CIFS background run is running with account number nnnnnn
that does not permit real-time priority. The CIFS background run
requires real-time priority to access MSCP, which is needed to
synchronize CIFS directories with the Exec Master File Directory.
Should CIFS Exit or run Without Monitor Services? (Exit, Without)
The CIFS subsystem is not functional until the message is answered. Responding
with “Exit” causes the background run to terminate and leaves the subsystem
disabled. Answering “Without” allows CIFS to function, but without real-time
synchronization of the MFD and CIFS directories.
• If MSCP is not accessible, the following console message is displayed:
*ERROR* CIFS has detected that Monitor Services (MSCP)
is not responsive. MSCP is needed to synchronize the CIFS
directories with the Exec Master File Directory.
Should CIFS Retry or Disable Monitor Services? (Retry, Disable)
A “Retry” response causes a 5-second delay and another attempt to register with
MSCP; the preceding message is repeated every five minutes if necessary. A
“Disable” response causes CIFS to stop attempting to connect to MSCP until the
next time the CIFS background run is started.
9–6 7859 6137–009

Administration
• If CIFS is unable to process log entries from MSCP quickly enough, the following
message is displayed:
*WARNING* CIFS is not running as expected.
CIFS filled log queue buffer b with n entries.
Log monitoring will continue, but the CIFS directory
may not reflect Exec file changes until these queued
entries are processed.
This indicates that adequate processing resources are not available.
• If CIFS needs to use the Security Server and it has not been created (a normal part of
the CIFS-BACK initialization), the following message is displayed:
*WARNING* CIFS has detected that its background run CIFSB is not active.
This run is required to process file security access checks.
Please start the background run using:
ST CIFS-BACK,,,/
Answer: Retry, after CIFSB is running, or
Error, to error all callers of CIFS
CIFS warning displayed above. (Retry, Error)
Stopping the CIFS Subsystem and Background Run
There are several ways to stop the CIFS background run:
• Use the CIFS DEACT keyin to shut down CIFS
• Use the ST keyin to shut down CIFS.
• Use the CIFS TERM keyin to stop the background run only.
• Use the E keyin to stop the background run only.
Stopping CIFS with the CIFS DEACT Keyin (Normal Shutdown
Procedure)
To stop the background run (CIFSB), deactivate the CIFS subsystem, and close the CIFS
trace file; then enter the following keyin:
CIFS-DEACT
Stopping CIFS with the ST Keyin (Alternate Shutdown Procedure)
To stop the background run (CIFSB), deactivate the CIFS subsystem, and generate the
CIFS trace file; then enter the following keyin:
ST CIFS-DEACT,,,
If the user ID used on the ST keyin does not have access to the SYS$LIB$*CIFS$SS file,
the following console message is displayed:
*ERROR* Userid does not have read & write access to SYS$LIB$*CIFS$SS.
Start CIFS-DEACT with a privileged userid. Answer OK
7859 6137–009 9–7

Administration
Note that CIFS maintains an internal trace area, which is written to disk when
CIFS-DEACT is run. The file name used to hold this trace data is
SYS$CIFS$*CIFS$TRACE$$.
Stopping CIFSB with the CIFS TERM
If the background run, CIFSB, needs to be stopped, enter the following keyin:
CIFS TERM
This causes the background run to fin, but it does not deactivate the CIFS subsystem. All
network access and system log monitoring are suspended, as is access to private files
on Fundamental Security systems. The background run can be restarted later in the
normal fashion.
If this keyin does not succeed, try the method using the E keyin.
Stopping CIFSB with the E Keyin
If the background run, CIFSB, needs to be stopped, enter the following keyin:
E CIFSB
This causes the background run to fin, but it does not deactivate the CIFS subsystem. All
network access and system log monitoring are suspended, as is access to private files
on Fundamental Security systems. The background run can be restarted later in the
normal fashion.
CIFS Background Run Options
Various options can be used on the background run executable CIFS-BACK-Z to control
its operation. These options are
K Inhibit use of network authentication even when all of the
prerequisites for network authentication are met.
M Inhibit execution of the Monitor Services interface.
N Disable network access.
P Inhibit starting the CIFS-POP runstream.
Q Prevent use of queue banks for network communications.
S Inhibit execution of the security server.
T Inhibit execution of the timer activity.
V Perform directory verification when CIFS is started.
None of these options should be used during normal CIFS operation. The V-option can be
used to correct suspected inconsistencies in the CIFS directory structure that might
result from system errors; however, it might take an hour or more to run in a large file
system, and CIFS is unusable for that time period.
9–8 7859 6137–009

CIFS Background Run Console Keyins
Administration
CIFS includes a console keyin handler that provides the following unsolicited console
keyins:
• CIFS BRKPT – @BRKPT the background run print file to a new cycle of
SYS$CIFS$*BACK-BRKPT; requires display console capability.
• CIFS DEACT – Deactivates the CIFS subsystem and stops the background run
without taking a dump of the subsystem; requires response console capability.
• CIFS ERROR – Deactivates the CIFS subsystem with a dump written to the trace
file, and stops the background run; requires response console capability.
• CIFS HELP – Displays this list of keyins; requires basic console capability.
• CIFS STATUS – Displays the installed CIFS version information and the availability of
network authentication.
• CIFS TERM – Performs an orderly shutdown of the CIFS background run.
• CIFS TRACE – Displays or alters the internal trace flag settings. The set of trace flags
that can be manipulated is subject to change at any time. Modifying the default
settings can impact performance and must be done judiciously.
To see current trace settings, enter
CIFS TRACE
To see all the possible trace flags, enter
CIFS TRACE ?
To change trace flags, enter
CIFS TRACE [+|-] [flag2]...
The following is a list of modifiers that can be used along with their descriptions:
+ The flags are added to the existing set
- The flags are removed from the existing set
Neither + nor - The specified flags replaces the existing set
To clear all trace flags, enter:
CIFS TRACE 0
Note: The PRINT trace flag sends all trace output to the PRINT$ file and the circular
internal trace buffer. This can have a significant impact on performance so do not leave
the trace flags set for an extended period of time. The CIFS BRKPT keyin closes the
current PRINT$ file (SYS$CIFS$*BACK-BRKPT) and starts a new cycle. None of the
keyins are case-sensitive.
7859 6137–009 9–9

Administration
CIFS Backup Procedure
The following files contain the internal data structures used by CIFS to manage the file
system. It is critical that these files be saved together if a FAS-like backup procedure is
used. If any of the files must be restored for any reason, restore all of them to insure the
integrity of the file system. The files are
SYS$CIFS$*CIFS$KERNEL$
SYS$CIFS$*00030000600x
SYS$CIFS$*00030000700x
SYS$CIFS$*00030000900x
SYS$CIFS$*00030000A00x
SYS$CIFS$*00030000B00x
SYS$CIFS$*00030000C00x
where x is a hexadecimal digit used to guarantee uniqueness. It is normally 0. For CIFS
level 2R2 or later installed over level 1R1, the SYS$CIFS$*00030000B00x file is no
longer used. For new CIFS level 2R2 or later installations, the
SYS$CIFS$*00030000C00x file is not present.
CIFS might create additional system files for sites with large numbers of directories. The
CIFSUT backup -f command can be used to generate the FAS commands needed to
save all CIFS system files.
These files are assigned to and being updated by the CIFS subsystem whenever it is
active. Consequently, if a FAS backup is used, the subsystem must be taken down
during the backup procedure. As an alternative to FAS, use the CIFSUT backup
command without the -f option to record the CIFS directory structure in a symbolic form.
This backup information can then be used as input to CIFSUT to restore the directory
structure. However, in a large file system, the backup command can take quite some
time to run, and it can produce a large amount of output. In these cases, using the -f
option on the backup command is the only recourse.
9–10 7859 6137–009

CIFS File Security Enforcement
Administration
CIFS relies on OS 2200 to perform security policy enforcement. OS 2200 security
privileges can be used to override this policy enforcement; for example, CIFS ignores any
ACR-imposed access restrictions for user IDs with the Bypass ACR Evaluation privilege.
CIFS, however, does enforce an additional security policy, namely file permission bits.
CIFS provides a privileged mode capability to override all CIFS security policy
enforcement. This privileged mode is invoked by the caller having read and write access
to the CIFS subsystem file, SYS$LIB$*CIFS$SS. In Fundamental Security systems, the
caller must have the subsystem file assigned with the proper read/write keys prior to
calling CIFS. In Security Option 1 and above, the caller must be able to pass an ER
SUVAL$ security check for read and write access to the file; the caller does not need to
have the file assigned.
To ensure only appropriate personnel have CIFS privileged mode capability, the CIFS
subsystem file must be protected by read/write keys on Fundamental Security systems
or by an ACR on Security Option 1 and above. The default SOLAR install of CIFS cannot
attach keys or an ACR to the subsystem file.
When supported by the Exec, accesses through CIFS to all owned files and any
unowned files with ACRs attached are logged in type 801, subtype 0, error type 060
entries. The logged information includes the filename, type of access, time of access,
and caller’s user ID, among other information.
CIFS and Clearance Levels / Compartment Sets
CIFS is designed to work with only a single clearance level and single compartment set.
When installed as documented in Appendix A of OS 2200 Software Products Installation
Guide, the CIFS subsystem runs without privilege to bypass either clearance level or
compartment set validation.
Although Table A-3 of the OS 2200 Software Products Installation Guide indicates a
clearance level range of 0 to 0, the user ID can be set up with any clearance level if the
minimum and maximum clearance levels are the same. CIFS can then only be able to
access files that have that specific clearance level.
Likewise, this table shows a compartment set of NULL. The CIFS subsystem user ID
can be given any set of compartments, but CIFS can then only be able to access files
with that set of compartments.
7859 6137–009 9–11

Administration
CIFS Network Access Security
To access OS 2200 CIFS through a network connection, the background run must be
active (without the N option), and a valid OS 2200 host user ID and password
combination must be used to establish the connection.
For CIFS levels prior to 6R2, the user ID passed to CIFS must be a valid OS 2200 user ID
and it must be authenticated with its matching OS 2200 password.
Beginning with CIFS level 6R2, CIFS accepts either OS 2200 user IDs or Windows
network user IDs if network authentication is configured through Messaging Integration
Services (NTSI). NTSI maps the network user ID to an OS 2200 user ID once it has
authenticated the network user ID.
CIFS supports both network and local authentication concurrently and transparently to
allow easy migration to the use of network authentication, while minimizing impact to
customers that do not wish to migrate. If all of the prerequisites for network
authentication are met, CIFS first attempts network authentication; if network
authentication fails, CIFS automatically tries local NTLM or NTLMv2 authentication.
The prerequisites for network authentication are
• Flexible User Authentication (FLEX, or User Authentication) is installed and the ASIS
background run is running.
• NTSI (Messaging Integration Services) Mode A is installed and configured.
The CIFS background run automatically detects the installation status of FLEX and NTSI
on startup. The K execute option can be specified on the @XQT of the background run
executable CIFS-BACK-Z to inhibit use of network authentication even when all of the
prerequisites are met.
The current status of CIFS network authentication can be found by using the CIFS
STATUS console keyin. This keyin displays either
− Network authentication is available
− Network authentication is not available
If network authentication is not available when the CIFS background run is initially
started, the background run must be shut down and restarted to detect a change in
network authentication availability.
9–12 7859 6137–009

Local OS 2200 Authentication
Administration
A valid OS 2200 host user ID and password combination must be used to establish the
connection. For access through Windows 95/98/Me, the user must also log onto the
workstation with the OS 2200 user ID, since those platforms do not support separate
workstation and network user IDs. The workstation password need not be the same as
the OS 2200 host password.
Passwords are not sent over the network. In ClearPath OS 2200 Release 7.1 and higher,
long passwords (up to 18 characters) are supported, and passwords are saved in hashed
form. The hash key is computed whenever a password is created or changed. When a
user attempts to sign on, CIFS uses the hash key to generate an authentication key, and
then uses the authentication key to verify the user’s password.
In releases lower than 7.1, CIFS uses the saved plain-text password (up to 6 characters
long) to generate an encryption key on a challenge string supplied to the client by the
SMB server within OS 2200 CIFS. The CIFS client sends the plain-text user ID and the
encrypted challenge to the server, where the encrypted value is compared to the one
calculated by the server.
(For more information, see “About Authentication and Passwords,” below.)
There are Windows registry settings that defeat encryption and result in the client
sending plain-text passwords over the network; this is not supported by OS 2200 CIFS.
For Windows 95/98/Me, the offending registry key is
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Service\VxD\Vnetsup
For Windows NT4, the key is
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Rdr\Parameters
For Windows 2000, XP, 2003, and Vista, the key is
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanWorkStation\Parameters
Ensure that either the registry key does not exist, or the value of
EnablePlainTextPassword under the key is zero. (The key and value names are not
case-sensitive.)
7859 6137–009 9–13

Administration
Network Authentication
Messaging Integration Services (NTSI) allows authentication against a Windows domain.
A user logged on at a workstation to a Windows domain can be authenticated to CIFS
using its Windows user name and credentials without having to enter a separate user ID
and password. NTSI supports authentication through both Kerberos and NTLM.
2200 Network Authentication is a Messaging Integration Services feature that allows
network users to be authenticated for access to an OS 2200 server against a Windows
domain instead of against the local OS 2200 security database. An OS 2200 Network
Authentication adapter supplied by Unisys running under the OS 2200 computer name
authenticates the network users on the Windows server using the Windows Security
Domain model instead of on the OS 2200 server.
To use network authentication with CIFS, the User Authentication product must be
installed and the NTSI product must be installed and configured. See the Messaging
Integration Services for ClearPath OS 2200 Help and ClearPath Enterprise Servers User
Authentication Administration Guide.
NTSI configuration allows selection of three Authentication Choices: Userid/Password,
Kerberos, and Windows NT LAN Manager (NTLM). Only Kerberos and NTLM are
relevant to CIFS. Either, both, or neither can be configured.
Note: This NTSI configuration is a system global specification. It applies to all
applications using NTSI, including CIFS and Demand/TIP signon.
This NTSI configuration is performed using Security Admin Security Client install and
update Network Authentication menu items.
9–14 7859 6137–009

Figure 9–1. Network Authentication Menu Items
Administration
The following paragraphs describe the various selections shown in Figure 9-1 that are
relevant to CIFS:
Authentication Choices
• Kerberos only - Microsoft Windows does not attempt Kerberos authentication if the
server is addressed by IP address or if an OS 2200 user ID and password are
supplied. If only Kerberos is configured, Windows 2000 and Vista users will not be
able to access CIFS. Windows XP users receive a LOGON Error on the initial attempt
to authenticate to 2200 CIFS because NTSI is not configured to perform network
NTLM authentication. If the user retries the logon attempt, 2200 CIFS attempts to
perform NTLM authentication against the OS 2200 user ID database.
Note: Unisys strongly advises that NTSI should not be configured specifying
Kerberos only.
• NTLM only - Microsoft Windows attempts NTLM authentication. If the user ID and
password specified by the user are an OS 2200 user ID/password, CIFS attempts
local NTLM authentication transparently if NTSI fails the authentication.
• Neither selected - CIFS treats this situation as if NTSI is not available and falls back
to performing native NTLM against OS 2200 user IDs only.
• Both selected - NTSI offers Kerberos and NTLM authentication during SMB protocol
negotiation. Microsoft Windows normally attempts Kerberos authentication and, if
necessary, falls back to attempting NTLM authentication. If the user ID and
password specified by the user are an OS 2200 user ID/password, Microsoft
7859 6137–009 9–15

Administration
Windows is unable to obtain a Kerberos ticket and thus immediately falls back to
attempting NTLM authentication.
Map Network Logon Name to Local Account by Matching
CIFS requires an OS 2200 user ID. NTSI provides the following methods of mapping
network user names to OS 2200 user IDs. These are
• Fully-qualified network logon name to local account network user ID
• Network account name to local account name exactly
• Fully-qualified name; if this fails, attempt account name exact match
Fully-qualified network logon name to local account network user ID
This option uses the Network User ID field in the OS 2200 user ID record to map the
network user name to the OS 2200 user ID. This is the recommended option.
In the example shown in Figure 9-2, the fully-qualified network user name
NA.UIS.UNISYS.COM\DOEJG is mapped to OS 2200 user ID JGD.
Note: As with OS 2200 user IDs, the Network User IDs must be unique; that is, only
one OS 2200 user ID can map to a Network User ID.
Network account name to local account name exactly
This option accepts a fully-qualified network user name (NA.UIS.UNISYS.COM\DOEJG)
and looks for an OS 2200 user ID (DOEJG).
Network Authentication Logging
CIFS uses the FLEX Authentication API AUTH_CONTEXT to perform network
authentication. FLEX generates type 17006 log entries for successful and unsuccessful
authentications. Windows clients often attempt to establish an IPC connection using a
null user ID. These connection attempts are always NTLM because Windows cannot get
a Kerberos ticket for a null user ID. FLEX and NTSI return an authentication failure for
these requests, which results in a subtype 2 17006 authentication failure log entry.
Note: Microsoft Windows clients do not attempt to perform Kerberos authentication if
the CIFS server is addressed by IP address (see KB 322979). To use Kerberos, the server
must be referenced by DNS name; then Microsoft Windows attempts to use NTLM, if
possible.
9–16 7859 6137–009

Figure 9–2. Example Fully-Qualified Network User Name
Administration
7859 6137–009 9–17

Administration
OS 2200 User ID Requirements
Each user ID that is used on any network connection must have first been made known
to OS 2200 CIFS through batch or demand. This is accomplished using @CIFSUT to
enter a simple command, such as pwd or cd that registers the user ID with OS 2200
CIFS.
Other OS 2200 CIFS requirements for user IDs are these:
• The user ID must not be disabled.
• For Fundamental Security systems where files are private by account, the user ID
must have at least one account listed in the OS 2200 user ID record.
• The first account in the OS 2200 user ID record must not be blank.
• OS 2200 CIFS uses the value q$q$q$ if the project from the OS 2200 user ID record
is missing or blank.
About Authentication and Passwords
The following table identifies the SMB authentication protocols supported by OS 2200
CIFS. CIFS 3R1 and later (starting with ClearPath OS 2200 Release 7.1) can use either of
the authentication protocols shown in this table, depending on the length and
case-sensitivity of the user’s password:
CIFS
Authentication
Protocol
cifs_lm_12 SMB
protocol
(NTLM 0.12)
cifs_pre_lm_12 SMB
protocol
(prior to NTLM 0.12)
Password/Authentication
Characteristics
MD4 message digest of the user’s
plain-text password, case-sensitive,
converted to Unicode. Long
passwords are supported. The
plain-text password is hashed and
saved. Machine-generated passwords
are permitted.
DES encryption of a constant using
the uppercased password as the key.
The plain-text password is saved.
Machine-generated passwords are not
permitted.
NTLMv2 A stronger enhancement to NTLM
developed by Microsoft that
significantly improves the
authentication security mechanism.
The key space for password-derived
keys is 128 bits. NTLMv2 uses the
same MD4 hash of the password as
cifs_lm_12 SMB protocol, but uses
this hash as the key to perform an
HMAC-MD5 hash.
CIFS Level Support
CIFS 3R1 and later
CIFS 3R1 and later
CIFS 6R2 and later
9–18 7859 6137–009

CIFS
Authentication
Protocol
Password/Authentication
Characteristics
NTLM2 A variant of NTLMv2 used by
Windows XP and later Microsoft
operating systems when extended
security negotiation is used and LAN
Manager Authentication Level is set to
Send LM & NTLM responses.
Administration
CIFS Level Support
CIFS 6R2 and later
If CIFS uses the cifs_pre_lm_12 protocol to handle a long password, it converts the
password to uppercase and allows only 14 characters. The following example illustrates
this case:
Example
If the user’s password is… …then only the following is accepted for authentication:
SIXTEENCHARACTER SIXTEENCHARACT
These are rejected:
SIXTEENCHARACTER
SIXTEENCHARACTXX
The following table shows how CIFS handles passwords on different release levels and
under different conditions:
CIFS
Level
3R1 and
later
3R1 and
later
3R1 and
later
ClearPath
Release
Level
7.1 and
later
7.1 and
later
Conditions Protocol Used
User ID record for the user accessing
CIFS is marked as having a
case-sensitive password, and a
cifs_lm_12 hash key is present.
User ID record is not marked as
having a case-sensitive password, or
no hash key is present (or both).
cifs_lm_12
cifs_pre_lm_12,
using only the
first 14 characters
of the password
Pre-7.1 N/A cifs_pre_lm_12,
using the
6-character
plain-text
password saved
in the user ID
record
7859 6137–009 9–19

Administration
CIFS
Level
ClearPath
Release
Level
Conditions Protocol Used
Pre-3R1 Pre-7.1 N/A cifs_pre_lm_12,
using the 6character
plain-text
password saved
in the user ID
record
LAN Manager Authentication Level
CIFS 6R2 and later allow Windows clients to be configured to inhibit use of LM and
NTLM authentication and allow only NTLMv2 to be used if Kerberos is not being used.
LAN Manager Authentication Level may be set to “Send NTLMv2 response only” when
using either Network Authentication or Local 2200 Authentication.
See Microsoft Knowledge Base articles 239869, 823659, and 147706.
You can also reference:
• http://www.microsoft.com/technet/security/prodtech/windowsxp/secwinxp/xpsgch0
3.mspx
• http://www.microsoft.com/technet/prodtechnol/winxppro/reskit/c16621675.mspx
• http://www.microsoft.com/technet/security/topics/serversecurity/tcg/tcgch05n.mspx
9–20 7859 6137–009

Environment Variables
Initial Values of Environment Variables
Administration
The site administrator might want to set the system’s initial values for environment
variables for CIFS (see Section 3 for the list) using the setsys command described in
Section 4 or through the PUT$ENV and GET$ENV interfaces as documented in the
System Services Programming Reference Manual. See the System Services
Programming Reference Manual and the documentation for the security management
product for more information about active and passive system profiles.
File I/O Buffer Cache
The default CIFS I/O buffer cache size is 64 megawords. This may be changed with the
CIFS$CACHE environment variable, which can be set globally in the CIFS-BACK
runstream, or in the CIFS-BACK user ID profile. The minimum value is 16 megawords,
and the value may be specified in words, kilowords, megawords, or gigawords.
Example
set CIFS$CACHE=1073741824
set CIFS$CACHE=1048576K
set CIFS$CACHE=1024m
set CIFS$CACHE=1G
The above are all equivalent. The variable name must be upper case; the multiplier suffix
is not case sensitive.
If necessary, CIFS may overflow the specified limit to hold unflushed data for written
files, but avoids the usage of the overflow area once the processing returns to normal.
The virtual space for the overflow buffers is not released back to the Exec, since it is not
being referenced, the system will page out the associated data from real memory when
other programs require it.
Communications Configuration Variables
By default, CIFS listens for network requests through the Communications Application
Program Interface installation mode A subsystem. You can select other or multiple
Communications Application Program Interface modes for CIFS by specifying the desired
mode letters in the CIFS$COMAPI environment variable for the CIFS background run.
For example, CIFS$COMAPI=FC tells CIFS to use Communications Application Program
Interface modes F and C for network connections. You may specify mode letters in any
order, in uppercase or lowercase. (But note that the variable name, CIFS$COMAPI, must
be uppercase.) CIFS gives a slight preference to the first modes in the string when
establishing listening connections.
You can specify the value of CIFS$COMAPI for the CIFS background run (CIFSB) in
several ways:
• Edit the CIFS-BACK runstream in SYS$LIB$*RUN$ to add a CIFSUT set command
for the CIFS$COMAPI variable. You can insert this command just before the existing
set command in the runstream that displays current environment variable settings.
7859 6137–009 9–21

Administration
• Establish a user profile for the CIFS background run’s user ID, and insert the
CIFS$COMAPI setting there. Note that CIFSB must always run with this specific
user ID for this method to be effective.
• Add the CIFS$COMAPI setting to the system profile, making it available to all runs in
the system. Be sure to update both the active and passive profiles when changing
the value.
File Assignment, Equipment Type, Size, and Placement
By default, CIFS creates OS 2200 data and program files on fixed mass storage, using
F///262143 for equipment type and maximum size. A site administrator can specify
alternative settings with the CIFS$CAT variable, including removable disk pack IDs, if
desired. When used in the CIFS background run, the CIFS$CAT settings are applied to
CIFS system files and any files created in response to network client requests. When
used in the system profile, the CIFS$CAT settings apply to all runs, including TIP
transactions and the CIFS background run. However, an individual batch or demand run
can override the global setting by establishing its own value for the variable.
When attempting to access rolled out or exclusively assigned OS 2200 files, you can
control the CIFS behavior with the CIFS$WAITROLBAK and CIFS$WAITXUSE variables.
The default values are 600 (10 minutes) and 0, respectively.
The variables can be set to the number of seconds to wait for file availability, if the
open() request triggering the assign has the O_NONBLOCK flag bit clear. As with
CIFS$CAT, variables visible to the background run affect CIFS system files and network
access. Batch and demand runs can override any global settings.
Time-Dependent Environment Variables
The OS 2200 operating system does not handle time zones or daylight savings time as
other systems do, yet CIFS access through the network depends on and references
Coordinated Universal Time (UTC). Therefore, there is a dependency on two
environment variables, TZ and TIMEBASE, which establish time relationships.
Proper client-server interaction requires that the background run be invoked with these
variables in place and with values that represent the desired relationship between the
system dayclock and UTC. The set and setsys commands of @CIFSUT are a convenient
means by which to set these variables.
The following example shows how a runstream can be used to set a variable for a
system in the central time zone running with a system dayclock set 6 hours behind UTC.
...
@CIFSUT
set TZ=CST6CDT
set TIMEBASE=6
@EOF
...
9–22 7859 6137–009

The TZ Environment Variable
Administration
The TZ environment variable is part of the normal user environment on systems similar
to Unix and specifies:
• The time zone.
• The relation of local time to standard time at the prime meridian.
• The dates to change between standard time and daylight saving time.
If the TZ variable is not in the environment, the UTC time zone is assumed.
Format
TZ=StdOffset[dst[Offset],[start[/time],end[/time]]]
where:
Std
Offset
dst
is three or more characters for the name of the time zone during standard time, for
example, CST for central standard time. This field is required. Any characters are
valid except digits, plus (+) and minus (-) signs, or a comma (,).
indicates the difference between local time and UTC (the value to add to local time
to obtain UTC). Offset has the form [+|-]hh[:mm[:ss]].
An optional “+” or “- “sign may precede the first digit. Time zones east of the prime
meridian and west of the international date line need a leading minus sign. Time
zones west of the prime meridian are indicated by an optional preceding plus sign.
hh indicates the number of hours on a 24-hour clock. Its value is one or more
decimal digits in the range 0 through 24. mm, if included, indicates the number of
minutes. Its value is one or more decimal digits in the range 0 - 59. ss, if included,
indicates the number of seconds. Its value is one or more decimal digits in the range
0- 59. The ss field cannot exist if mm does not exist.
The Offset following Std is required.
is three or more characters for the name of the time zone during daylight savings
time, for example, EDT for eastern daylight time. This field is optional. If dst is not
included, then daylight savings time does not apply in this locale. Any characters are
valid except digits, plus (+) and minus (-) signs, or a comma (,).
The Offset following dst is optional. If no Offset follows dst, daylight savings time is
assumed to be one hour ahead of standard time.
7859 6137–009 9–23

Administration
start /time, end /time
Jn
n
start /time indicates the day and time to change from standard time to daylight
savings time. end /time indicates the day and time to change from daylight savings
time to standard time. Each time field indicates the time of day, in current local time,
the change is made. The time fields have the same format as the Offset fields,
except that no leading plus or minus field is allowed. If a time field is not included, it
has the default value of 02:00:00.
The start and end fields are optional. Implementation-specific defaults are used if
they are not specified. The start and end fields have one of the following formats:
where n represents the day of the year, except leap day. The value of n ranges from
1 through 365. Leap day is not represented. February 28 is always day 59 and March
1 is always day 60. It is impossible to refer to the occasional February 29.
where n represents the number of days since January 1. The value of n ranges from
0 through 365. February 28 is day 58. March 1 is either day 59 or 60, depending on
whether the year is a leap year.
Mm.n.d
where:
m represents the month; values range from 1 through 12.
n represents the week of the month; values range from 1 through 5. If n is 5, the
date references the last day of the month.
d represents the day of the week; values ranges from 0 through 6. Day 0 is Sunday.
The date indicated is the nth d day of month m.
Example
TZ=CST6CDT,M4.1.0,M10.5.0
This code indicates the following time-zone values:
• The standard time designator is CST (Central Standard Time).
• Standard time is 6 hours behind UTC.
• The daylight savings time designator is CDT (Central Daylight Time).
• Daylight savings time is 5 hours behind UTC.
9–24 7859 6137–009

Administration
• The time-zone designator switches from CST to CDT on the first Sunday in April at
2:00 A.M. standard time.
• The time-zone designator switches from CDT to CST on the last Sunday in October
at 2:00 A.M. daylight savings time.
TIMEBASE Environment Variable
The TIMEBASE environment variable is unique to the OS 2200 system. Most systems
similar to UNIX set their internal clock to UTC, but that is usually not true for OS 2200
systems. Traditionally, most OS 2200 systems set their internal clock to local time,
which can include biases for the time zone and daylight savings time. The TIMEBASE
environment variable specifies the relationship between UTC and the site's system
dayclock.
If the TIMEBASE variable is not present, CIFS assumes that the dayclock is set to local
time, as indicated by the TZ variable setting. If the TIMEBASE variable is present, CIFS
always interprets a value of 0 as an indication that the site is running UTC in the
dayclock, regardless of the TZ variable setting.
Consequently, if a site is operating with a local time in the dayclock that has an offset of
0 from UTC, the TIMEBASE variable must be omitted. Otherwise, CIFS performs an
incorrect conversion on times outside of the current standard or daylight time period.
Format
TIMEBASE=offset
where offset indicates the amount of time that the system dayclock varies from UTC and
has the form [+|-]hh[:mm[:ss]]
An optional “+” or “-“ sign may precede the first digit. Time zones east of the prime
meridian and west of the international date line need a leading minus sign. Time zones
west of the prime meridian are indicated by an optional preceding plus sign. hh indicates
the number of hours on a 24-hour clock. Its value is one or more decimal digits in the
range 0 through 24. mm, if included, indicates the number of minutes. Its value is one or
more decimal digits in the range 0 through 59. ss, if included, indicates the number of
seconds. Its value is one or more decimal digits in the range 0 through 59. The ss field
cannot exist if mm does not exist.
Example
TIMEBASE=6
TZ=CST6CDT
This code specifies the following:
• During standard time, the system dayclock is 6 hours earlier than UTC.
• During daylight savings time, the system dayclock is 5 hours earlier than UTC (since
we know that TZ=CST6CDT).
7859 6137–009 9–25

Administration
But if the dayclock changed during CDT, then the TIMEBASE variable must be changed
as well:
TIMEBASE=5
TZ=CST6CDT
File Filtering
File filtering provides site administrators with the capability to control access to the 2200
file system through CIFS by implementing site file system policy in local code that
executes within the CIFS subsystem. This can be useful, for example, in a consolidated
server environment, where users from previously independent systems with identical
application environments are now operating on a single host, yet must continue to
reference separate sets of files. In such a situation, file filtering can adjust the names in a
user’s file requests to insure that segregation of application data continues.
Filtering is implemented by a set of APIs called by the CIFS subsystem to enforce the
site policy. These APIs are fielded by the FILTER object module (OM) in the CIFS
subsystem file (SYS$LIB$*CIFS$SS). To employ filtering, perform the following steps:
1. If it is running, deactivate the CIFS subsystem.
2. Change SYS$LIB$*CIFS$SS to write-enabled, if it is not already.
3. Replace the FILTER object module supplied by Unisys with one or more OMs that
implement the site file system policy through the APIs described below. (If none of
the site OMs is named FILTER, the Unisys one must be deleted.)
4. Pack and prep SYS$LIB$*CIFS$SS.
5. Start CIFS-BACK. The replacement OMs are automatically loaded during the CIFS
subsystem activation.
The three APIs that a site must implement to enable file filtering are briefly documented
below. For details about the interfaces, including parameters and return values, consult
the FILTER/H header file in SYS$LIB$*CIFS$SS.
• filter_userid() – Determines whether a particular combination of user ID, account,
and project is subject to file filtering; called during creation of the internal process
descriptor structure for each process as it registers with CIFS.
• filter_check() – Determines whether a particular qualifier and filename must be
visible to a given CIFS user; called during scans of the directories /os2200 and
/os2200/ (or equivalent network shares) to eliminate passing back entries the
site does not want this user to access.
• filter_apply() – Modifies a particular qualifier and filename requested by a user, as
determined by site file system policy. Called during path resolution and file creation
for /os2200// and /os2200/ or when a name from
the CIFS$NEXTFILE environment variable is used.
9–26 7859 6137–009

Administration
The carefully controlled execution environment of the CIFS subsystem imposes certain
restrictions on how a site’s filter code can be implemented. In particular, the header file
“universal.h” MUST be included first in any UC-based filter OMs, and site-supplied code
must use only the APIs available through the header files supplied in
SYS$LIB$*CIFS$SS. Site-supplied code must not call outside of the CIFS subsystem,
other than to the Exec. This prohibition includes any URTS or UC library functions not
specified in the supplied header files.
To build a module for file filtering, you must observe the following points:
• Do an @USE UC$PF,SYS$LIB$*CIFS$SS before any compilations.
• Make #include “universal.h” the first include in every compilation.
• Any or all of the additional header files from SYS$LIB$*CIFS$SS may also be
included, but they must be referenced with quotation marks, not angle brackets.
• Do not call any interfaces outside of the ones supplied by your filter OMs other than
Exec entry points or those in the supplied header files.
• If any compiler other than UC is used, it must conform to UC register conventions
and the limitations listed above.
Examine the header files in SYS$LIB$*CIFS$SS for details about what interfaces are
available to filtering code.
7859 6137–009 9–27

Administration
9–28 7859 6137–009

Appendix A
Limitations, Considerations, and
Restrictions
Limitations
The CIFS level 6R3 release has the following limitations, considerations, and restrictions.
• CIFS cannot perform I/O to portions of files beyond byte 34,359,738,367. This is
equivalent to 4,793,490 OS 2200 tracks or 74,898 positions. This is a limit imposed
by the 2200 36-bit architecture and the POSIX API specification that uses a signed
integer field to hold the byte offset in a file. The byte offset overflows a 36-bit word
and goes negative above 74,898 positions.
• CIFS path names are limited to a total of 1,046,496 bytes.
• CIFS path name components (directory and file names) are limited to 4,095 bytes.
• The maximum number of concurrently open files for a process is 2,048. Due to this
limit, certain CIFSUT functions (for example, deltree and rm –r) will not complete
normally if the number of nested directories causes the open-file limit to be
exceeded.
• Environment variables cannot be set by transaction processing (TIP) programs.
• A share name cannot be more than 31 characters long.
Considerations
Note: Many network clients cannot access share names with more than 12
characters.
These considerations apply:
• CIFS uses a large amount of virtual memory in order to cache file data. This
consumes a significant number of application-level Bank Descriptor Indices (BDIs)
and can impact the availability of BDIs to other programs. Consequently, Unisys
strongly recommends that sites set the Exec dynamic configuration parameter
apl_bank_bdi_gt4k (short name APLBDIGT4K) to TRUE. This allows CIFS to allocate
its data banks from the 28,000 slots in the upper BDI range rather than from the
4,000 in the lower range. The amount of memory used by the file cache can be
specified by the CIFS$CACHE environment variable.
• The ZIPUT processor is written primarily in the Java language. Use of ZIPUT requires
that the Virtual Machine for the Java Platform on ClearPath OS 2200 product be
installed. This product is known informally as the 2200 JVM.
7859 6137–009 A–1

Limitations, Considerations, and Restrictions
• CIFS supports SMB clients that utilize long file names, including Windows 95/98/Me,
Windows NT4/2000/XP/2003/Vista, jCIFS, and Samba. Because of this, some
commands entered from the DOS command prompt under Windows 95/98/Me
might not be usable. For example, the dir and copy commands fail because they rely
upon fixed-length 13-character fields to hold file names. The DOS command prompt,
under Windows 95/98/Me, can be used for launching programs that use the Win32
APIs, such as Notepad, WordPad, Java compiler, and so on, that use files on drives
mapped to CIFS directories. In addition, redirection to or from a CIFS directory is
supported. For example, the more command can be used to display the contents of
a file. Other commands might or might not work depending on the client software's
implementation and reliance upon 8.3 style file names. Windows
NT4/2000/XP/2003/Vista does not have these restrictions. All commands to the
command prompt (shell) under Windows NT4/2000/XP/2003/Vista should function.
• When you use Windows NT4 to access CIFS, Service Pack 4, 6a, or higher is
recommended. (Service pack 5 can have connection problems when using IP
addresses.)
• Files in the CIFS file system might consume more physical disk space than
previously used in OS 2200. This is because CIFS always allocates all physical disk
space, which differs from OS 2200. For example, in OS 2200, if you do not write a
file sequentially from the beginning, OS 2200 can leave unwritten areas of the file
unallocated; CIFS allocates all areas of the file.
• If read/write keys are used on container files for CIFS directories, and directories are
nested, you cannot perform a change directory across multiple directories unless the
read/write keys are the same. Instead, you must do individual change directory
commands after setting the CIFS$KEYS environment variable for each directory
individually. Example (assume a path of /dir-a/dir-b/dir-c):
@CIFSUT
set CIFS$KEYS=dirak1
cd /dir-a
SET CIFS$KEYS=dirak2
cd /dir-b
SET CIFS$KEYS=dirak3
cd /dir-c
• Read/write keys cannot be used over network connections to CIFS because the
protocol does not provide a means of specifying them. Consequently, great care
must be taken on Fundamental Security systems to balance accessibility and
vulnerability. Moving to Security Option 1 or higher and using Access Control
Records on files is strongly recommended.
• The Communications Application Program Interface configuration impacts CIFS. For
example, CIFS uses up to 65 activities to handle network access through each
instance of Communications Application Program Interface. Make note of this when
configuring the MAX_USERS_TCP value in Communications Application Program
Interface.
• The host name can be expressed as a shortname (for example, rs06), fully qualified
name (for example, rs06.rsvl.unisys.com), or an IP address. Depending on the client
and the local network configuration, any or all of these will work.
A–2 7859 6137–009

Limitations, Considerations, and Restrictions
• When a CIFS file is updated by an application, any existing SDF record structure
remains unchanged. Therefore, if new record delimiters (ASCII newline characters)
do not exactly overwrite existing delimiters, the resulting file might not make sense
if read outside of CIFS. Copying such a file with CIFSUT to another location will
rebuild the SDF record structure, making the file readable by standard OS 2200
programs.
• Dates prior to 1980 cannot display correctly in SMB client programs such as
Windows Explorer due to inherent restrictions with the SMB protocol.
• Files accessed through CIFS are normally stored as SDF elements in OS 2200
program files. The environment variable, CIFS$NEXTFILE, can be used to force
storage in a data file, if required. The SDF format is transparent to network clients
and programs using the CIFS APIs because on read operations, CIFS always returns
the exact byte sequences supplied on write requests. To facilitate data access by
programs using traditional OS 2200 I/O mechanisms, CIFS interprets various line
termination sequences as record breaks.
− A single line feed (0x0A): the Linux/UNIX standard, compatible with UCS
Runtime System I/O handling
− A carriage return, line feed sequence (0x0D and 0x0A): typically used by
Windows text files
− A single carriage return (0x0D): the normal Apple Mac OS line terminator
Files using terminators other than a plain line feed can be filtered to make them
compatible with Linux/UNIX based programs through the w-option of the CIFSUT CP
and COPY commands. There is no limit on record length, though files are limited to
approximately 29 MB when stored as standard OS 2200 elements (34 GB in LEPF).
• Using cpFTP to transfer files created by CIFS can corrupt the data at the receiver
unless extreme care is taken with the procedure. Any files to be sent through cpFTP
must first be converted to binary using the CIFSUT cp -b or binjar commands. Once
this is done, the cpFTP mode must be set to binary and, if the CIFS file is stored as
an element, set ftype to OMN. This insures that critical information (such as data
bytes with values equal to carriage return or line feed) are not discarded or modified
during the transfer. Using the CIFS client to transfer data to another system requires
no such considerations.
• CIFS automatically converts the program file that is associated with a directory to a
Large Program File (LPF) if the Table of Contents (TOC) of the program file fills-up.
This conversion can occur both for implicitly-created program files and for files at the
/os2200/qual/file level of the directory hierarchy (whether they are created by CIFS or
not ). A normal program file TOC can hold entries between 2671 to 5000 entries,
depending on whether there are Assembler/COBOL/Fortran PROC entries or a
relocatable entry point table existing in the program file. An LPF can hold up to
26146 TOC entries. A program file is not converted to an LPF if the TOC has deleted
element entries in it. This is because a pack is done on the file and this recovers the
space for those deleted entries. Note that a FURPUR @PACK,M cannot be done on
an LPF. If you want to compress the program files for your directories using
@PACK,M, ensure that the directories have less than 5000 elements in them so that
they are not converted to LPFs by CIFS.
7859 6137–009 A–3

Limitations, Considerations, and Restrictions
Restrictions
• CIFS also automatically packs the underlying program file for a directory if the TOC or
the text area of the program file fills up and an overflow could occur that might result
in truncation of user files(elements). The pack recovers space for the deleted TOC
entries and for text space that is allocated for deleted elements in the program file.
The CIFSUT touch command with the -p option will also pack the program file
associated with a directory. Using the -pr options with touch (adding the recursive
option) will pack all the program files for a directory tree.
• CIFS can create Large Element Program Files (LEPFs) using the CIFSUT command
mkdir or the C program interface mkdir(). CIFS creates LEPFs as needed for CIFS
implicitly created containers (ones created by CIFS not at the /os2200/qual/file level
of the directory hierarchy and not explicitly specified using CIFS$NEXTFILE). Such
automatic LEPF creation occurs only when the element to be written is larger than
262,143 sectors and the existing container is not already an LEPF. CIFS can also
work with existing LEPFs. If you use CIFSUT to copy or move a directory that has an
LEPF container associated with it, and the corresponding directory at the target
location does not exist, then the new directory default container is created as normal
program file. However, any files within the container that are larger than the normal
element limit are placed in the automatically created auxiliary LEPF containers.
These are the restrictions applied to:
Note: On CIFS level 3R1 (ClearPath OS 2200 Release 7.1), the restriction against
machine-generated passwords was removed. The restriction still exists on lower levels.
• Files larger than 262,143 tracks cannot be copied or moved by CIFSUT.
• CIFS does not maintain an 8.3 format alias for long file names.
• Programs that use the 8.3 file naming interfaces might experience problems
interacting with CIFS. This includes, but is not limited to, the dir command of the
DOS shell running under Windows 95/98/Me.
• If a symbolic element is cycled, CIFS provides access only to the current cycle. Data
in older cycles is not available.
• Windows Explorer cannot be used to create directories one or two levels below
/os2200 because Windows uses “New Folder” for the initial name. The space in
“New Folder” conflicts with Exec file naming requirements. Directories at these
levels can be created from the command prompt, or through Windows APIs.
• Some desktop applications, including Microsoft Word, cannot be used to manipulate
OS 2200 data files because they attempt to create temporary files in the
/os2200/qualifier directory that are not valid OS 2200 file names. These applications
operate successfully on OS 2200 elements, or on any files not in the /os2200
directory hierarchy.
• Calling CIFS from a protected subsystem can be problematical. First, any activity
calling CIFS from a protected subsystem must first call CIFS from the home
subsystem, or never call CIFS from any subsystem (including home) other than that
protected one. Second, any CIFS files opened by a protected subsystem are
accessible by all activities of the run that performed the open() requests, even when
they are not executing in the protected subsystem. This restriction will be removed
in a future level.
A–4 7859 6137–009

Limitations, Considerations, and Restrictions
• CIFS does not currently detect file name changes made by @CHG,N. Direct access
to the new name results in CIFS becoming aware of the file, but the old name
remains. Running CIFS-POP corrects the discrepancy. This restriction will be
removed in a future level.
• If network authentication is not installed when the CIFS background run is initially
started, the background run must be shut down and restarted to detect a change in
network authentication availability.
• Files whose type is not yet known are not visible over network connections. The
SMB protocol does not allow for an unknown or “none-of-the-above” file attribute,
so some batch or demand CIFS operation must be performed on such a file to
establish the type before it can be used from the network.
• When accessing CIFS from a Windows Vista workstation, the lmcompatibility setting
in the registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa
must have a value less than 2 unless FLEX and NTSI are installed and operational.
7859 6137–009 A–5

Limitations, Considerations, and Restrictions
A–6 7859 6137–009

Appendix B
Error Codes
Error Code Description
2 Object with specified name does not exist.
3 No such process.
5 Input/output error.
12 Not enough space.
13 Access permission denied.
22 Invalid argument.
24 Too many open files.
27 File address too large.
33 Domain error.
34 Result too large.
222 Argument list too long.
224 Resource temporarily unavailable.
225 Invalid file descriptor.
226 Resource busy.
227 No child processes.
228 Waiting for resource would cause deadlock.
230 Object already exists.
231 Addressing exception.
233 Interrupted function call.
236 Is a directory.
238 Too many links.
239 Name is too long.
240 Too many open files in system.
241 No such device.
243 Is not an object file.
244 No locks available.
7859 6137–009 B–1

Error Codes
Error Code Description
246 No space left on device.
247 Function not implemented.
248 Is not a directory.
249 Directory is not empty.
250 Inappropriate I/O control operation.
251 No such device or address.
252 Operation not permitted.
253 Broken pipe.
255 Read-only file system.
256 Pipe is an invalid file type for lseek.
258 Attempt to link across different file systems.
701 BSP$ error: specified length of FCT is less than minimum required.
702 BSP$ error: file is not a program file.
703 BSP$ error: specified interface level not supported.
704 BSP$ error: file is not sector formatted or TOC is corrupt.
705 BSP$ error: program file revision level not supported.
706 BSP$ error: specified size indicator is illegal.
707 BSP$ error: no starting sector address for large program file table.
708 BSP$ error: program file does not contain a valid size indicator.
710 BSP$ error: FTI not in memory.
711 BSP$ error: no starting sector for large program file table.
712 BSP$ error: sequence number out of range.
718 BSP$ error: specified table not in memory.
720 BSP$ error: buffer too small.
721 BSP$ error: buffer too large.
734 BSP$ error: at least one table not written back.
735 BSP$ error: invalid next sector for text.
736 BSP$ error: no room in file to create table entry.
737 BSP$ error: attempt to change item size.
738 BSP$ error: illegal element type for large element program file.
739 BSP$ error: illegal element length granularity for large element program
file.
822 CIFS not initialized.
823 Not enough system memory.
B–2 7859 6137–009

Error Code Description
824 OS 2200 facility rejection.
825 Not enough stack space.
826 Process table entry already exists.
827 Internal error.
828 The underlying file is corrupt.
829 CIFS initialization failed.
830 Error on file assignment switch.
831 You are not permitted to use CIFS.
832 Attempt to process an invalid SDF file or update an SDF file not
produced by CIFS.
834 Imported file name is not valid OS 2200 file name.
835 ERESTART error.
838 Operation not allowed at the current position in the CIFS directory
hierarchy.
839 OS 2200 F-cycle has been dropped.
Error Codes
840 The path name contains characters not allowed in CIFS file or directory
names.
841 A fatal error occurred within the CIFS kernel.
842 Unlink not allowed in /os2200 directory hierarchy if link count not equal
to two for program files or one for non-program files.
843 The CIFS background run is already active. Only one copy of the
background run allowed at one time.
844 An error occurred during CIFS library initialization.
845 A limit imposed by the 2200 architecture, OS 2200, or the CIFS
implementation has been exceeded.
846 Object already exists.
847 The CIFSB background run is not active when it is required.
848 The Coded Character Set name is not known to CIFS.
849 The specified network path cannot be found.
850 Remote authentication failed with the given network userid/password.
851 Request not completed due to network error.
852 Network path not permitted for this function.
853 No password available for network authentication.
854 Function could not be completed by network server.
855 Cross-linking not allowed for elements in program files.
856 MSCP interface cannot be initialized.
7859 6137–009 B–3

Error Codes
Error Code Description
901 Files may not be created in the /os2200 directory.
902 Directories may not be created at this level in the /os2200 directory
hierarchy.
903 Unknown file type.
904 Links may not be created in the /os2200 directory hierarchy.
905 This functionality has not yet been implemented in CIFS.
906 CIFS$NEXTFILE directed file cannot be created in an implicitly created
program file directory.
908 A fatal error occurred attempting to populate a program file directory.
909 CIFS$NEXTFILE may not be used when creating files or directories in
the /os2200 hierarchy.
910 ER SUMOD$ SYS$*SACRD$ I/O error.
911 ER SUMOD$ error 01240. File specified in the packet is not assigned or
is a removable disk pack file assigned with the Y option.
912 ER SUMOD$ error 01241. An attempt was made to perform a
modification without possessing the proper privilege or privileges.
913 ER SUMOD$ error 01242. New clearance level does not lie in modifier's
clearance level range.
914 ER SUMOD$ error 01243. To-be-attached ACR does not exist.
915 ER SUMOD$ error 01244. Invalid data specified in packet.
916 ER SUMOD$ error 01245. MFDF contains bad links.
917 ER SUMOD$ error 01246. MFDF I/O error during read/write of file's
lead or main item.
918 ER SUMOD$ error 01247. Attached ACR does not exist for the
specified owner.
919 ER SUMOD$ error 0540. User ID specified does not exist in
SYS$*SACRD$.
920 ER SUMOD$ error 0542. User ID specified has been deleted.
921 ER SUMOD$ error 01252. Bad packet length.
922 ER SUMOD$ error 01253. New compartment set is not a subset of
modifier's compartment set.
923 Request requires the CIFS Security Server to complete, and the
Security Server activity of the CIFS background run is not active.
924 ER SUMOD$ error 01255. Attempt to modify privilege mask by a
requestor not possessing the privilege to do so.
925 ER SUMOD$ error 01256. Attempt to modify interface mask by a
requestor not possessing the privilege to do so.
926 ER SUMOD$ error 01257. Modifier failed write object security record
access.
B–4 7859 6137–009

Error Code Description
Error Codes
927 ER SUMOD$ error 01260. Attributes of the new owner and the object
are not compatible.
928 ER SUMOD$ error 01261. Ring number, subsystem level designator bit,
and ACR count fields may be modified only when the user ID record is
owned.
929 ER SUMOD$ error 01262. Unowned shared file cannot have an ACR.
930 ER SUMOD$ error 01263. Value specified for maximum ACR is out of
bounds for the object or its owner.
931 ER SUMOD$ error 01264. Owner of object and owner of ACR must be
the same.
932 ER SUMOD$ error 01265. The ring number, subsystem level, or
designator bits are not in the owner's range.
933 ER SUMOD$ error 01266. New owner does not exist or is deleted.
934 ER SUMOD$ error 01267. The default compartment set is not a subset
of the maximum compartment set.
935 ER SUMOD$ error 01270. The table version number has changed and
has affected the supplied bit mask.
936 ER SUMOD$ error 01271. ER SUMOD$ can only be performed by the
home subsystem.
937 ER SUMOD$ error 01272. On Security Option 3 systems, when
changing clearance level or compartment set, the file must be
exclusively assigned unless it is in the to-be-catalogued state.
938 ER SUMOD$ error 01273. On Security Option 3 systems, when
changing clearance level or compartment set, only the caller can have
other F-cycles assigned.
939 ER SUMOD$ error 01274.
940 Cannot mkdir with an existing Q*F specified via CIFS$NEXTFILE unless
the current link count equals 2.
941 Cannot mkdir with an existing Q*F specified via CIFS$NEXTFILE unless
Q*F is a program file.
942 CIFS encountered a conflict between a temporary file assigned to the
caller's home name section and the cataloged file CIFS was requested
to create.
943 CIFS failed unowned file private by account check.
944 CIFS failed unowned file private by project-id check.
945 Failed CIFS read key check.
946 Failed CIFS write key check.
947 Failed CIFS security check due to data in the lead item or main item
being slashed.
948 An invalid OS 2200 MFD name was specified via CIFS$MFD.
7859 6137–009 B–5

Error Codes
Error Code Description
949 An error occurred while CIFS was getting or putting an OS 2200
environment variable.
950 Failed CIFS ER SUVAL$ security check.
951 File has read-only access and request requires write access.
952 Security check could not be performed due to G option file. CIFS does
not support private unowned G option files or G option files with
read/write keys.
953 CIFS$ACR other than PUBLIC or PRIVATE not valid on FUNDAMENTAL
Security systems.
954 File size exceeds the CIFS maximum file size of 74898 OS 2200
positions.
955 Rename of qualifiers or file names in the /os2200 directory hierarchy is
not allowed.
956 Files may not be created in the root directory, only directories.
957 File has write-only access and request requires read access.
960 Populate (of the /os2200 directory) failed. The CIFS directory will not be
in sync with the OS 2200 MFD.
961 Populate is already running. Another run must be active.
962 A request to the security server completed with status indicating it is
still in progress.
963 File was rolled out and ROLBAK inhibit was specified.
964 CIFS attempted to assign a file and received status indicating the file
was already assigned to CIFS.
2000 : Operations on . or .. not allowed.
2001 : Cannot change to directory .
2002 : Cannot create directory .
2003 : Failure to get working directory.
2004 : Insufficient memory.
2005 : Cannot remove directory .
2006 : Directory not empty.
2007 : Cannot remove . or .. directory entries.
2008 : Unable to access object .
2009 : Cannot open directory .
2010 : Cannot close directory .
2011 : is a directory.
2012 : Cannot remove file .
2013 : Cannot change to parent directory during directory
B–6 7859 6137–009

Error Code Description
traversal.
2014 : Environment variable does not exist.
2015 : Either setting or retrieval of the environment variable
failed.
2016 : Changing network share name failed.
2017 : Copying multiple sources to a file
2018 : Target not found.
2019 : Target contains mask characters.
2020 : Target same as source.
2021 : Cannot create file .
2022 : Cannot change user id.
2023 : Cannot set file access time and modification time on
.
2024 : Cannot set mode on .
2025 : Cannot open file .
2026 : File I/O error.
2027 : Option -r must be specified.
2028 : Get stat on failed.
2029 : Cannot close file.
2030 : Attempt to link multiple sources to a file.
2031 : Link of two directories not allowed.
2032 : Attempt to link two existing files without -f specified.
2033 : Link file fail.
2034 : No filename specified with /s option.
2035 : Error reading directory.
2036 : More than one entry matches the mask.
2037 : is not a directory.
2038 : Attempt to move the source directory to itself.
2039 : Cannot create directory .
2040 : Cannot change owner on .
2041 : Cannot get uid from .
Error Codes
2042 : Share name may not be useable due to length of
more than 12 characters.
2043 : Error retrieving CIFS subsystem identity.
2044 : Error switching to kernel root directory.
7859 6137–009 B–7

Error Codes
Error Code Description
2045 : @use name is longer than 12 characters.
2046 : Path has no file-level container.
2048 : Cannot move file .
2049 : Specific file requested with recursion or
extensions.
2050 : Specified file is not SDF format.
2051 : Rename of failed.
2052 : Specified extension () must not
be null or all periods.
2053 : Time conversion error; value must be in
"[[CC]YY]MMDDhhmm[:ss]" format.
2054 : Option conflict; cannot specify both the
-e option and the -n option.
2055 : Cannot create FIFO .
2056 : Cannot create FIFO .
2057 : CIFS requires exclusive access to pack directory
. Even your CIFSUT run cannot have the backing program file
assigned.
3000–3034 ZIPUT error and warnings.
100000 Unrecognized errno: .
B–8 7859 6137–009

Glossary
/
/os2200 directory
The directory in CIFS that contains an image of all files in the OS 2200 MFDs. Contrast
with non-/os2200 directory.
A
absolute (.abs)
An OS 2200 element type. CIFS recognizes the file name extension .abs as indicative of
an executable element.
absolute reference
A file path name reference that begins with a slash, indicating the root directory.
access control record (ACR)
A record containing lists of users and the user access to a file, tape, or subsystem, and
the conditions under which those users are allowed that access. You create ACRs by
using SIMAN. Attaching an ACR to an object makes it semiprivate.
application program interface (API)
The interface (calling conventions) by which an application program accesses CIFS
services. An API is defined at source code level and provides a level of abstraction
between the application and CIFS to ensure the portability of the code.
ASCII
B
byte
Abbreviation for American Standard Code for Information Interchange: an 8–bit code
used to represent data and certain control functions (such as a carriage return). ASCII is
used in both computers and data communications. Unlike Fieldata, ASCII can represent
both uppercase and lowercase letters, as well as numbers and special characters.
Smallest granularity of file storage that CIFS manipulates. Bytes in OS 2200 are 9 bits
wide, but only 8 bits on communications networks.
7859 6137–009 Glossary–1

Glossary
C
clearance level
A hierarchical classification for objects. Clearance levels can range from 0 to 63, with 63
being the most restrictive. Clearance levels can also be associated with symbolic labels
such as unclassified, classified, secret, and top secret.
Common Internet File System (CIFS)
CIFS is a file system that allows access to OS 2200 files through standard Internet
protocols. The CIFS specification was created by Microsoft Corporation and is based on
the existing Server Messages Block (SMB) protocol.
control statement
An instruction (such as in ECL and FURPUR) that directs the processing of a run. Control
statements begin with a masterspace (@).
current working directory
The directory that the user is currently in. The current working directory can be displayed
with the pwd or cd CIFSUT commands.
cycle
E
element
One of the stages a file or symbolic element goes through as it is updated. Cycles of
files are called file cycles or F-cycles; cycles of symbolic elements are called element
cycles or S-cycles. Each cycle can be identified with either an absolute cycle number,
which never changes, or a relative cycle number, which changes as new cycles of a file
or element are created.
A part of a program file or element file, usually used to store a program or subprogram.
Elements can contain either symbolic images or binary data such as machine-language
instructions.
Executive or Exec
A software program on OS 2200 systems that processes user runs, controls files,
manages system resources, and performs input/output operations for the user. The
Exec, along with the System Control Software products, provide the
hardware-independent environment in which other OS 2200 products execute.
F
Fieldata
file
A 6-bit character set originally developed for Unisys forerunner systems. It includes
neither lower case letters nor any control characters.
An organized collection of data, treated as a unit and stored so as to facilitate the
retrieval of each individual data item. Files are retained on auxiliary storage devices.
Glossary–2 7859 6137–009

Glossary
file cycle (F-cycle)
A generation (version) of a file. A new cycle of a file is created by using the relative cycle
number +1. File cycles are sometimes called F-cycles.
FURPUR
Abbreviation for File Utility Routines/Program File Utility Routines.
H
host
host-id
I
inode
A host consists of a main storage memory, unique (local) peripheral and central complex
devices, and operating system software.
A single character (A, B, C, or D) that an OS 2200 identifies a host within a Multi-Host
File Sharing system.
An internal structure used to manage each file in the system. Information from an inode
can be retrieved by using the ls and dir commands or the stat() and istat() functions.
input/output (I/O)
The process of transferring information between the processor and peripheral devices.
I/O devices include magnetic tapes, magnetic disks, consoles, card readers, printers, and
punches.
K
keyin
M
A sequence of characters entered from a console that requests information or tells the
Exec to perform certain tasks.
master file directory (MFD)
The file catalog of the Exec. It is a directory maintained by the Exec to control permanent
files. Files listed in the MFD are said to be cataloged and are retained even after a run
terminates.
7859 6137–009 Glossary–3

Glossary
N
node
A system component.
non-/os2200 directory
Any CIFS directory that is not the /os2200 directory. Non-/os2200 directories contain only
the files placed in them by users. All files in non-/os2200 directories also have an entry in
the /os2200 directory.
O
omnibus (.omn)
An OS 2200 element type. CIFS recognizes the file name extension .omn as indicative of
an omnibus element.
P
password
A character string used to authenticate a user ID. A user must enter the correct
password when signing on to the system. Each user ID has its own unique and private
password associated with it. Passwords are used to prevent others from signing on the
system with a user-id that is not their own.
populate
The process of updating the CIFS directories with information from the Exec master file
directories (MFDs).
position
POSIX
An increment for measuring mass storage space, equal to 64 tracks, 4,096 sectors, or
114,688 words, 458,752 bytes.
Portable operating system interfaces. A set of IEEE standards designed to provide
application portability among UNIX variants.
privilege
The mechanism that lets specified users override restrictions and validations.
Q
qualifier
A string of characters used to prefix a file name to make sure that the name is unique.
The qualifier is separated from the basic file name with an asterisk (for example,
QUAL*FILE). If the user does not provide a qualifier when a file is named, the system
uses the user’s project–id.
Glossary–4 7859 6137–009

R
relative reference
A file path name reference that is relative to the current working directory.
Glossary
relocatable element (.rel)
An OS 2200 element type. CIFS recognizes the file name extension as indicative of a
relocatable element.
S
SDF
Symbolic element (SDF). Default for CIFS-created files if a type is not explicitly specified.
security management product
The product used to manage security on OS 2200 systems—either Security
Administration for ClearPath OS 2200 or SIMAN.
Security Administration for ClearPath OS 2200 is a product for controlling and
administering OS 2200 security. It has a Security Client for creating and modifying
system, application, and user security records from a remote Windows or LINUX or UNIX
workstation. Administrators use this application to configure security features, set up
user-ids, and control access to system resources. Nonadministrators can use it to view
or modify their individual security records. A batch processor (@SECMGR) provides a
batch/demand interface to perform those same administrator or end-user operations at
an OS 2200 terminal. Communication between the remote Security Client workstations
and the OS 2200 host is enabled by an SNMP agent running on the host.
Site Management Complex (SIMAN) is the TeamQuest interactive software product that
provides a tool with a menu-driven interface for creating and maintaining security and
resource control in an OS 2200 system. You can set up security for the whole system,
for a particular application, or for individual user security.
server message block protocol (SMB)
Server message block (SMB) protocol is a client/server request/response protocol for
sharing files, printers, serial ports, and communication abstractions.
W
word
A sequence of bits or characters treated as a unit that can be stored in a single main
storage location (an OS 2200 word by contains 36 bits).
working directory
See current working directory.
7859 6137–009 Glossary–5

Glossary
Glossary–6 7859 6137–009

Index
A
absolute
element type (.abs), 1-8
pathname resolution, 3-9
reference, 1-6
access
control records (ACRs), 3-15
permissions, 1-10
to data, 1-11
access() function, 5-6
administrative tasks, 9-1
advisory
record locking, 3-26
advisory record lock, deadlocks, 3-28
alias, 1-2, 1-7
APIs for file filtering, 9-26
associate specific file descriptor index with
existing open file description, 5-19,
6-23
associate stream with pathname, 5-42, 6-50
attributes of open file description, 3-11
audience, 1-3
B
background run options, 9-8
backup command, 4-4
binary format, 3-21
binjar command, 4-5
C
C API table, 5-1
case, handling of, 1-5
cat (type), 4-6
cd command, 4-7
change
current working directory, 4-7, 5-8, 6-8
file permissions, 4-8, 5-9
logical length of a file, 4-32
owner of file or directory, 4-10
pathname of existing file or
directory, 5-111, 6-119
change access time and modification time file
or directory, 5-132, 6-147
character file, 3-1
characteristics of
a file hierarchy, 3-6
locks, 3-27
chdir command, 4-7
chdir() function, 5-8
chmod command, 4-8
chmod() function, 5-9
chown command, 4-10
CIFS background run, 9-6
CIFS components, 1-1
CIFS diagram, 1-2
CIFS subsystem user-id, 9-4
CIFS TRACE, 9-9
cifs$access service subprogram, 6-5
CIFS$ACR, 3-32
CIFS$CACHE, 3-32, 9-21
CIFS$CAT, 3-32
CIFS$CD, 3-32
cifs$chdir service subprogram, 6-8
cifs$chown service subprogram, 6-12
cifs$clearerr service subprogram, 6-14
cifs$close service subprogram, 6-15
cifs$closedir service subprogram, 6-17
CIFS$COMAPI, 3-33
cifs$creat service subprogram, 6-19
cifs$dup service subprogram, 6-21
cifs$dup2 service subprogram, 6-23
cifs$fclose service subprogram, 6-25
cifs$fcntl service subprogram, 6-26
cifs$fdatasync service subprogram, 6-39
cifs$fdopen service subprogram, 6-41
cifs$feof service subprogram, 6-43
cifs$ferror service subprogram, 6-44
cifs$fflush service subprogram, 6-45
cifs$fgetc service subprogram, 6-46
cifs$fgetpos service subprogram, 6-47
cifs$fgets service subprogram, 6-48
7859 6137–009 Index–1

Index
cifs$fileno service subprogram, 6-49
cifs$fopen service subprogram, 6-50
cifs$fprintf service subprogram, 6-52
cifs$fputc service subprogram, 6-57
cifs$fputs service subprogram, 6-58
cifs$fread service subprogram, 6-59
cifs$freopen service subprogram, 6-61
cifs$fscanf service subprogram, 6-63
cifs$fseek service subprogram, 6-67
cifs$fsetpos service subprogram, 6-68
cifs$fstat service subprogram, 6-69
cifs$fsync service subprogram, 6-71
cifs$ftell service subprogram, 6-72
cifs$ftruncate service subprogram, 6-73
cifs$fwrite service subprogram, 6-74
cifs$getc service subprogram, 6-75
cifs$getchar service subprogram, 6-75
cifs$getcwd service subprogram, 6-77
cifs$gets service subprogram, 6-78
cifs$istat service subprogram, 6-79
CIFS$KEYS, 3-33
cifs$link service subprogram, 6-81
cifs$lseek service subprogram, 6-84
cifs$mask service subprogram, 6-87
CIFS$MFD, 3-33
cifs$mkdir service subprogram, 6-88
cifs$mkfifo service subprogram, 6-90
CIFS$NEXTFILE, 1-8, 3-33
cifs$open service subprogram, 6-92
cifs$opendir service subprogram, 6-100
CIFS$PACK, 6-102
cifs$perror service subprogram, 6-104
cifs$pipe service subprogram, 6-105
cifs$printf service subprogram, 6-107
cifs$putc service subprogram, 6-108
cifs$putchar service subprogram, 6-109
cifs$puts service subprogram, 6-110
CIFS$RAW, 3-33
cifs$read service subprogram, 6-111
cifs$readdir service subprogram, 6-115
cifs$remove service subprogram, 6-118
cifs$rename service subprogram, 6-119
cifs$rewind service subprogram, 6-123
cifs$rewinddir service subprogram, 6-124
cifs$rmdir service subprogram, 6-126
cifs$scanf service subprogram, 6-128, 6-129
cifs$share service subprogram, 6-129
cifs$sprintf service subprogram, 6-130
cifs$sscanf service subprogram, 6-131
cifs$stat service subprogram, 6-132
cifs$stderr service subprogram, 6-134
cifs$stdin service subprogram, 6-135
cifs$stdout service subprogram, 6-136
cifs$strerror service subprogram, 6-137
CIFS$SUBTYPE, 3-33
cifs$tmpfile service subprogram, 6-138
cifs$tmpnam service subprogram, 6-139
cifs$truncate service subprogram, 6-140
cifs$umask service subprogram, 6-141
cifs$uname service subprogram, 6-143
cifs$ungetc service subprogram, 6-144
cifs$unlink service subprogram, 6-145
cifs$utime service subprogram, 6-147
cifs$write service subprogram, 6-150
cifs$xlate service subprogram, 6-155
CIFS-DEACT, 9-8
CIFS-F-DUPFD, 6-31
CIFSHI, 1-1
CIFSLIB, 1-1
CIFSUT, 1-1
class permission values, 3-20
clear
end-of-file indicators for the stream, 5-13,
6-14
error indicators for the stream, 5-13, 6-14
clearance level, 9-11
clearerr() function, 5-13
close an open directory stream, 5-15, 6-17
close() function, 5-14
closedir() function, 5-15
COBOL API table, 6-1
common permission assignments, 3-16
communications interface, 1-11
compartment set, 9-11
components, CIFS, 1-1
conflicts with file access specification, 3-27
consolidating servers, 9-26
conversion specifications, 5-44, 6-53
convert files from SDF to binary, 4-5
copy a file or directory to a target, 4-11
copy command, 4-11
cp command, 4-11
creat() function, 5-16
create
additional file descriptor, 5-18, 6-21
directory, 4-22, 5-82, 6-88
directory entries for file, 5-75, 6-81
file, 5-16, 6-19
file mode creation mask, 5-127, 6-141
network-visible name for a directory, 4-31
new FIFO file, 5-84, 6-90
pipe, 5-98, 6-105
share directory, 2-3
stream and associate file descriptor, 5-34,
6-41
temporary binary file, 5-124, 6-138
Index–2 7859 6137–009

creation mask, file mode, 3-19
current working directory, 1-6, 3-8, 0-2
D
data
access privileges, 1-11
storage, 1-8
data access security and network
connections, 2-2
deadlock, 3-28
default working directory, 2-3
delete a specific directory and all files and
subdirectories, 4-14
deltree command, 4-14
determine
if a file exists, 5-6, 6-5
permission, 5-6, 6-5
dir command, 4-19
directories synchronized, 9-2
directory, 3-4
/dev, 1-7
/os2200, 1-6
create, 4-22
entry, 3-4, 3-25
main_dir, 3-4
name length, 1-5
non-/os2200, 1-7
rename, 5-113, 6-121
stream, 3-25
directory structure of CIFS, 1-5
directory, files, and links diagram, 3-5
display environmental variables, 4-29
display system environmental variables, 4-30
dot file, 3-8
dot-dot file, 3-8
dup() function, 5-18
dup2() function, 5-19
duplicate file descriptor, 5-27, 6-31
E
E keyin, 9-8
E1100CORRUPT, 5-96
E1100INTERNAL, 5-96
EACCES, 5-95
EBUSY, 5-96
EFAULT, 5-95
EIO, 5-96
Index
elements placed in SYS$LIB$*CIFS$LIB
during installation, 9-1
ENONMEM, 5-96
ENOTDIR, 5-96
environment variables
initial values, 9-21
table, 3-32
environmental variables, display, initialize, or
update, 4-29
examples or valid pathnames, 3-7
exclusive locks, 3-27
execute permission, 3-14
7859 6137–009 Index–3
F
F_DUPFD, 5-27
fclose() function, 5-21
fcntl() function, 5-22
fdatasync() function, 5-33
fdopen() function, 5-34
feof() function, 5-35
ferror() function, 5-36
fflush() function, 5-37
fgetc() function, 5-38
fgetpos() function, 5-39
fgets() function, 5-40
Fieldata, 1-8, 5-106, 6-114
file
access
specification, 3-12
attributes, 1-10
character, 3-1
concepts, 3-1
definition and file types, 3-1
descriptor, 3-13
descriptor services, 5-27, 6-31
dot, 3-8
dot-dot, 3-8
format, 3-21
hierarchy, 3-6
name length, 1-5
permissions, 3-14, 3-19
pipe, 3-2
regular, 3-1
renaming, 5-112, 6-121
status flags, 3-11
status flags and access specification
services, 5-27, 6-32
system structure, 1-5
type, 3-21
file access

Index
by multiple processes, 3-24
File Assignment, 9-22
file descriptor closure mode services, 5-27
file filtering, 9-26
APIs, 9-26
File I/O Buffer Cache, 9-21
file mode, 3-18
filename, 3-2
fileno() function, 5-41
files deleted by @CYCLE, 9-3
filtering files in a consolidated server
environment, 9-26
flock structure, 5-25, 6-29
fopen() function, 5-42
format string, 5-44, 5-53, 6-52, 6-63
forward slash, 1-6, 1-7
fprintf() function, 5-44
fputc() function, 5-49
fputs() function, 5-50
fread() function, 5-51
freopen() function, 5-52
fscanf() function, 5-53
fseek() function, 5-57
fsetpos() function, 5-58
fstat() function, 5-59
fsync() function, 5-61
ftell() function, 5-62
ftruncate() function, 5-63
FURPUR @PACK, 4-33
fwrite() function, 5-64
G
generate string to use as filename, 5-125,
6-139
get
current value of file position indicator, 5-39,
6-47
current value of stream file position
indicator, 5-62, 6-72
next character from input stream, 5-38,
5-65, 6-46, 6-75
next character from standard input, 5-66,
6-75
GET$ENV, 3-32
getc() function, 5-65
getchar() function, 5-66
getcwd() function, 5-67
gets() function, 5-71
group activities into logical processes, 5-20
Index–4 7859 6137–009
I
i, 9-15
I/O operations, file, 3-24
identify process' current working
directory, 5-67, 6-77
implementation of SMB, 1-11
inheriting file mode creation mask, 3-19
initial values for environment variables, 9-21
initialize environmental variables, 4-29
initialize system environmental variables, 4-30
input and output (I/O) operations and
functions, 3-31
istat() function, 5-73
K
keys command, 4-17
L
limitations, A-1
link, 3-4
link count, 3-4
link() function, 5-75
ln command, 4-18
lock or unlock an entire file, 5-27, 6-31
lock request failure, 3-27
locking, records, 3-26
log entries, type 801, 9-11
ls command, 4-19
lseek() function, 5-78
M
main_dir directory, 3-4
make open directory stream inaccessible to
calling process, 5-15, 6-17
manage an open file, 5-22, 6-26
managing files from the workstation, 2-1
map drive to share directory, 2-4
masking with @CIFSUT, 4-3
md command, 4-22
merge adjacent locks, 5-27, 6-31
Microsoft networks redirector, 2-2
mkdir command, 4-22
mkdir() function, 5-82
mkfifo() function, 5-84

mode argument, 3-19, 5-93, 6-98
Monitor Services, 9-2
move a file, 4-24
move command, 4-24
mv command, 4-24
N
networking CIFS with Windows, 2-1
networking implementation, 2-2
network-visible name
create share, 4-31
remove share, 4-35
node, 3-6
non-/os2200 directory hierarchy, 1-7
notation conventions, 1-4
O
oflag argument, 5-90, 6-95
omnibus element type (.omn), 1-8, 0-1, 0-4
open
directory stream, 5-94, 6-100
file, 5-87, 6-92
new file, 5-16, 6-19
pathname, 5-42, 6-50
pathname and associate stream, 5-52, 6-61
open file
description, 3-11
descriptions time information, 3-17
information, 3-18
open() function, 5-87
opendir() function, 5-94
P
pack(), 5-95
parent directory, 3-8
pathname, 3-7
pathname resolution, 3-9
permission mask, 3-16
perror() function, 5-97
Persistent Connections, 2-3
pipe, 3-2
using, 3-29
pipe file, 3-2
pipe() function, 5-98
populate, 9-4
prevent access to a file, 5-14, 6-15
Index
print message corresponding to error, 5-97,
6-104
printf() function, 5-100
private files, 3-15
protecting data against loss from system
outage, 5-61, 6-71
public files, 3-15
PUT$ENV, 3-32
putc() function, 5-101
putchar() function, 5-102
puts() function, 5-103
7859 6137–009 Index–5
R
rd command, 4-28
read
current entry in directory stream, 5-107,
6-115
data from a file, 5-104, 6-111
elements from input stream to array, 5-51,
6-59
formatted input, 5-53, 6-63
formatted input from standard
input, 5-118, 6-128
formatted input from string, 5-121, 6-131
next character from input stream to
array, 5-40, 6-48
permission, 3-14
read() function, 5-104
read/write offset, 3-11
readdir() function, 5-107
reading or writing data to CIFS files, 3-24
realpath() function, 5-109
record locking, 3-26
services, 5-30, 6-35
redirecting standard files to pipes, 5-18, 5-99,
6-21, 6-106
reference one file in multiple ways, 5-75, 6-81
regular file, 3-1
relative pathname resolution, 3-10
release certain file attributes, 5-14, 6-15
release grouped activities, 5-86
relocatable element type (.rel), 1-8, 0-1, 0-4
remove
empty directory, 4-28, 5-117, 6-126
file, 5-110, 6-118
link from file, 5-131, 6-145
network-visible name for a directory, 4-35
remove() function, 5-110
removing locks, 3-28
rename

Index
directory, 5-113, 6-121
files, 4-24, 5-112, 6-121
rename() function, 5-111
replace the previous lock, 5-27, 6-31
replacing and merging locks, 3-28
reposition directory stream at
beginning, 5-116, 6-124
restrictions, A-1
restrictions for file
descriptors, 3-13
format attributes, 3-21
retrieve
CIFS-unique information about CIFS file or
directory, 5-73, 6-79
file descriptor, 5-41, 6-49
information about open file, 5-59, 5-122,
6-69, 6-132
return
character to the input stream, 5-130, 6-144
fully resolved name of specified file, 5-109
rewind() function, 5-115
rewinddir() function, 5-116
rmdir command, 4-28
rmdir() function, 5-117
root directory, 3-6
rules for
creating directories, 3-4
pathnames, 3-7
S
save CIFS directory structure, 4-4
scanf() function, 5-118
SDF elements, 1-8
search/execute permission, 3-14
securing data to disk storage, 3-24
Security Administration for ClearPath OS
2200, See security management
product
security considerations, 1-10
security management product, 4-30, 9-21
security policy enforcement, 9-11
server message block (SMB), 1-11
servers, consolidating, 9-26
set
end-of-file position for file, 5-126, 6-140
end-of-file position for open file, 5-63, 6-73
file position indicator to beginning of
stream, 5-115, 6-123
permissions, 3-20
stream file position indicator, 5-57, 5-58,
6-67, 6-68
the read/write offset for open file, 5-78,
6-84
set command, 4-29
set the file mode creation mask, 5-127, 6-142
setsys command, 4-30
share
names, 1-11
reference, 1-11
share command, 4-31
shared locks, 3-27
size command, 4-32
SMB protocol, 1-11
specify network-visible name for
directory, 5-119, 6-129
sprintf() function, 5-120
sscanf() function, 5-121
SSCONSOLE, 9-4
SSRUNXOPT, 9-5
ST keyin, 9-4, 9-7
standard
error, 3-13
input, 3-13
output, 3-13
starting the CIFS background run, 9-5
stat structure table, 5-59
stat() function, 5-122
status of advisory record locks, 3-26
stderr, 3-13
stdin, 3-13
stdout, 3-13
stop the CIFS background run, 9-7
subordinate directory, 3-4
system data format (SDF), 3-21
system environmental variables, display,
initialize, or update, 4-30
system recovery, 9-6
Index–6 7859 6137–009
T
TCP port, 2-2
test
end of file for stream, 5-35, 6-43
for file type, 3-22
for read/write error, 5-36, 6-44
text-based utility, CIFS, 4-1
time dependent environment variables, 9-22
time information, 3-17
TIMEBASE environment variable, 9-22
TIP considerations, 1-12

tmpfile() function, 5-124
tmpnam() function, 5-125
truncate() function, 5-126
type 801 log entry, 9-11
types of file permissions, 3-14
TZ environment variable, 9-22
U
umask() function, 5-127
UNC, 2-1, 2-5
ungetc() function, 5-130
universal naming convention, 2-1, 2-5
unlink() function, 5-131
unlocks whole files, 3-27
unshare command, 4-35
update environmental variables, 4-29
update system environmental variables, 4-30
URTS I/O handling, 1-8
use command, 4-36
user-id for CIFS, 9-4
using
advisory record locks, 3-27
directory streams, 3-25
file descriptors, 3-13
file permissions, 3-17
pipes, 3-29
the file mode, 3-19
utility command list, 4-2
utility interfaces, 4-1
utimbuf structure, 5-133, 6-148
utime() function, 5-132
V
valid filenames, example, 3-3
version command, 4-37
vfprintf() function, 5-135
viewing CIFS files, 2-7
vprintf() function, 5-136
vsprintf() function, 5-137
Index
7859 6137–009 Index–7
W
what CIFS does, 1-2
working directory, 3-8
write
characters to output stream, 5-49, 5-101,
6-57, 6-108
characters to standard output, 5-102, 6-109
data currently in buffer cache for file, 5-61,
6-71
data in buffer without closing file, 5-37,
6-45
data to file at current read/write
position, 5-138, 6-150
elements to output stream, 5-64, 6-74
formatted output, 5-44, 5-135, 6-52
formatted output to character array, 5-120,
5-137, 6-130
formatted output to standard
output, 5-100, 5-136, 6-107
information to standard output, 4-19
permission, 3-14
remaining data to file and close file, 5-21,
6-25
string of characters to standard
output, 5-103, 6-110
string to output stream, 5-50, 6-58
write all data currently in portion of buffer
cache for file, 5-33, 6-39
write() function, 5-138
X
xlate command, 4-38
Special Characters
/os2200 directory hierarchy, 1-6
@CIFSUT, 4-1

Index
Index–8 7859 6137–009

© 2009 Unisys Corporation.
All rights reserved.
*78596137-009*
7859 6137–009