1515 lines
42 KiB
Plaintext
1515 lines
42 KiB
Plaintext
# MAN2
|
|
MAN2 (2)
|
|
|
|
Section 2 of the Manual describes system calls, and is for use
|
|
primarily by programmers.
|
|
|
|
The sections of the manual are:
|
|
|
|
Section 1: User commands
|
|
-->Section 2: System calls
|
|
Section 3: C library
|
|
Section 4: File formats
|
|
Section 5: Miscellaneous
|
|
Section 6: Games
|
|
Section 7: Special files (devices)
|
|
Section 8: Maintenance procedures
|
|
|
|
# fork
|
|
fork (2)
|
|
|
|
PROTOTYPE:
|
|
pid_t fork() - create a child process identical to the parent
|
|
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
|
|
# wait
|
|
wait (2)
|
|
|
|
PROTOTYPE:
|
|
pid_t wait(int *stat_loc)
|
|
- wait for a child process to terminate and determine
|
|
its exit status
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 276
|
|
# execve execl execv execle execve execlp execvp
|
|
execl (2), execv (2), execle (2), execve (2), execlp (2),
|
|
execvp (2)
|
|
|
|
PROTOTYPE:
|
|
int execl (path, arg0, arg1, ..., argn, (char *))
|
|
int execv (path, argv)
|
|
int execle (path, arg0, arg1, ..., argn, (char *), envp)
|
|
int execve (path, argv, envp)
|
|
int execlp (file, arg0, arg1, ..., argn, (char *))
|
|
int execvp (file, argv)
|
|
- substitute a new image for the existing process
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
Concurrent Unix Programmer's Manual Vol 1B
|
|
# exit
|
|
exit (2)
|
|
|
|
PROTOTYPE:
|
|
void exit(int status)
|
|
- terminate process
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# brk
|
|
brk (2)
|
|
|
|
PROTOTYPE:
|
|
char * brk(char *addr)
|
|
- change size of data segment
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# getpid
|
|
getpid (2)
|
|
|
|
PROTOTYPE:
|
|
pid_t getpid()
|
|
- get process id
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# signal
|
|
signal (2)
|
|
|
|
PROTOTYPE:
|
|
void signal(int signr, void (*func()))
|
|
- enable signal catching
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 276
|
|
# kill
|
|
kill (2)
|
|
|
|
PROTOTYPE:
|
|
int kill(pid_t pid, int sig)
|
|
- send a signal to a process
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# alarm
|
|
alarm (2)
|
|
|
|
PROTOTYPE:
|
|
unsigned alarm(unsigned int sec)
|
|
- set alarm clock timer
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# pause
|
|
pause (2)
|
|
|
|
PROTOTYPE:
|
|
int pause()
|
|
- suspend current process until signal received
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# creat
|
|
creat (2)
|
|
|
|
PROTOTYPE:
|
|
int creat(char *path, mode_t mode)
|
|
- create new file or truncate existing one
|
|
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# mkdir
|
|
mkdir (2)
|
|
|
|
PROTOTYPE:
|
|
int mkdir(char *path, mode_t mode)
|
|
- make a directory
|
|
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# mknod
|
|
mknod (2)
|
|
|
|
PROTOTYPE:
|
|
int mknod(char *name, int mode, int addr, int size)
|
|
- make a special (device) file
|
|
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# open
|
|
open (2)
|
|
|
|
PROTOTYPE:
|
|
int open(char *path, int oflag, mode_t mode)
|
|
- open a file for reading, writing, or both
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# close
|
|
close (2)
|
|
|
|
PROTOTYPE:
|
|
int close(int fd)
|
|
- close open file
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# read
|
|
read (2)
|
|
|
|
PROTOTYPE:
|
|
int read(int fd, char *buf, unsigned nbyte)
|
|
- read data from a file to a buffer
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# write
|
|
write (2)
|
|
|
|
PROTOTYPE:
|
|
int write(int fd, char *buf, unsigned nbyte)
|
|
- write data from a buffer to a file
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 276
|
|
# lseek
|
|
lseek (2)
|
|
|
|
PROTOTYPE:
|
|
off_t lseek(int fd, off_t offset, int whence)
|
|
- move file pointer
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# stat fstat
|
|
stat (2), fstat (2)
|
|
|
|
PROTOTYPE:
|
|
int stat(char *path,struct stat *buf)
|
|
- get info from i-node using file name
|
|
int fstat(int fd, struct stat * buf)
|
|
- get info from i-node using file descriptor
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275, 276
|
|
# dup dup2
|
|
dup (2), dup2 (2)
|
|
|
|
PROTOTYPE:
|
|
int dup(int fd)
|
|
int dup2(int fd, int fd2)
|
|
- duplicate file descriptor
|
|
archivo abierto
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
Concurrent Unix Programmer's Manual Vol 1B
|
|
|
|
# pipe
|
|
pipe (2)
|
|
|
|
PROTOTYPE:
|
|
int pipe(int fd[])
|
|
- create a pipe
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# ioctl
|
|
ioctl (2)
|
|
|
|
PROTOTYPE:
|
|
int ioctl(int fd, int request, struct sgttyb *argp)
|
|
- set device parameters
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# link
|
|
link (2)
|
|
|
|
PROTOTYPE:
|
|
int link(char *path1, char *path2)
|
|
- create a link
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# unlink
|
|
unlink (2)
|
|
|
|
PROTOTYPE:
|
|
int unlink(char *path)
|
|
- remove a directory entry
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 276
|
|
|
|
# mount
|
|
mount (2)
|
|
|
|
PROTOTYPE:
|
|
int mount(char *name, char *special)
|
|
- mount a file system
|
|
See also:
|
|
umount (2)
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
|
|
# umount
|
|
umount (2)
|
|
|
|
PROTOTYPE:
|
|
int umount(char *name)
|
|
- unmount a file system
|
|
See also:
|
|
mount (2)
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 276
|
|
# sync
|
|
sync (2)
|
|
|
|
PROTOTYPE:
|
|
int sync() - flush cache to disk
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 276
|
|
|
|
# chdir
|
|
chdir (2)
|
|
|
|
PROTOTYPE:
|
|
int chdir(char *path)
|
|
- change current directory
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
|
|
# chroot
|
|
chroot (2)
|
|
|
|
PROTOTYPE:
|
|
int chroot(char *path)
|
|
- change root
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
|
|
# chmod
|
|
chmod (2)
|
|
|
|
PROTOTYPE:
|
|
int chmod (char *path, mode_t mode)
|
|
- change protection bits
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# getuid
|
|
getuid (2)
|
|
|
|
PROTOTYPE:
|
|
gid_t getuid() - determine uid of caller
|
|
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
|
|
# getgid
|
|
getgid (2)
|
|
|
|
PROTOTYPE:
|
|
uid_t getgid() - determine gid of caller
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# geteuid
|
|
geteuid (2)
|
|
|
|
PROTOTYPE:
|
|
gid_t geteuid() - determine effective gid
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# getegid
|
|
getegid (2)
|
|
|
|
PROTOTYPE:
|
|
uid_t getegid() - determine effective uid
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# setuid
|
|
setuid (2)
|
|
|
|
PROTOTYPE:
|
|
int setuid(uid_t uid)
|
|
- set uid
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# setgid
|
|
setgid (2)
|
|
|
|
PROTOTYPE:
|
|
int setgid(gid_t gid)
|
|
- set gid
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
|
|
# chown
|
|
chown (2)
|
|
|
|
PROTOTYPE:
|
|
int chown(char *path, uid_t owner, gid_t group)
|
|
- change owner and/or group of file
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# umask
|
|
umask (2)
|
|
|
|
PROTOTYPE:
|
|
mode_t umask(mode_t cmask)
|
|
- set file mask
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# time
|
|
time (2)
|
|
|
|
PROTOTYPE:
|
|
time_t time(time_t *loc)
|
|
- get time since Jan 1 1970
|
|
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# stime
|
|
stime (2)
|
|
|
|
PROTOTYPE:
|
|
int stime(long *timep)
|
|
- set time
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# utime
|
|
utime (2)
|
|
|
|
PROTOTYPE:
|
|
int utime(char *path, struct utimbuf *times)
|
|
- set file times
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# times
|
|
times (2)
|
|
|
|
PROTOTYPE:
|
|
clock_t times(struct tms *buffer)
|
|
- get accounting times
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# access
|
|
access (2)
|
|
|
|
PROTOTYPE:
|
|
int access(char *path, int amode)
|
|
- determine if access is permitted
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# fcntl
|
|
fcntl (2)
|
|
|
|
PROTOTYPE:
|
|
int fcntl(int fd, struct stat *buf)
|
|
- miscellaneous controls
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# rename
|
|
rename (2)
|
|
|
|
PROTOTYPE:
|
|
int rename(char *old, char *new)
|
|
- change name of file
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
|
|
# rmdir
|
|
rmdir (2)
|
|
|
|
PROTOTYPE:
|
|
int rmdir(char *path)
|
|
- remove a directory
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
# ptrace
|
|
ptrace (2)
|
|
|
|
PROTOTYPE:
|
|
long ptrace(int req, pid_t pid, long addr, long data)
|
|
- trace a process
|
|
See also:
|
|
Operating Systems Design and Implementation 22;
|
|
Minix 1.5 Reference Manual 275
|
|
|
|
# accept
|
|
NAME
|
|
accept - accept a connection on a socket
|
|
|
|
SYNOPSIS
|
|
#include <sys/types.h>
|
|
#include <sys/socket.h>
|
|
|
|
ns = accept(s, addr, addrlen)
|
|
int ns, s;
|
|
struct sockaddr *addr;
|
|
int *addrlen;
|
|
|
|
DESCRIPTION
|
|
The argument s is a socket that has been created with socket(2),
|
|
bound to an address with bind(2), is listening for connections
|
|
after a listen(2). Accept extracts the first connection request
|
|
on the queue of pending connections, creates a new socket with
|
|
the same properties of s and allocates a new file descriptor, ns ,
|
|
for the socket. If no pending connections are present on the queue,
|
|
and the socket is not marked as non-blocking, accept blocks the
|
|
caller until a connection is present.
|
|
If the socket is marked non-blocking and no pending connections
|
|
are present on the queue, accept returns an error as described
|
|
below. The accepted socket, ns , may not be used to accept more
|
|
connections. The original socket s remains open.
|
|
|
|
The argument addr is a result parameter that is filled in with
|
|
the address of the connecting entity, as known to the communications
|
|
layer. The exact format of the addr parameter is determined by the
|
|
domain in which the communication is occurring.
|
|
|
|
The addrlen is a value-result parameter; it should initially contain
|
|
the amount of space pointed to by addr ; on return it will contain
|
|
the actual length (in bytes) of the address returned.
|
|
This call is used with connection-based socket types, currently with
|
|
SOCK_STREAM.
|
|
|
|
It is possible to select(2) a socket for the purposes of doing an
|
|
accept by selecting it for read.
|
|
|
|
For certain protocols which require an explicit confirmation, such
|
|
as ISO or DATAKIT, one should think of accept as merely dequeueing
|
|
the next connection request, and not in of itself implying
|
|
confirmation. Confirmation can be implied by a normal read or write
|
|
on the new file desciptor, and rejection can be implied by closing
|
|
the new socket.
|
|
|
|
One can obtain user connection request data without confirming the
|
|
connection by issuing a recvmsg call with an msg_iovlen of 0 and a
|
|
non-zero msg_controllen, or by issuing a getsockopt(2) request.
|
|
Similarly, one can provide user connection rejection information
|
|
by issuing a sendmsg call with providing only the control
|
|
information, or by calling setsockopt(2).
|
|
|
|
RETURN VALUE
|
|
The call returns -1 on error. If it succeeds, it returns a
|
|
non-negative integer that is a descriptor for the accepted socket.
|
|
|
|
ERRORS
|
|
The accept will fail if:
|
|
|
|
[EBADF] The descriptor is invalid.
|
|
|
|
[ENOTSOCK] The descriptor references a file, not a socket.
|
|
|
|
[EOPNOTSUPP] The referenced socket is not of type SOCK_STREAM.
|
|
|
|
[EFAULT] The addr parameter is not in a writable part of the
|
|
user address space.
|
|
|
|
[EWOULDBLOCK] The socket is marked non-blocking and no connections
|
|
are present to be accepted.
|
|
|
|
SEE ALSO
|
|
bind(2), connect(2), listen(2), select(2), socket(2)
|
|
|
|
OTHER INFO
|
|
This call is part of the Tnet library.
|
|
|
|
# bind
|
|
NAME
|
|
bind - bind a name to a socket
|
|
|
|
SYNOPSIS
|
|
#include <sys/types.h>
|
|
#include <sys/socket.h>
|
|
|
|
bind(s, name, namelen)
|
|
int s;
|
|
struct sockaddr *name;
|
|
int namelen;
|
|
|
|
DESCRIPTION
|
|
Bind assigns a name to an unnamed socket. When a socket is created
|
|
with socket(2) it exists in a name space (address family) but has no
|
|
name assigned. Bind requests that name be assigned to the socket.
|
|
|
|
NOTES
|
|
Binding a name in the UNIX domain creates a socket in the file
|
|
system that must be deleted by the caller when it is no longer
|
|
needed (using unlink(2)).
|
|
|
|
The rules used in name binding vary between communication domains.
|
|
Consult the manual entries in section 4 for detailed information.
|
|
|
|
RETURN VALUE
|
|
If the bind is successful, a 0 value is returned.
|
|
A return value of -1 indicates an error, which is
|
|
further specified in the global errno.
|
|
|
|
ERRORS
|
|
The bind call will fail if:
|
|
|
|
[EBADF] S is not a valid descriptor.
|
|
|
|
[ENOTSOCK] S is not a socket.
|
|
|
|
[EADDRNOTAVAIL] The specified address is not available from the
|
|
local machine.
|
|
|
|
[EADDRINUSE] The specified address is already in use.
|
|
|
|
[EINVAL] The socket is already bound to an address.
|
|
|
|
[EACCES] The requested address is protected, and the current
|
|
user has inadequate permission to access it.
|
|
|
|
[EFAULT] The name parameter is not in a valid part of the user
|
|
address space.
|
|
|
|
The following errors are specific to binding names in the UNIX
|
|
domain.
|
|
|
|
[ENOTDIR] A component of the path prefix is not a directory.
|
|
|
|
[EINVAL] The pathname contains a character with the
|
|
high-order bit set.
|
|
|
|
[ENAMETOOLONG] A component of a pathname exceeded 255 characters.
|
|
|
|
|
|
[ENOENT] A prefix component of the path name does not exist.
|
|
|
|
[ELOOP] Too many symbolic links were encountered in
|
|
translating the pathname.
|
|
|
|
[EIO] An I/O error occurred while making the directory
|
|
entry or allocating the inode.
|
|
|
|
[EROFS] The name would reside on a read-only file system.
|
|
|
|
[EISDIR] A null pathname was specified.
|
|
|
|
SEE ALSO
|
|
connect(2), listen(2), socket(2), getsockname(2)
|
|
|
|
OTHER INFO
|
|
This call is part of the Tnet library.
|
|
|
|
#connect
|
|
NAME
|
|
connect - initiate a connection on a socket
|
|
|
|
SYNOPSIS
|
|
#include <sys/types.h>
|
|
#include <sys/socket.h>
|
|
|
|
connect(s, name, namelen)
|
|
int s;
|
|
struct sockaddr *name;
|
|
int namelen;
|
|
|
|
DESCRIPTION
|
|
The parameter s is a socket.
|
|
If it is of type SOCK_DGRAM, then this call specifies the peer with
|
|
which the socket is to be associated; this address is that to which
|
|
datagrams are to be sent, and the only address from which datagrams
|
|
are to be received. If the socket is of type SOCK_STREAM, then this
|
|
call attempts to make a connection to another socket.
|
|
The other socket is specified by name, which is an address in the
|
|
communications space of the socket. Each communications space
|
|
interprets the name parameter in its own way.
|
|
Generally, stream sockets may successfully connect only once;
|
|
datagram sockets may use connect multiple times to change their
|
|
association. Datagram sockets may dissolve the association by
|
|
connecting to an invalid address, such as a null address.
|
|
|
|
RETURN VALUE
|
|
If the connection or binding succeeds, then 0 is returned.
|
|
Otherwise a -1 is returned, and a more specific error code
|
|
is stored in errno.
|
|
|
|
ERRORS
|
|
The call fails if:
|
|
|
|
[EBADF] S is not a valid descriptor.
|
|
|
|
[ENOTSOCK] S is a descriptor for a file, not a socket.
|
|
|
|
[EADDRNOTAVAIL] The specified address is not available on this
|
|
machine.
|
|
|
|
[EAFNOSUPPORT] Addresses in the specified address family cannot
|
|
be used with this socket.
|
|
|
|
[EISCONN] The socket is already connected.
|
|
|
|
[ETIMEDOUT] Connection establishment timed out without
|
|
establishing a connection.
|
|
|
|
[ECONNREFUSED] The attempt to connect was forcefully rejected.
|
|
|
|
[ENETUNREACH] The network isn't reachable from this host.
|
|
|
|
[EADDRINUSE] The address is already in use.
|
|
|
|
[EFAULT] The name parameter specifies an area outside
|
|
the process address space.
|
|
|
|
[EINPROGRESS] The socket is non-blocking and the connection cannot
|
|
be completed immediately. It is possible to
|
|
select(2) for completion by selecting the socket
|
|
for writing.
|
|
|
|
[EALREADY] The socket is non-blocking and a previous connection
|
|
attempt has not yet been completed.
|
|
|
|
The following errors are specific to connecting names in the UNIX
|
|
domain. These errors may not apply in future versions of the UNIX
|
|
IPC domain.
|
|
|
|
[ENOTDIR] A component of the path prefix is not a directory.
|
|
|
|
[EINVAL] The pathname contains a character with the
|
|
high-order bit set.
|
|
|
|
[ENAMETOOLONG] A component of a pathname exceeded 255 characters,
|
|
or an entire path name exceeded 1023 characters.
|
|
|
|
[ENOENT] The named socket does not exist.
|
|
|
|
[EACCES] Search permission is denied for a component of the
|
|
path prefix.
|
|
|
|
[EACCES] Write access to the named socket is denied.
|
|
|
|
[ELOOP] Too many symbolic links were encountered in
|
|
translating the pathname.
|
|
|
|
SEE ALSO
|
|
accept(2), select(2), socket(2), getsockname(2)
|
|
|
|
OTHER INFO
|
|
This call is part of the Tnet library.
|
|
|
|
# gethostid
|
|
NAME
|
|
gethostname, sethostname - get/set name of current host
|
|
|
|
SYNOPSIS
|
|
gethostname(name, namelen)
|
|
char *name;
|
|
int namelen;
|
|
|
|
sethostname(name, namelen)
|
|
char *name;
|
|
int namelen;
|
|
|
|
DESCRIPTION
|
|
Gethostname returns the standard host name for the current
|
|
processor, as previously set by sethostname. The parameter
|
|
namelen specifies the size of the name array. The returned name
|
|
is null-terminated unless insufficient space is provided.
|
|
|
|
Sethostname sets the name of the host machine to be name ,
|
|
which has length namelen . This call is restricted to the
|
|
super-user and is normally used only when the system is bootstrapped.
|
|
|
|
RETURN VALUE
|
|
If the call succeeds a value of 0 is returned. If the call
|
|
fails, then a value of -1 is returned and an error code is
|
|
placed in the global location \fIerrno\fP.
|
|
|
|
ERRORS
|
|
The following errors may be returned by these calls:
|
|
|
|
[EFAULT] The name or namelen parameter gave an
|
|
invalid address.
|
|
|
|
[EPERM] The caller tried to set the hostname and was not
|
|
the super-user.
|
|
|
|
SEE ALSO
|
|
gethostid(2)
|
|
|
|
BUGS
|
|
Host names are limited to MAXHOSTNAMELEN (from <sys/param.h> )
|
|
characters, currently 64.
|
|
|
|
OTHER INFO
|
|
This call is part of the Tnet library.
|
|
|
|
# gethostname
|
|
NAME
|
|
gethostname, sethostname - get/set name of current host
|
|
|
|
SYNOPSIS
|
|
gethostname(name, namelen)
|
|
char *name;
|
|
int namelen;
|
|
|
|
sethostname(name, namelen)
|
|
char *name;
|
|
int namelen;
|
|
|
|
DESCRIPTION
|
|
Gethostname returns the standard host name for the current
|
|
processor, as previously set by sethostname. The parameter
|
|
namelen specifies the size of the name array. The returned name
|
|
is null-terminated unless insufficient space is provided.
|
|
|
|
Sethostname sets the name of the host machine to be name ,
|
|
which has length namelen . This call is restricted to the
|
|
super-user and is normally used only when the system is bootstrapped.
|
|
|
|
RETURN VALUE
|
|
If the call succeeds a value of 0 is returned. If the call
|
|
fails, then a value of -1 is returned and an error code is
|
|
placed in the global location \fIerrno\fP.
|
|
|
|
ERRORS
|
|
The following errors may be returned by these calls:
|
|
|
|
[EFAULT] The name or namelen parameter gave an
|
|
invalid address.
|
|
|
|
[EPERM] The caller tried to set the hostname and was not
|
|
the super-user.
|
|
|
|
SEE ALSO
|
|
gethostid(2)
|
|
|
|
BUGS
|
|
Host names are limited to MAXHOSTNAMELEN (from <sys/param.h> )
|
|
characters, currently 64.
|
|
|
|
OTHER INFO
|
|
This call is part of the Tnet library.
|
|
|
|
# getpeername
|
|
NAME
|
|
getpeername - get name of connected peer
|
|
|
|
SYNOPSIS
|
|
getpeername(s, name, namelen)
|
|
int s;
|
|
struct sockaddr *name;
|
|
int *namelen;
|
|
|
|
DESCRIPTION
|
|
Getpeername returns the name of the peer connected to socket s .
|
|
The namelen parameter should be initialized to indicate the amount
|
|
of space pointed to by name . On return it contains the actual size
|
|
of the name returned (in bytes). The name is truncated if the
|
|
buffer provided is too small.
|
|
|
|
DIAGNOSTICS
|
|
A 0 is returned if the call succeeds, -1 if it fails.
|
|
|
|
ERRORS
|
|
The call succeeds unless:
|
|
|
|
[EBADF] The argument s is not a valid descriptor.
|
|
|
|
[ENOTSOCK] The argument s is a file, not a socket.
|
|
|
|
[ENOTCONN] The socket is not connected.
|
|
|
|
[ENOBUFS] Insufficient resources were available in the system
|
|
to perform the operation.
|
|
|
|
[EFAULT] The name parameter points to memory not in a valid
|
|
part of the process address space.
|
|
|
|
SEE ALSO
|
|
accept(2), bind(2), socket(2), getsockname(2)
|
|
|
|
OTHER INFO
|
|
This call is part of the Tnet library.
|
|
|
|
# getsockname
|
|
NAME
|
|
getsockname - get socket name
|
|
|
|
SYNOPSIS
|
|
getsockname(s, name, namelen)
|
|
int s;
|
|
struct sockaddr *name;
|
|
int *namelen;
|
|
|
|
DESCRIPTION
|
|
Getsockname returns the current name for the specified socket.
|
|
The namelen parameter should be initialized to indicate the amount
|
|
of space pointed to by name . On return it contains the actual
|
|
size of the name returned (in bytes).
|
|
|
|
DIAGNOSTICS
|
|
A 0 is returned if the call succeeds, \-1 if it fails.
|
|
|
|
ERRORS
|
|
The call succeeds unless:
|
|
|
|
[EBADF] The argument s is not a valid descriptor.
|
|
|
|
[ENOTSOCK] The argument s is a file, not a socket.
|
|
|
|
[ENOBUFS] Insufficient resources were available in the system
|
|
to perform the operation.
|
|
|
|
[EFAULT] The name parameter points to memory not in a valid
|
|
part of the process address space.
|
|
|
|
SEE ALSO
|
|
bind(2), socket(2)
|
|
|
|
BUGS
|
|
Names bound to sockets in the UNIX domain are inaccessible;
|
|
getsockname returns a zero length name.
|
|
|
|
OTHER INFO
|
|
This call is part of the Tnet library.
|
|
|
|
# getsockopt
|
|
NAME
|
|
getsockopt, setsockopt - get and set options on sockets
|
|
|
|
SYNOPSIS
|
|
#include <sys/types.h>
|
|
#include <sys/socket.h>
|
|
|
|
getsockopt(s, level, optname, optval, optlen)
|
|
int s, level, optname;
|
|
char *optval;
|
|
int *optlen;
|
|
|
|
setsockopt(s, level, optname, optval, optlen)
|
|
int s, level, optname;
|
|
char *optval;
|
|
int optlen;
|
|
|
|
DESCRIPTION
|
|
Getsockopt and setsockopt manipulate options associated with a
|
|
socket. Options may exist at multiple protocol levels; they are
|
|
always present at the uppermost ``socket'' level.
|
|
|
|
When manipulating socket options the level at which the
|
|
option resides and the name of the option must be specified.
|
|
To manipulate options at the ``socket'' level, level is specified
|
|
as SOL_SOCKET. To manipulate options at any other level the
|
|
protocol number of the appropriate protocol controlling the option
|
|
is supplied. For example, to indicate that an option is to be
|
|
interpreted by the TCP protocol, level should be set to the
|
|
protocol number of TCP; see getprotoent(3N).
|
|
|
|
The parameters optval and optlen are used to access option values
|
|
for setsockopt . For getsockopt they identify a buffer in which
|
|
the value for the requested option(s) are to be returned. For
|
|
getsockopt , optlen is a value-result parameter, initially
|
|
containing the size of the buffer pointed to by optval , and
|
|
modified on return to indicate the actual size of the value
|
|
returned. If no option value is to be supplied or returned,
|
|
optval may be supplied as 0.
|
|
|
|
Optname and any specified options are passed uninterpreted to the
|
|
appropriate protocol module for interpretation. The include file
|
|
< sys/socket.h > contains definitions for ``socket'' level options,
|
|
described below. Options at other protocol levels vary in format and
|
|
name; consult the appropriate entries in section (4P).
|
|
|
|
Most socket-level options take an int parameter for optval . For
|
|
setsockopt , the parameter should non-zero to enable a boolean
|
|
option, or zero if the option is to be disabled. SO_LINGER uses a
|
|
struct linger parameter, defined in < sys/socket.h >, which
|
|
specifies the desired state of the option and the linger interval
|
|
(see below).
|
|
|
|
The following options are recognized at the socket level.
|
|
Except as noted, each may be examined with getsockopt and set with
|
|
setsockopt .
|
|
|
|
SO_BROADCAST
|
|
SO_DEBUG toggle recording of debugging information
|
|
SO_REUSEADDR toggle local address reuse
|
|
SO_KEEPALIVE toggle keep connections alive
|
|
SO_DONTROUTE toggle routing bypass for outgoing messages
|
|
SO_LINGER linger on close if data present
|
|
SO_BROADCAST toggle permission to transmit broadcast messages
|
|
SO_OOBINLINE toggle reception of out-of-band data in band
|
|
SO_SNDBUF set buffer size for output
|
|
SO_RCVBUF set buffer size for input
|
|
SO_TYPE get the type of the socket (get only)
|
|
SO_ERROR get and clear error on the socket (get only)
|
|
|
|
SO_DEBUG enables debugging in the underlying protocol modules.
|
|
SO_REUSEADDR indicates that the rules used in validating addresses
|
|
supplied in a bind(2) call should allow reuse of local addresses.
|
|
SO_KEEPALIVE enables the periodic transmission of messages on a
|
|
connected socket. Should the connected party fail to respond to
|
|
these messages, the connection is considered broken and processes
|
|
using the socket are notified via a SIGPIPE signal. SO_DONTROUTE
|
|
indicates that outgoing messages should bypass the standard routing
|
|
facilities. Instead, messages are directed to the appropriate
|
|
network interface according to the network portion of the
|
|
destination address.
|
|
|
|
SO_LINGER controls the action taken when unsent messags are queued
|
|
on socket and a close(2) is performed. If the socket promises
|
|
reliable delivery of data and SO_LINGER is set, the system will
|
|
block the process on the close attempt until it is able to transmit
|
|
the data or until it decides it is unable to deliver the information
|
|
(a timeout period, termed the linger interval, is specified in the
|
|
setsockopt call when SO_LINGER is requested).
|
|
If SO_LINGER is disabled and a close is issued, the system will
|
|
process the close in a manner that allows the process to continue
|
|
as quickly as possible.
|
|
|
|
The option SO_BROADCAST requests permission to send broadcast
|
|
datagrams on the socket.
|
|
Broadcast was a privileged operation in earlier versions of the
|
|
system. With protocols that support out-of-band data, the
|
|
SO_OOBINLINE option requests that out-of-band data be placed in
|
|
the normal data input queue as received; it will then be accessible
|
|
with recv or read calls without the MSG_OOB flag.
|
|
|
|
SO_SNDBUF and SO_RCVBUF are options to adjust the normal
|
|
buffer sizes allocated for output and input buffers, respectively.
|
|
The buffer size may be increased for high-volume connections,
|
|
or may be decreased to limit the possible backlog of incoming data.
|
|
The system places an absolute limit on these values.
|
|
Finally, SO_TYPE and SO_ERROR are options used only with setsockopt .
|
|
SO_TYPE returns the type of the socket, such as SOCK_STREAM;
|
|
it is useful for servers that inherit sockets on startup.
|
|
SO_ERROR returns any pending error on the socket and clears
|
|
the error status.
|
|
It may be used to check for asynchronous errors on connected
|
|
datagram sockets or for other asynchronous errors.
|
|
|
|
RETURN VALUE
|
|
A 0 is returned if the call succeeds, \-1 if it fails.
|
|
|
|
ERRORS
|
|
The call succeeds unless:
|
|
|
|
[EBADF] The argument s is not a valid descriptor.
|
|
|
|
[ENOTSOCK] The argument s is a file, not a socket.
|
|
|
|
[ENOPROTOOPT] The option is unknown at the level indicated.
|
|
|
|
[EFAULT] The address pointed to by optval is not in a valid
|
|
part of the process address space.
|
|
For getsockopt , this error may also be returned
|
|
if optlen is not in a valid part of the process
|
|
address space.
|
|
|
|
SEE ALSO
|
|
ioctl(2), socket(2), getprotoent(3N)
|
|
|
|
BUGS
|
|
Several of the socket options should be handled at lower levels of
|
|
the system.
|
|
|
|
OTHER INFO
|
|
This call is part of the Tnet library.
|
|
|
|
# listen
|
|
NAME
|
|
listen - listen for connections on a socket
|
|
|
|
SYNOPSIS
|
|
listen(s, backlog)
|
|
int s, backlog;
|
|
|
|
DESCRIPTION
|
|
To accept connections, a socket is first created with socket(2),
|
|
a willingness to accept incoming connections and a queue limit for
|
|
incoming connections are specified with listen(2), and then the
|
|
connections are accepted with accept(2).
|
|
The listen call applies only to sockets of type SOCK_STREAM or
|
|
SOCK_SEQPACKET.
|
|
|
|
The backlog parameter defines the maximum length the queue of
|
|
pending connections may grow to. If a connection request arrives
|
|
with the queue full the client may receive an error with an
|
|
indication of ECONNREFUSED, or, if the underlying protocol supports
|
|
retransmission, the request may be ignored so that retries may
|
|
succeed.
|
|
|
|
RETURN VALUE
|
|
A 0 return value indicates success; -1 indicates an error.
|
|
|
|
ERRORS
|
|
The call fails if:
|
|
|
|
[EBADF] The argument s is not a valid descriptor.
|
|
|
|
[ENOTSOCK] The argument s is not a socket.
|
|
|
|
[EOPNOTSUPP] The socket is not of a type that supports the
|
|
operation listen.
|
|
|
|
SEE ALSO
|
|
accept(2), connect(2), socket(2)
|
|
|
|
BUGS
|
|
The backlog is currently limited (silently) to 5.
|
|
|
|
OTHER INFO
|
|
This call is part of the Tnet library.
|
|
|
|
# recv
|
|
NAME
|
|
recv, recvfrom, recvmsg - receive a message from a socket
|
|
|
|
SYNOPSIS
|
|
#include <sys/types.h>
|
|
#include <sys/socket.h>
|
|
|
|
cc = recv(s, buf, len, flags)
|
|
int cc, s;
|
|
char *buf;
|
|
int len, flags;
|
|
|
|
cc = recvfrom(s, buf, len, flags, from, fromlen)
|
|
int cc, s;
|
|
char *buf;
|
|
int len, flags;
|
|
struct sockaddr *from;
|
|
int *fromlen;
|
|
|
|
cc = recvmsg(s, msg, flags)
|
|
int cc, s;
|
|
struct msghdr *msg;
|
|
int flags;
|
|
|
|
DESCRIPTION
|
|
Recvfrom , and recvmsg are used to receive messages from a socket,
|
|
and may be used to receive data on a socket whether it is in a
|
|
connected state or not.
|
|
|
|
If from is non-zero, the source address of the message is filled in.
|
|
Fromlen is a value-result parameter, initialized to the size of the
|
|
buffer associated with from , and modified on return to indicate the
|
|
actual size of the address stored there.
|
|
|
|
The recv call is normally used only on a connected socket (see
|
|
connect(2)) and is identitical to recfrom with a zero-valued
|
|
fromlen parameter.
|
|
As it is redundant, it may not be supported in future releases.
|
|
|
|
The length of the message is returned in cc . If a message is too
|
|
long to fit in the supplied buffer, excess bytes may be discarded
|
|
depending on the type of socket the message is received from (see
|
|
socket(2)).
|
|
|
|
If no messages are available at the socket, the receive call waits
|
|
for a message to arrive, unless the socket is nonblocking (see
|
|
ioctl(2)) in which case a cc -1 is returned with the external
|
|
variable errno set to EWOULDBLOCK.
|
|
|
|
The select(2) call may be used to determine when more data arrives.
|
|
|
|
The flags argument to a recv call is formed by or'ing one or more
|
|
of the values,
|
|
|
|
#define MSG_OOB 0x1 /* process out-of-band data */
|
|
#define MSG_PEEK 0x2 /* peek at incoming message */
|
|
#define MSG_DONTROUTE 0x4 /* send without using routing tables */
|
|
#define MSG_EOR 0x8 /* data completes record */
|
|
#define MSG_TRUNC 0x10 /* data discarded before delivery */
|
|
#define MSG_CTRUNC 0x20 /* control data lost before delivery */
|
|
|
|
The recvmsg call uses a msghdr structure to minimize the number of
|
|
directly supplied parameters. This structure has the following form,
|
|
as defined in <sys/socket.h> :
|
|
|
|
struct msghdr {
|
|
caddr_t msg_name; /* optional address */
|
|
u_int msg_namelen; /* size of address */
|
|
struct iovec *msg_iov; /* scatter/gather array */
|
|
u_int msg_iovlen; /* # elements in msg_iov */
|
|
caddr_t msg_control; /* ancillary data, see below */
|
|
u_int msg_controllen; /* ancillary data buffer len */
|
|
int msg_flags; /* flags on received message */
|
|
};
|
|
|
|
Here msg_name and msg_namelen specify the destination address if
|
|
the socket is unconnected; msg_name may be given as a null pointer
|
|
if no names are desired or required. The msg_iov and msg_iovlen
|
|
describe the scatter gather locations, as described in read(2).
|
|
|
|
msg_control , which has length msg_controllen .
|
|
This is a buffer for other protocol control related messages
|
|
or other miscellaneous ancillary data. The messages are of the form:
|
|
|
|
struct cmsghdr {
|
|
u_int cmsg_len; /* data byte count, including hdr */
|
|
int cmsg_level; /* originating protocol */
|
|
int cmsg_type; /* protocol-specific type */
|
|
/* followed by
|
|
u_char cmsg_data[]; */
|
|
};
|
|
|
|
As an example, one could use this to learn of changes in the
|
|
data-stream in XNS/SPP, or in ISO, to obtain user-connection-request
|
|
data by requesting a recvmsg with no uio provided immediately after
|
|
an accept(), thought of here in the sense of get-next-connection-
|
|
request without an implicit connection confirmation.
|
|
|
|
Open file descriptors are now passed as ancillary data for AF_UNIX
|
|
domain sockets, with cmsg_level being SOL_SOCKET and cmsg_type being
|
|
SCM_RIGHTS.
|
|
|
|
msg_flags is set on return in a way that may include some of the
|
|
same values specified for the flags parameter to a recv system call.
|
|
The returned values MSG_EOR indicates end-of-record, MSG_TRUNC
|
|
indicates that some trailing datagram data was discarded,
|
|
MSG_CTRUNC indicates that some control data was discarded due to
|
|
lack of space. MSG_OOB is returned to indicate that expedited data
|
|
was received.
|
|
|
|
RETURN VALUE
|
|
These calls return the number of bytes received, or -1 if an error
|
|
occurred.
|
|
|
|
ERRORS
|
|
The calls fail if:
|
|
|
|
[EBADF] The argument s is an invalid descriptor.
|
|
|
|
[ENOTSOCK] The argument s is not a socket.
|
|
|
|
[EWOULDBLOCK] The socket is marked non-blocking and the receive
|
|
operation would block.
|
|
|
|
[EINTR] The receive was interrupted by delivery of a signal
|
|
before any data was available for the receive.
|
|
|
|
[EFAULT] The data was specified to be received into a
|
|
non-existent or protected part of the process
|
|
address space.
|
|
|
|
SEE ALSO
|
|
fcntl(2), read(2), send(2), select(2), getsockopt(2), socket(2)
|
|
|
|
OTHER INFO
|
|
This call is part of the Tnet library.
|
|
|
|
# send
|
|
NAME
|
|
send, sendto, sendmsg - send a message from a socket
|
|
|
|
SYNOPSIS
|
|
#include <sys/types.h>
|
|
#include <sys/socket.h>
|
|
|
|
cc = send(s, msg, len, flags)
|
|
int cc, s;
|
|
char *msg;
|
|
int len, flags;
|
|
|
|
cc = sendto(s, msg, len, flags, to, tolen)
|
|
int cc, s;
|
|
char *msg;
|
|
int len, flags;
|
|
struct sockaddr *to;
|
|
int tolen;
|
|
|
|
cc = sendmsg(s, msg, flags)
|
|
int cc, s;
|
|
struct msghdr *msg;
|
|
int flags;
|
|
|
|
DESCRIPTION
|
|
Send , sendto , and sendmsg are used to transmit a message to
|
|
another socket. Send may be used only when the socket is in a
|
|
connected state, while sendto and endmsg may be used at any time.
|
|
|
|
The address of the target is given by to with tolen specifying
|
|
its size. The length of the message is given by len .
|
|
If the message is too long to pass atomically through the
|
|
underlying protocol, then the error EMSGSIZE is returned, and
|
|
the message is not transmitted.
|
|
|
|
No indication of failure to deliver is implicit in a
|
|
send . Return values of -1 indicate some locally detected errors.
|
|
|
|
If no messages space is available at the socket to hold
|
|
the message to be transmitted, then send normally blocks, unless
|
|
the socket has been placed in non-blocking I/O mode.
|
|
The select(2) call may be used to determine when it is possible to
|
|
send more data.
|
|
|
|
The flags parameter may include one or more of the following:
|
|
|
|
#define MSG_OOB 0x1 /* process out-of-band data */
|
|
#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */
|
|
|
|
The flag MSG_OOB is used to send out-of-band data on sockets that
|
|
support this notion (e.g. SOCK_STREAM); the underlying protocol
|
|
must also support out-of-band data.
|
|
MSG_DONTROUTE is usually used only by diagnostic or routing programs.
|
|
|
|
See recv(2) for a description of the msghdr structure.
|
|
|
|
RETURN VALUE
|
|
The call returns the number of characters sent, or -1
|
|
if an error occurred.
|
|
|
|
ERRORS
|
|
[EBADF] An invalid descriptor was specified.
|
|
|
|
[ENOTSOCK] The argument s is not a socket.
|
|
|
|
[EFAULT] An invalid user space address was specified for a
|
|
parameter.
|
|
|
|
[EMSGSIZE] The socket requires that message be sent atomically,
|
|
and the size of the message to be sent made this
|
|
impossible.
|
|
|
|
[EWOULDBLOCK] The socket is marked non-blocking and the requested
|
|
operation would block.
|
|
|
|
[ENOBUFS] The system was unable to allocate an internal buffer.
|
|
The operation may succeed when buffers become
|
|
available.
|
|
|
|
[ENOBUFS] The output queue for a network interface was full.
|
|
This generally indicates that the interface has
|
|
stopped sending, but may be caused by transient
|
|
congestion.
|
|
|
|
SEE ALSO
|
|
fcntl(2), recv(2), select(2), getsockopt(2), socket(2), write(2)
|
|
|
|
OTHER INFO
|
|
This call is part of the Tnet library.
|
|
|
|
# socket
|
|
NAME
|
|
socket - create an endpoint for communication
|
|
|
|
SYNOPSIS
|
|
#include <sys/types.h>
|
|
#include <sys/socket.h>
|
|
|
|
s = socket(domain, type, protocol)
|
|
int s, domain, type, protocol;
|
|
|
|
DESCRIPTION
|
|
Socket creates an endpoint for communication and returns a
|
|
descriptor.
|
|
|
|
The domain parameter specifies a communications domain within which
|
|
communication will take place; this selects the protocol family
|
|
which should be used.
|
|
The protocol family generally is the same as the address family
|
|
for the addresses supplied in later operations on the socket.
|
|
These families are defined in the include file <sys/socket.h> .
|
|
The currently understood formats are
|
|
|
|
PF_UNIX (UNIX internal protocols),
|
|
PF_INET (ARPA Internet protocols),
|
|
PF_NS (Xerox Network Systems protocols), and
|
|
PF_IMPLINK (IMP host at IMP link layer).
|
|
|
|
The socket has the indicated type, which specifies the semantics
|
|
of communication. Currently defined types are:
|
|
|
|
SOCK_STREAM
|
|
SOCK_DGRAM
|
|
SOCK_RAW
|
|
SOCK_SEQPACKET
|
|
SOCK_RDM
|
|
|
|
A SOCK_STREAM type provides sequenced, reliable,
|
|
two-way connection based byte streams.
|
|
An out-of-band data transmission mechanism may be supported.
|
|
A SOCK_DGRAM socket supports
|
|
datagrams (connectionless, unreliable messages of
|
|
a fixed (typically small) maximum length).
|
|
A SOCK_SEQPACKET socket may provide a sequenced, reliable,
|
|
two-way connection-based data transmission path for datagrams
|
|
of fixed maximum length; a consumer may be required to read
|
|
an entire packet with each read system call.
|
|
This facility is protocol specific, and presently implemented
|
|
only for PF_NS.
|
|
SOCK_RAW sockets provide access to internal network protocols and
|
|
interfaces. The types SOCK_RAW, which is available only to the
|
|
super-user, and SOCK_RDM, which is planned, but not yet
|
|
implemented, are not described here.
|
|
|
|
The protocol specifies a particular protocol to be used with the
|
|
socket. Normally only a single protocol exists to support a
|
|
particular socket type within a given protocol family. However,
|
|
it is possible that many protocols may exist, in which case a
|
|
particular protocol must be specified in this manner. The protocol
|
|
number to use is particular to the communication domain in which
|
|
communication is to take place; see protocols(3N).
|
|
|
|
Sockets of type SOCK_STREAM are full-duplex byte streams, similar
|
|
to pipes. A stream socket must be in a connected state before any
|
|
data may be sent or received on it. A connection to another socket
|
|
is created with a connect(2) call. Once connected, data may be
|
|
transferred using read(2) and write(2) calls or some variant of the
|
|
send(2) and recv(2) calls. When a session has been completed a
|
|
close(2) may be performed.
|
|
|
|
Out-of-band data may also be transmitted as described in send(2)
|
|
and received as described in recv(2).
|
|
|
|
The communications protocols used to implement a SOCK_STREAM insure
|
|
that data is not lost or duplicated. If a piece of data for which
|
|
the peer protocol has buffer space cannot be successfully transmitted
|
|
within a reasonable length of time, then the connection is
|
|
considered broken and calls will indicate an error with -1 returns
|
|
and with ETIMEDOUT as the specific code in the global variable errno.
|
|
The protocols optionally keep sockets warm by forcing transmissions
|
|
roughly every minute in the absence of other activity.
|
|
An error is then indicated if no response can be elicited on an
|
|
otherwise idle connection for a extended period (e.g. 5 minutes).
|
|
A SIGPIPE signal is raised if a process sends on a broken stream;
|
|
this causes naive processes, which do not handle the signal, to exit.
|
|
|
|
SOCK_SEQPACKET sockets employ the same system calls as SOCK_STREAM
|
|
sockets. The only difference is that read(2) calls will return
|
|
only the amount of data requested, and any remaining in the
|
|
arriving packet will be discarded.
|
|
|
|
SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams to
|
|
correspondents named in send(2) calls. Datagrams are generally
|
|
received with recvfrom(2), which returns the next datagram with
|
|
its return address.
|
|
|
|
An fcntl(2) call can be used to specify a process group to receive
|
|
a SIGURG signal when the out-of-band data arrives. It may also
|
|
enable non-blocking I/O and asynchronous notification of I/O events
|
|
via SIGIO.
|
|
|
|
The operation of sockets is controlled by socket level options .
|
|
These options are defined in the file < sys/socket.h >.
|
|
Setsockopt(2) and getsockopt(2) are used to set and get options,
|
|
respectively.
|
|
|
|
RETURN VALUE
|
|
A -1 is returned if an error occurs, otherwise the return
|
|
value is a descriptor referencing the socket.
|
|
|
|
ERRORS
|
|
The socket call fails if:
|
|
|
|
[EPROTONOSUPPORT] The protocol type or the specified protocol
|
|
is not supported within this domain.
|
|
|
|
[EMFILE] The per-process descriptor table is full.
|
|
|
|
[ENFILE] The system file table is full.
|
|
|
|
[EACCESS] Permission to create a socket of the
|
|
specified type and/or protocol is denied.
|
|
|
|
[ENOBUFS] Insufficient buffer space is available.
|
|
The socket cannot be created until
|
|
sufficient resources are freed.
|
|
|
|
SEE ALSO
|
|
accept(2), bind(2), connect(2), getsockname(2), getsockopt(2),
|
|
ioctl(2), listen(2), read(2), recv(2),
|
|
send(2), shutdown(2), socketpair(2), write(2)
|
|
|
|
``An Introductory 4.3BSD Interprocess Communication Tutorial.''
|
|
``An Advanced 4.3BSD Interprocess Communication Tutorial.''
|
|
|
|
OTHER INFO
|
|
This call is part of the Tnet library.
|
|
|
|
# socketpair
|
|
NAME
|
|
socketpair - create a pair of connected sockets
|
|
|
|
SYNOPSIS
|
|
#include <sys/types.h>
|
|
#include <sys/socket.h>
|
|
|
|
socketpair(d, type, protocol, sv)
|
|
int d, type, protocol;
|
|
int sv[2];
|
|
|
|
DESCRIPTION
|
|
The socketpair call creates an unnamed pair of connected sockets in
|
|
the specified domain d , of the specified type , and using the
|
|
optionally specified protocol .
|
|
The descriptors used in referencing the new sockets are returned in
|
|
sv[0] and sv[1]. The two sockets are indistinguishable.
|
|
|
|
DIAGNOSTICS
|
|
A 0 is returned if the call succeeds, -1 if it fails.
|
|
|
|
ERRORS
|
|
The call succeeds unless:
|
|
|
|
[EMFILE] Too many descriptors are in use by this process.
|
|
|
|
[EAFNOSUPPORT] The specified address family is not supported on
|
|
this machine.
|
|
|
|
[EPROTONOSUPPORT] The specified protocol is not supported on this
|
|
machine.
|
|
|
|
[EOPNOSUPPORT] The specified protocol does not support creation of
|
|
socket pairs.
|
|
|
|
[EFAULT] The address sv does not specify a valid part of the
|
|
process address space.
|
|
|
|
SEE ALSO
|
|
read(2), write(2), pipe(2)
|
|
|
|
BUGS
|
|
This call is currently implemented only for the UNIX domain.
|
|
|
|
OTHER INFO
|
|
This call is part of the Tnet library.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|