.BI "int access(const char *" pathname ", int " mode );
.fi
.SH DESCRIPTION
-.B access
+.BR access ()
checks whether the process would be allowed to read,
write or test for existence of the file (or other file system
object) whose name is
.I errno
is set appropriately.
.SH ERRORS
-.B access
+.BR access ()
shall fail if:
.TP
.B EACCES
.B EROFS
Write permission was requested for a file on a read-only filesystem.
.PP
-.B access
+.BR access ()
may fail if:
.TP
.B EFAULT
Write access was requested to an executable which is being
executed.
.SH RESTRICTIONS
-.B access
+.BR access ()
returns an error if any of the access types in the requested call
fails, even if other types might be successful.
.PP
-.B access
+.BR access ()
may not work correctly on NFS file systems with UID mapping enabled,
because UID mapping is done on the server and hidden from the client,
which checks permissions.
.PP
Using
-.B access
+.BR access ()
to check if a user is authorized to e.g. open a file before actually
doing so using
.BR open (2)
.SH DESCRIPTION
Linux uses David L. Mills' clock adjustment algorithm (see RFC\ 1305).
The system call
-.B adjtimex
+.BR adjtimex ()
reads and optionally sets adjustment parameters for this algorithm.
It takes a pointer to a
.I timex
.ne 12v
.SH "RETURN VALUE"
On success,
-.B adjtimex
+.BR adjtimex ()
returns the clock state:
.PP
.RS
.RE
.PP
On failure,
-.B adjtimex
+.BR adjtimex ()
returns \-1 and sets
.IR errno .
.SH ERRORS
.B CAP_SYS_TIME
capability is required.
.SH "CONFORMING TO"
-\fBadjtimex\fP is Linux specific and should not be used in programs
+\fBadjtimex\fP() is Linux specific and should not be used in programs
intended to be portable. There is a similar but less general call
\fBadjtime\fR in SVr4.
.SH "SEE ALSO"
If
.I seconds
is zero, no new
-.B alarm
+.BR alarm ()
is scheduled.
In any event any previously set
-.B alarm
+.BR alarm ()
is cancelled.
.SH "RETURN VALUE"
-.B alarm
+.BR alarm ()
returns the number of seconds remaining until any previously scheduled
alarm was due to be delivered, or zero if there was no previously
scheduled alarm.
.\" asmlinkage int sys_free_hugepages(unsigned long addr);
.SH DESCRIPTION
The system calls
-.B alloc_hugepages
+.BR alloc_hugepages ()
and
-.B free_hugepages
+.BR free_hugepages ()
were introduced in Linux 2.5.36 and removed again in 2.5.54.
They existed only on i386 and ia64 (when built with CONFIG_HUGETLB_PAGE).
In Linux 2.4.20 the syscall numbers exist, but the calls return ENOSYS.
.IR
.SH "RETURN VALUE"
On success,
-.B alloc_hugepages
+.BR alloc_hugepages ()
returns the allocated virtual address, and
-.B free_hugepages
+.BR free_hugepages ()
returns zero. On error, \-1 is returned, and
.I errno
is set appropriately.
.BI "int arch_prctl(int code, unsigned long addr)"
.SH DESCRIPTION
The
-.B arch_prctl
+.BR arch_prctl ()
function sets architecture specific process or thread state.
.I code
selects a subfunction
or using the
.BR set_thread_area (2)
system call in a 2.5 kernel.
-.B arch_prctl
+.BR arch_prctl ()
is only needed when you want to set bases that are larger than 4GB.
Memory in the first 2GB of address space can be allocated by using
.BR mmap (2)
.BI "int bdflush(int " func ", long " data );
.fi
.SH DESCRIPTION
-.B bdflush
+.BR bdflush ()
starts, flushes, or tunes the buffer-dirty-flush daemon.
Only a privileged process (one with the
.B CAP_SYS_ADMIN
capability) may call
-.BR bdflush .
+.BR bdflush ().
.PP
If
.I func
is negative or 0, and no daemon has been started, then
-.B bdflush
+.BR bdflush ()
enters the daemon code and never returns.
.PP
If
If
.I func
is negative or 0 and the daemon successfully starts,
-.B bdflush
+.BR bdflush ()
never returns.
Otherwise, the return value is 0 on success and \-1 on failure, with
.I errno
.B CAP_SYS_ADMIN
capability.
.SH "CONFORMING TO"
-\fBbdflush\fP is Linux specific and should not be used in programs
+\fBbdflush\fP() is Linux specific and should not be used in programs
intended to be portable.
.SH "SEE ALSO"
.BR fsync (2),
.sp
.BI "void *sbrk(intptr_t " increment );
.SH DESCRIPTION
-.B brk
+.BR brk ()
sets the end of the data segment to the value specified by
.IR end_data_segment ,
when that value is reasonable, the system does have enough memory
and the process does not exceed its max data size (see
.BR setrlimit (2)).
-.B sbrk
+.BR sbrk ()
increments the program's data space by
.I increment
bytes.
-.B sbrk
+.BR sbrk ()
isn't a system call, it is just a C library wrapper.
Calling
-.B sbrk
+.BR sbrk ()
with an increment of 0 can be used to find the current
location of the program break.
.SH "RETURN VALUE"
On success,
-.B brk
+.BR brk ()
returns zero, and
-.B sbrk
+.BR sbrk ()
returns a pointer to the start of the new area. On error, \-1 is returned,
and
.I errno
.BI "int cacheflush(char *" addr ", int "nbytes ", int "cache );
.fi
.SH DESCRIPTION
-.B cacheflush
+.BR cacheflush ()
flushes contents of indicated cache(s) for user addresses in the range
addr to (addr+nbytes-1). Cache may be one of:
.TP
.BR (ICACHE|DCACHE) .
.PP
.SH "RETURN VALUE"
-.B cacheflush
+.BR cacheflush ()
returns 0 on success or \-1 on error. If errors are detected,
errno will indicate the error.
.SH ERRORS
.br
.BI "int fchdir(int " fd );
.SH DESCRIPTION
-.B chdir
+.BR chdir ()
changes the current directory to that specified in
.IR path .
.PP
-.B fchdir
+.BR fchdir ()
is identical to
-.BR chdir ;
+.BR chdir ();
the only difference is that the directory is given as an
open file descriptor.
.SH "RETURN VALUE"
.SH ERRORS
Depending on the file system, other errors can be returned. The more
general errors for
-.B chdir
+.BR chdir ()
are listed below:
.TP
.B EACCES
is not a directory.
.PP
The general errors for
-.B fchdir
+.BR fchdir ()
are listed below:
.TP
.B EACCES
is not a valid file descriptor.
.SH NOTES
The prototype for
-.B fchdir
+.BR fchdir ()
is only available if
.B _BSD_SOURCE
is defined (either explicitly, or implicitly, by not defining
_POSIX_SOURCE or compiling with the \-ansi flag).
.SH "CONFORMING TO"
The
-.B chdir
+.BR chdir ()
call is compatible with SVr4, SVID, POSIX, X/OPEN, 4.4BSD. SVr4 documents
additional EINTR, ENOLINK, and EMULTIHOP error conditions but has
no ENOMEM. POSIX.1 does not have ENOMEM or ELOOP error conditions.
X/OPEN does not have EFAULT, ENOMEM or EIO error conditions.
The
-.B fchdir
+.BR fchdir ()
call is compatible with SVr4, 4.4BSD and X/OPEN.
SVr4 documents additional EIO, EINTR, and ENOLINK error conditions.
X/OPEN documents additional EINTR and EIO error conditions.
.SH ERRORS
Depending on the file system, other errors can be returned. The more
general errors for
-.B chmod
+.BR chmod ()
are listed below:
.TP
The named file resides on a read-only file system.
.PP
The general errors for
-.B fchmod
+.BR fchmod ()
are listed below:
.TP
.B EBADF
See above.
.SH "CONFORMING TO"
The
-.B chmod
+.BR chmod ()
call conforms to SVr4, SVID, POSIX, X/OPEN, 4.4BSD.
SVr4 documents EINTR, ENOLINK and EMULTIHOP returns, but no
ENOMEM. POSIX.1 does not document EFAULT, ENOMEM, ELOOP or EIO error
conditions, or the macros \fBS_IREAD\fP, \fBS_IWRITE\fP and \fBS_IEXEC\fP.
.PP
The
-.B fchmod
+.BR fchmod ()
call conforms to 4.4BSD and SVr4.
SVr4 documents additional EINTR and ENOLINK error conditions.
POSIX requires the
-.B fchmod
+.BR fchmod ()
function if at least one of
.B _POSIX_MAPPED_FILES
and
.SH ERRORS
Depending on the file system, other errors can be returned. The more
general errors for
-.B chown
+.BR chown ()
are listed below.
.TP
.B EACCES
The named file resides on a read-only file system.
.PP
The general errors for
-.B fchown
+.BR fchown ()
are listed below:
.TP
.B EBADF
See above.
.SH NOTES
In versions of Linux prior to 2.1.81 (and distinct from 2.1.46),
-.B chown
+.BR chown ()
did not follow symbolic links.
Since Linux 2.1.81,
-.B chown
+.BR chown ()
does follow symbolic links, and there is a new system call
-.B lchown
+.BR lchown ()
that does not follow symbolic links.
Since Linux 2.1.86, this new call (that has the same semantics
as the old
-.BR chown )
+.BR chown ())
has got the same syscall number, and
-.B chown
+.BR chown ()
got the newly introduced number.
.LP
The prototype for
-.B fchown
+.BR fchown ()
is only available if
.B _BSD_SOURCE
is defined (either explicitly, or implicitly, by not defining
_POSIX_SOURCE or compiling with the \-ansi flag).
.SH "CONFORMING TO"
The
-.B chown
+.BR chown ()
call conforms to SVr4, SVID, POSIX, X/OPEN. The 4.4BSD version can only be
used by the superuser (that is, ordinary users cannot give away files).
SVr4 documents EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no
ENOMEM. POSIX.1 does not document ENOMEM or ELOOP error conditions.
.PP
The
-.B fchown
+.BR fchown ()
call conforms to 4.4BSD and SVr4.
SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK error conditions.
.SH RESTRICTIONS
.sp
.BI "int chroot(const char *" path );
.SH DESCRIPTION
-.B chroot
+.BR chroot ()
changes the root directory to that specified in
.IR path .
This directory will be used for path names beginning with /. The root
.BR clone ()
is a library function layered on top
of the underlying
-.BR clone
+.BR clone ()
system call, hereinafter referred to as
.BR sys_clone .
A description of
and
.B CLONE_FS
in the same
-.BR clone
+.BR clone ()
call.
.TP
.B CLONE_SIGHAND
previous
.BR write (2)
operation are first reported at the final
-.BR close .
+.BR close ().
Not checking the return value when closing the file may lead to
silent loss of data. This can especially be observed with NFS
and with disk quota.
.sp
.BI "int fdatasync(int " fd );
.SH DESCRIPTION
-.B fdatasync
+.BR fdatasync ()
flushes all data buffers of a file to disk (before the system
call returns). It resembles
.B fsync
data and another one in order to update the modification time stored
in the inode. If the modification time is not a part of the transaction
concept
-.B fdatasync
+.BR fdatasync ()
can be used to avoid unnecessary inode disk write operations.
.SH "RETURN VALUE"
On success, zero is returned. On error, \-1 is returned, and
is bound to a special file which does not support synchronization.
.SH BUGS
Currently (Linux 2.2)
-.B fdatasync
+.BR fdatasync ()
is equivalent to
.BR fsync .
.SH AVAILABILITY
On POSIX systems on which
-.B fdatasync
+.BR fdatasync ()
is available,
.B _POSIX_SYNCHRONIZED_IO
is defined in <unistd.h> to a value greater than 0. (See also
.sp
.B pid_t fork(void);
.SH DESCRIPTION
-.B fork
+.BR fork ()
creates a child process that differs from the parent process only in its
PID and PPID, and in the fact that resource utilizations are set to 0.
File locks and pending signals are not inherited.
.PP
Under Linux,
-.B fork
+.BR fork ()
is implemented using copy-on-write pages, so the only penalty incurred by
fork is the time and memory required to duplicate the parent's page tables,
and to create a unique task structure for the child.
.SH ERRORS
.TP
.B EAGAIN
-.B fork
+.BR fork ()
cannot allocate sufficient memory to copy the parent's page tables and
allocate a task structure for the child.
.TP
capability.
.TP
.B ENOMEM
-.B fork
+.BR fork ()
failed to allocate the necessary kernel structures because memory is tight.
.SH "CONFORMING TO"
The
-.B fork
+.BR fork ()
call conforms to SVr4, SVID, POSIX, X/OPEN, 4.3BSD.
.SH "SEE ALSO"
.BR clone (2),
.sp
.BI "int fdatasync(int " fd );
.SH DESCRIPTION
-.B fsync
+.BR fsync ()
copies all in-core parts of a file to disk, and waits until the
device reports that all parts are on stable storage.
It also updates metadata stat information. It does not necessarily ensure
that the entry in the directory containing the file has also reached disk.
For that an explicit
-.B fsync
+.BR fsync ()
on the file descriptor of the directory is also needed.
-.B fdatasync
+.BR fdatasync ()
does the same as
-.B fsync
+.BR fsync ()
but only flushes user data, not the meta data like the st_atime or
st_mtime
(respectively, time of last access and
.SH NOTES
In case the hard disk has write cache enabled,
the data may not really be on permanent storage when
-.BR fsync / fdatasync
+.BR fsync ()/ fdatasync
return.
.\" See
.\" .BR hdparm (8)
When an ext2 file system is mounted with the
.I sync
option, directory entries are also implicitly synced by
-.BR fsync .
+.BR fsync ().
.LP
On kernels before 2.4,
-.B fsync
+.BR fsync ()
on big files can be inefficient.
An alternative might be to use the
.I O_SYNC
.SH "DESCRIPTION"
.PP
The
-.B futex
+.BR futex ()
system call provides a method for
a program to wait for a value at a given address to change, and a
method to wake up anyone waiting on a particular address (while the
addresses for the same memory in separate processes may not be
equal, the kernel maps them internally so the same memory mapped in
different locations will correspond for
-.B futex
+.BR futex ()
calls). It is typically used to
implement the contended case of a lock in shared memory, as
described in
.BI "int get_thread_area (struct user_desc *" u_info );
.SH "DESCRIPTION"
-.B get_thread_area
+.BR get_thread_area ()
returns an entry in the current thread's Thread Local Storage (TLS) array.
The index of the entry corresponds to the value
of \fIu_info->\fR\fIentry_number\fR, passed in by the user.
TLS entry into the area pointed to by \fIu_info\fR.
.SH "RETURN VALUE"
-.B get_thread_area
+.BR get_thread_area ()
returns 0 on success.
Otherwise, it returns \-1 and sets
.I errno
.B EINVAL
\fIu_info->\fR\fIentry_number\fR is out of bounds.
.SH "CONFORMING TO"
-.B get_thread_area
+.BR get_thread_area ()
is Linux specific and should not be used in programs
that are intended to be portable.
.SH AVAILABILITY
A version of
-.B get_thread_area
+.BR get_thread_area ()
first appeared in Linux 2.5.32.
.SH "SEE ALSO"
This page documents the bare kernel system call interface.
.PP
The system call
-.B getdents
+.BR getdents ()
reads several
.I dirent
structures from the directory
These functions are used to access or to change the domain name of the
current processor.
If the NUL-terminated domain name requires more than \fIlen\fP bytes,
-.B getdomainname
+.BR getdomainname ()
returns the first \fIlen\fP bytes (glibc) or returns an error (libc).
.SH "RETURN VALUE"
On success, zero is returned. On error, \-1 is returned, and
.TP
.B EFAULT
For
-.BR setdomainname :
+.BR setdomainname ():
.I name
pointed outside of user address space.
.TP
.B EINVAL
For
-.BR getdomainname
+.BR getdomainname ()
under libc:
.I name
is
.TP
.B EINVAL
For
-.BR setdomainname :
+.BR setdomainname ():
.I len
was negative or too large.
.TP
.B EPERM
For
-.BR setdomainname :
+.BR setdomainname ():
the caller is unprivileged (Linux: does not have the
.B CAP_SYS_ADMIN
capability).
.sp
.B int getdtablesize(void);
.SH DESCRIPTION
-.B getdtablesize
+.BR getdtablesize ()
returns the maximum number of files a process can have open,
one more than the largest possible value for a file descriptor.
.SH "RETURN VALUE"
The current limit on the number of open files per process.
.SH NOTES
-.B getdtablesize
+.BR getdtablesize ()
is implemented as a libc library function. The glibc version calls
.BR getrlimit (2)
and returns the current
(set to 256 since Linux 0.98.4).
.SH "CONFORMING TO"
SVr4, 4.4BSD (the
-.B getdtablesize
+.BR getdtablesize ()
function first appeared in 4.2BSD).
.SH "SEE ALSO"
.BR close (2),
.br
.B gid_t getegid(void);
.SH DESCRIPTION
-.B getgid
+.BR getgid ()
returns the real group ID of the current process.
-.B getegid
+.BR getegid ()
returns the effective group ID of the current process.
.SH ERRORS
These functions are always successful.
.BI "int setgroups(size_t " size ", const gid_t *" list );
.SH DESCRIPTION
.TP
-.B getgroups
+.BR getgroups ()
Up to
.I size
supplementary group IDs (of the calling process) are returned in
is not modified, but the total number of supplementary group IDs for the
process is returned.
.TP
-.B setgroups
+.BR setgroups ()
Sets the supplementary group IDs for the process.
Appropriate privileges (Linux: the
.B CAP_SETGID
capability) are required.
.SH "RETURN VALUE"
.TP
-.B getgroups
+.BR getgroups ()
On success, the number of supplementary group IDs is returned.
On error, \-1 is returned, and
.I errno
is set appropriately.
.TP
-.B setgroups
+.BR setgroups ()
On success, zero is returned. On error, \-1 is returned, and
.I errno
is set appropriately.
.TP
.B EINVAL
For
-.BR setgroups ,
+.BR setgroups (),
.I size
is greater than
.B NGROUPS
(32 for Linux 2.0.32).
For
-.BR getgroups ,
+.BR getgroups (),
.I size
is less than the number of supplementary group IDs, but is not zero.
.TP
.B EPERM
The calling process has insufficient privilege to call
-.BR setgroups .
+.BR setgroups ().
.SH NOTES
A process can have up to at least NGROUPS_MAX supplementary group IDs
in addition to the effective group ID. The set of supplementary group IDs
is inherited from the parent process and may be changed using
-.BR setgroups .
+.BR setgroups ().
The maximum number of supplementary group IDs can be found using
.BR sysconf (3):
.nf
ngroups_max = sysconf(_SC_NGROUPS_MAX);
.fi
The maximal return value of
-.B getgroups
+.BR getgroups ()
cannot be larger than one more than the value obtained this way.
.LP
The prototype for
-.B setgroups
+.BR setgroups ()
is only available if
.B _BSD_SOURCE
is defined (either explicitly, or implicitly, by not defining
.SH "CONFORMING TO"
SVr4, SVID (issue 4 only; these calls were not present in SVr3),
X/OPEN, 4.3BSD. The
-.B getgroups
+.BR getgroups ()
function is in POSIX.1. Since
-.B setgroups
+.BR setgroups ()
requires privilege, it is not covered by POSIX.1.
.SH "SEE ALSO"
.BR getgid (2),
and thus usually never needs to be set.
The
-.B sethostid
+.BR sethostid ()
call is restricted to the superuser.
The
argument is stored in the file
.IR /etc/hostid .
.SH "RETURN VALUE"
-.B gethostid
+.BR gethostid ()
returns the 32-bit identifier for the current host as set by
.BR sethostid (2).
.SH "CONFORMING TO"
4.2BSD. These functions were dropped in 4.4BSD.
POSIX.1 does not define these functions, but ISO/IEC 9945-1:1990 mentions
them in B.4.4.1. SVr4 includes
-.B gethostid
+.BR gethostid ()
but not
-.BR sethostid .
+.BR sethostid ().
.SH FILES
.I /etc/hostid
.SH "SEE ALSO"
.B EINVAL
.I len
is negative or, for
-.BR sethostname ,
+.BR sethostname (),
.I len
is larger than the maximum allowed size,
or, for
-.BR gethostname
+.BR gethostname ()
on Linux/i386,
.I len
is smaller than the actual size.
.TP
.B EPERM
For
-.BR sethostname ,
+.BR sethostname (),
the caller did not have the
.B CAP_SYS_ADMIN
capability.
.SH "CONFORMING TO"
SVr4, 4.4BSD (this function first appeared in 4.2BSD).
POSIX 1003.1-2001 specifies
-.B gethostname
+.BR gethostname ()
but not
-.BR sethostname .
+.BR sethostname ().
.SH BUGS
For many Linux kernel / libc combinations
-.B gethostname
+.BR gethostname ()
will return an error instead of returning a truncated hostname.
.SH NOTES
SUSv2 guarantees that `Host names are limited to 255 bytes'.
is a file, not a socket.
.SH "CONFORMING TO"
SVr4, 4.4BSD (the
-.B getpeername
+.BR getpeername ()
function call first appeared in 4.2BSD).
.SH NOTE
The third argument of
-.B getpeername
+.BR getpeername ()
is in reality an `int *' (and this is what 4.x BSD and libc4 and libc5 have).
Some POSIX confusion resulted in the present socklen_t, also used by glibc.
See also
.br
.B pid_t getppid(void);
.SH DESCRIPTION
-.B getpid
+.BR getpid ()
returns the process ID of the current process. (This is often used by
routines that generate unique temporary file names.)
-.B getppid
+.BR getppid ()
returns the process ID of the parent of the current process.
.SH "CONFORMING TO"
POSIX, 4.3BSD, SVID
and
.I who
is obtained with the
-.B getpriority
+.BR getpriority ()
call and set with the
-.B setpriority
+.BR setpriority ()
call.
The value
lower priorities cause more favorable scheduling.
The
-.B getpriority
+.BR getpriority ()
call returns the highest priority (lowest numerical value)
enjoyed by any of the specified processes. The
-.B setpriority
+.BR setpriority ()
call sets the priorities of all of the specified processes
to the specified value. Only the superuser may lower priorities.
.SH "RETURN VALUE"
Since
-.B getpriority
+.BR getpriority ()
can legitimately return the value \-1, it is necessary
to clear the external variable
.I errno
call, then check it afterwards to determine
if a \-1 is an error or a legitimate value.
The
-.B setpriority
+.BR setpriority ()
call returns 0 if there is no error, or
\-1 if there is.
.SH ERRORS
values specified.
.PP
In addition to the errors indicated above,
-.B setpriority
+.BR setpriority ()
may fail if:
.TP
.B EPERM
using the corresponding range 40..1
(since negative numbers are error codes) and these are the values
employed by the
-.B setpriority
+.BR setpriority ()
and
-.B getpriority
+.BR getpriority ()
system calls.
The glibc wrapper functions for these system calls handle the
translations between the user-land and kernel representations
.br
.BI "int getresgid(gid_t *" rgid ", gid_t *" egid ", gid_t *" sgid );
.SH DESCRIPTION
-.B getresuid
+.BR getresuid ()
and
-.B getresgid
+.BR getresgid ()
(both introduced in Linux 2.1.44)
get the real UID, effective UID, and saved set-user-ID (resp. group ID's)
of the current process.
is a file, not a socket.
.SH "CONFORMING TO"
SVr4, 4.4BSD (the
-.B getsockname
+.BR getsockname ()
function call appeared in 4.2BSD). SVr4 documents additional ENOMEM
and ENOSR error codes.
.SH NOTE
The third argument of
-.B getsockname
+.BR getsockname ()
is in reality an `int *' (and this is what 4.x BSD and libc4 and libc5 have).
Some POSIX confusion resulted in the present socklen_t, also used by glibc.
See also
.SH DESCRIPTION
.B Getsockopt
and
-.B setsockopt
+.BR setsockopt ()
manipulate the
.I options
associated with a socket. Options may exist at multiple
and
.I optlen
are used to access option values for
-.BR setsockopt .
+.BR setsockopt ().
For
-.B getsockopt
+.BR getsockopt ()
they identify a buffer in which the value for the
requested option(s) are to be returned. For
-.BR getsockopt ,
+.BR getsockopt (),
.I optlen
is a value-result parameter, initially containing the
size of the buffer pointed to by
parameter for
.IR optval .
For
-.BR setsockopt ,
+.BR setsockopt (),
the parameter should be non-zero to enable a boolean option, or zero if the
option is to be disabled.
The address pointed to by
.I optval
is not in a valid part of the process address space. For
-.BR getsockopt ,
+.BR getsockopt (),
this error may also be returned if
.I optlen
is not in a valid part of the process address space.
.sp
.B pid_t gettid(void);
.SH DESCRIPTION
-\fBgettid\fP returns the thread ID of the current process. This is equal
+\fBgettid\fP() returns the thread ID of the current process. This is equal
to the process ID (as returned by
.BR getpid (2)),
unless the process is part of a thread group (created by specifying
.SH ERRORS
This call is always successful.
.SH "CONFORMING TO"
-\fBgettid\fP is Linux specific and should not be used in programs that
+\fBgettid\fP() is Linux specific and should not be used in programs that
are intended to be portable.
.SH "SEE ALSO"
.BR clone (2),
.BI ", const struct timezone *" tz );
.SH DESCRIPTION
The functions
-.B gettimeofday
+.BR gettimeofday ()
and
-.B settimeofday
+.BR settimeofday ()
can get and set the time as well as a timezone.
The
.I tv
this period is determined by unpredictable political
decisions. So this method of representing time zones
has been abandoned. Under Linux, in a call to
-.B settimeofday
+.BR settimeofday ()
the
.I tz_dsttime
field should be zero.
.PP
Under Linux there is some peculiar `warp clock' semantics associated
to the
-.B settimeofday
+.BR settimeofday ()
system call if on the very first call (after booting)
that has a non-NULL
.I tz
is null, the corresponding structure is not set or returned.
.PP
Only the superuser may use
-.BR settimeofday .
+.BR settimeofday ().
.SH "RETURN VALUE"
-.B gettimeofday
+.BR gettimeofday ()
and
-.B settimeofday
+.BR settimeofday ()
return 0 for success, or \-1 for failure (in which case
.I errno
is set appropriately).
.TP
.B EPERM
The calling process has insufficient privilege to call
-.BR settimeofday ;
+.BR settimeofday ();
under Linux the
.B CAP_SYS_TIME
capability is required.
.SH NOTE
The prototype for
-.B settimeofday
+.BR settimeofday ()
and the defines for
.BR timercmp ,
.BR timerisset ,
.br
.B uid_t geteuid(void);
.SH DESCRIPTION
-.B getuid
+.BR getuid ()
returns the real user ID of the current process.
-.B geteuid
+.BR geteuid ()
returns the effective user ID of the current process.
.SH ERRORS
These functions are always successful.
A complete overview of extended attributes concepts can be found in
.BR attr (5).
.PP
-.B getxattr
+.BR getxattr ()
retrieves the
.I value
of the extended attribute identified by
.I value
is returned.
.PP
-.B lgetxattr
+.BR lgetxattr ()
is identical to
-.BR getxattr ,
+.BR getxattr (),
except in the case of a symbolic link, where the link itself is
interrogated, not the file that it refers to.
.PP
-.B fgetxattr
+.BR fgetxattr ()
is identical to
-.BR getxattr ,
+.BR getxattr (),
only the open file pointed to by
.I filedes
(as returned by
.sp
.B int idle(void);
.SH DESCRIPTION
-.B idle
+.BR idle ()
is an internal system call used during bootstrap.
It marks the process's pages as swappable, lowers its priority,
and enters the main scheduling loop.
-.B idle
+.BR idle ()
never returns.
.PP
Only process 0 may call
-.BR idle .
+.BR idle ().
Any user process, even a process with superuser permission,
will receive
.BR EPERM .
.SH "RETURN VALUE"
-.B idle
+.BR idle ()
never returns for process 0, and always returns \-1 for a user process.
.SH ERRORS
.TP
.SH "DESCRIPTION"
.PP
-\fBio_cancel\fR attempts to cancel an asynchronous I/O operation
+\fBio_cancel\fR() attempts to cancel an asynchronous I/O operation
previously submitted with the \fBio_submit\fR system call.
\fIctx_id\fR is the AIO context ID of the operation to be cancelled.
If the AIO context is found, the event will be cancelled and then copied
.SH "RETURN VALUE"
.PP
-\fBio_cancel\fR returns 0 on success; otherwise, it returns one of the
+\fBio_cancel\fR() returns 0 on success; otherwise, it returns one of the
errors listed in the "Errors" section.
.SH "ERRORS"
.TP
ENOSYS
-\fBio_cancel\fR is not implemented on this architecture.
+\fBio_cancel\fR() is not implemented on this architecture.
.SH "VERSIONS"
.SH "CONFORMING TO"
.PP
-\fBio_cancel\fR is Linux specific and should not be used in programs that are intended to be portable.
+\fBio_cancel\fR() is Linux specific and should not be used in programs that are intended to be portable.
.SH "SEE ALSO"
.SH "DESCRIPTION"
.PP
-\fBio_destroy\fR removes the asynchronous I/O context from the list of
+\fBio_destroy\fR() removes the asynchronous I/O context from the list of
I/O contexts and then destroys it.
-\fBio_destroy\fR can also cancel any outstanding asynchronous I/O
+\fBio_destroy\fR() can also cancel any outstanding asynchronous I/O
actions on \fIctx\fR and block on completion.
.SH "RETURN VALUE"
.PP
-\fBio_destroy\fR returns 0 on success.
+\fBio_destroy\fR() returns 0 on success.
.SH "ERRORS"
.TP
ENOSYS
-\fBio_destroy\fR is not implemented on this architecture.
+\fBio_destroy\fR() is not implemented on this architecture.
.SH "CONFORMING TO"
.PP
-\fBio_destroy\fR is Linux specific and should not be used in programs
+\fBio_destroy\fR() is Linux specific and should not be used in programs
that are intended to be portable.
.SH "VERSIONS"
.SH "DESCRIPTION"
.PP
-\fBio_getevents\fR attempts to read at least \fImin_nr\fR events and
+\fBio_getevents\fR() attempts to read at least \fImin_nr\fR events and
up to \fInr\fR events from the completion queue of the AIO context
specified by \fIctx_id\fR.
\fItimeout\fR specifies the amount of time to wait for events,
.SH "RETURN VALUE"
.PP
-\fBio_getevents\fR returns the number of events read: 0 if no events are
+\fBio_getevents\fR() returns the number of events read: 0 if no events are
available or < \fImin_nr\fR if the \fItimeout\fR has elapsed.
.SH "ERRORS"
.TP
ENOSYS
-\fBio_getevents\fR is not implemented on this architecture.
+\fBio_getevents\fR() is not implemented on this architecture.
.SH "CONFORMING TO"
.PP
-\fBio_getevents\fR is Linux specific and should not be used in programs that are intended to be portable.
+\fBio_getevents\fR() is Linux specific and should not be used in programs that are intended to be portable.
.SH "VERSIONS"
.SH "DESCRIPTION"
.PP
-\fBio_setup\fR creates an asynchronous I/O context capable of receiving
+\fBio_setup\fR() creates an asynchronous I/O context capable of receiving
at least \fInr_events\fR.
\fIctxp\fR must not point to an AIO context that already exists, and must
be initialized to 0 prior to the call.
.SH "RETURN VALUE"
.PP
-\fBio_setup\fR returns 0 on success; otherwise, one of the errors
+\fBio_setup\fR() returns 0 on success; otherwise, one of the errors
listed in the "Errors" section is returned.
.SH "ERRORS"
.TP
ENOSYS
-\fBio_setup\fR is not implemented on this architecture.
+\fBio_setup\fR() is not implemented on this architecture.
.SH "CONFORMING TO"
.PP
-\fBio_setup\fR is Linux specific and should not be used in programs
+\fBio_setup\fR() is Linux specific and should not be used in programs
that are intended to be portable.
.SH "VERSIONS"
.SH "DESCRIPTION"
.PP
-\fBio_submit\fR queues \fInr\fR I/O request blocks for processing in
+\fBio_submit\fR() queues \fInr\fR I/O request blocks for processing in
the AIO context \fIctx_id\fR. \fIiocbpp\fR should be an array of
\fInr\fR AIO request blocks, which will be submitted to context \fIctx_id\fR.
.SH "RETURN VALUE"
.PP
-\fBio_submit\fR returns the number of \fIiocb\fRs submitted and
+\fBio_submit\fR() returns the number of \fIiocb\fRs submitted and
0 if \fInr\fR is zero.
.SH "ERRORS"
.TP
ENOSYS
-\fBio_submit\fR is not implemented on this architecture.
+\fBio_submit\fR() is not implemented on this architecture.
.SH "CONFORMING TO"
.PP
-\fBio_submit\fR is Linux specific and should not be used in programs that are intended to be portable.
+\fBio_submit\fR() is Linux specific and should not be used in programs that are intended to be portable.
.SH "VERSIONS"
.BI "int ioctl(int " d ", int " request ", ...);"
.SH DESCRIPTION
The
-.B ioctl
+.BR ioctl ()
function manipulates the underlying device parameters of special files. In
particular, many operating characteristics of character special files
(e.g. terminals) may be controlled with
-.B ioctl
+.BR ioctl ()
requests. The argument
.I d
must be an open file descriptor.
model). See
.BR ioctl_list (2)
for a list of many of the known
-.B ioctl
+.BR ioctl ()
calls. The
-.B ioctl
+.BR ioctl ()
function call appeared in Version 7 AT&T Unix.
.SH "SEE ALSO"
.BR execve (2),
.SH DESCRIPTION
\fBIoperm\fP sets the port access permission bits for the process for
\fInum\fP bytes starting from port address \fBfrom\fP to the value
-\fBturn_on\fP. The use of \fBioperm\fP requires root privileges.
+\fBturn_on\fP. The use of \fBioperm\fP() requires root privileges.
Only the first 0x3ff I/O ports can be specified in this manner. For more
ports, the
.TP
.B EPERM
The calling process has insufficient privilege to call
-.BR ioperm ;
+.BR ioperm ();
the
.B CAP_SYS_RAWIO
capability is required.
.SH "CONFORMING TO"
-\fBioperm\fP is Linux specific and should not be used in programs
+\fBioperm\fP() is Linux specific and should not be used in programs
intended to be portable.
.SH NOTES
Libc5 treats it as a system call and has a prototype in
.sp
.BI "int iopl(int " level );
.SH DESCRIPTION
-.B iopl
+.BR iopl ()
changes the I/O privilege level of the current process, as specified in
.IR level .
.TP
.B EPERM
The calling process has insufficient privilege to call
-.BR iopl ;
+.BR iopl ();
the
.B CAP_SYS_RAWIO
capability is required.
.SH "CONFORMING TO"
-\fBiopl\fP is Linux specific and should not be used in processes
+\fBiopl\fP() is Linux specific and should not be used in processes
intended to be portable.
.SH NOTES
Libc5 treats it as a system call and has a prototype in
.fi
.SH DESCRIPTION
The
-.B kill
+.BR kill ()
system call
can be used to send any signal to any process group or process.
.PP
If
.I pgrp
is 0,
-.B killpg
+.BR killpg ()
sends the signal to the sending process's process group.
(POSIX says: If
for all target processes.
.SH "CONFORMING TO"
SVr4, 4.4BSD (The
-.B killpg
+.BR killpg ()
function call first appeared in 4.0BSD).
.SH "SEE ALSO"
.BR getpgrp (2),
.sp
.BI "int link(const char *" oldpath ", const char *" newpath );
.SH DESCRIPTION
-.B link
+.BR link ()
creates a new link (also known as a hard link) to an existing file.
If
even if the same filesystem is mounted on both.)
.SH NOTES
Hard links, as created by
-.BR link ,
+.BR link (),
cannot span filesystems. Use
.B symlink
if this is required.
POSIX.1-2001 says that
-.BR link
+.BR link ()
should dereference
.I oldpath
if it is a symbolic link.
A complete overview of extended attributes concepts can be found in
.BR attr (5).
.PP
-.B listxattr
+.BR listxattr ()
retrieves the
.I list
of extended attribute names associated with the given
.I list
is returned.
.PP
-.B llistxattr
+.BR llistxattr ()
is identical to
-.BR listxattr ,
+.BR listxattr (),
except in the case of a symbolic link, where the list of names of
extended attributes associated with the link itself is retrieved,
not the file that it refers to.
.PP
-.B flistxattr
+.BR flistxattr ()
is identical to
-.BR listxattr ,
+.BR listxattr (),
only the open file pointed to by
.I filedes
(as returned by
.BI "unsigned long " offset_low ", loff_t *" result ", unsigned int " whence );
.SH DESCRIPTION
The
-.B _llseek
+.BR _llseek ()
function repositions the offset of the open file associated
with the file descriptor
.I fd
.SH "RETURN VALUE"
Upon successful completion,
-.B _llseek
+.BR _llseek ()
returns 0. Otherwise, a value of \-1 is returned and
.I errno
is set to indicate the error.
entry.
For
-.B lookup_dcookie
+.BR lookup_dcookie ()
to return successfully,
the kernel must still hold a cookie reference to the directory entry.
.SH "NOTES"
-.B lookup_dcookie
+.BR lookup_dcookie ()
is a special-purpose system call, currently used only by the oprofile profiler.
It relies on a kernel driver to register cookies for directory entries.
.SH "RETURN VALUE"
On success,
-.B lookup_dcookie
+.BR lookup_dcookie ()
returns the length of the path string copied into the buffer.
On error, \-1 is returned, and
.I errno
.B ERANGE
The buffer was not large enough to hold the path of the directory entry.
.SH "CONFORMING TO"
-.B lookup_dcookie
+.BR lookup_dcookie ()
is Linux-specific.
.SH AVAILABILITY
Since Linux 2.5.43.
.BI "off_t lseek(int " fildes ", off_t " offset ", int " whence );
.SH DESCRIPTION
The
-.B lseek
+.BR lseek ()
function repositions the offset of the open file associated with the
file descriptor
.I fildes
bytes.
.PP
The
-.B lseek
+.BR lseek ()
function allows the file offset to be set beyond the end of the existing
end-of-file of the file (but this does not change the size of the file).
If data is later written at this point, subsequent reads of the data
the gap).
.SH "RETURN VALUE"
Upon successful completion,
-.B lseek
+.BR lseek ()
returns the resulting offset location as measured in bytes from the
beginning of the file. Otherwise, a value of (off_t)\-1 is returned and
.I errno
Some devices are incapable of seeking and POSIX does not specify which
devices must support it.
-Linux specific restrictions: using \fBlseek\fP on a tty device returns
+Linux specific restrictions: using \fBlseek\fP() on a tty device returns
\fBESPIPE\fP.
.\" Other systems return the number of written characters,
.\" using SEEK_SET to set the counter. (Of written characters.)
.BI "int madvise(void *" start ", size_t " length ", int " advice );
.SH DESCRIPTION
The
-.B madvise
+.BR madvise ()
system call advises the kernel about how to handle paging input/output in
the address range beginning at address
.I start
without an underlying file.
.SH "RETURN VALUE"
On success
-.B madvise
+.BR madvise ()
returns zero. On error, it returns \-1 and
.I errno
is set appropriately.
.I length
to be zero. If there are some parts of the specified address range
that are not mapped, the Linux version of
-.B madvise
+.BR madvise ()
ignores them and applies the call to the rest (but returns
.B ENOMEM
from the system call, as it should).
.SH HISTORY
The
-.B madvise
+.BR madvise ()
function first appeared in 4.4BSD.
.SH "CONFORMING TO"
POSIX.1b (POSIX.4).
.BI "int mincore(void *" start ", size_t " length ", unsigned char *" vec );
.SH DESCRIPTION
The
-.B mincore
+.BR mincore ()
function requests a vector describing which pages of a file are in core and
can be read without disk access. The kernel will supply data for
.I length
may be stale already when this call returns.
For
-.B mincore
+.BR mincore ()
to return successfully,
.I start
must lie on a page boundary. It is the caller's responsibility to
.SH "RETURN VALUE"
On success,
-.B mincore
+.BR mincore ()
returns zero.
On error, \-1 is returned, and
.I errno
contained unmapped memory, or memory not part of a file.
.SH BUGS
Up to now (Linux 2.6.5),
-.B mincore
+.BR mincore ()
does not return correct information for MAP_PRIVATE mappings.
.\" Linux (up to now, 2.6.5),
.\" always fails with the error
.\" .BR ENOMEM .
.SH "CONFORMING TO"
-.B mincore
+.BR mincore ()
is not specified in POSIX.1-2001,
and it is not available on all Unix implementations.
.SH HISTORY
.BI "int mkdir(const char *" pathname ", mode_t " mode );
.fi
.SH DESCRIPTION
-.B mkdir
+.BR mkdir ()
attempts to create a directory named
.IR pathname .
newly created directory.
.SH "RETURN VALUE"
-.BR mkdir
+.BR mkdir ()
returns zero on success, or \-1 if an error occurred (in which case,
.I errno
is set appropriately).
.PP
There are many infelicities in the protocol underlying NFS. Some
of these affect
-.BR mkdir .
+.BR mkdir ().
.SH "SEE ALSO"
.BR mkdir (1),
.BR chmod (2),
.fi
.SH DESCRIPTION
The system call
-.B mknod
+.BR mknod ()
creates a filesystem node (file, device special file or
named pipe) named
.IR pathname ,
new node will inherit the group ownership from its parent directory;
otherwise it will be owned by the effective group ID of the process.
.SH "RETURN VALUE"
-.BR mknod
+.BR mknod ()
returns zero on success, or \-1 if an error occurred (in which case,
.I errno
is set appropriately).
There are many infelicities in the protocol underlying NFS. Some
of these affect
-.BR mknod .
+.BR mknod ().
.SH "SEE ALSO"
.BR fcntl (2),
.BR mkdir (2),
will be unlocked by a single call to
.BR munlock ()
for the corresponding range or by
-.BR munlockall .
+.BR munlockall ().
Pages which are mapped to several locations or by several processes stay
locked into RAM as long as they are locked at least at one location or by
at least one process.
.B EPERM
(Linux 2.6.8 and earlier)
The calling process has insufficient privilege to call
-.BR munlockall .
+.BR munlockall ().
Under Linux the
.B CAP_IPC_LOCK
capability is required.
.BI "int " flags ", int " fd ", off_t " pgoffset );
.SH DESCRIPTION
The function
-.B mmap2
+.BR mmap2 ()
operates in exactly the same way as
.BR mmap (2),
except that the final argument specifies the offset into the
larger files (typically up to 2^44 bytes).
.SH "RETURN VALUE"
On success,
-.B mmap2
+.BR mmap2 ()
returns a pointer to the mapped area. On error \-1 is returned
and
.I errno
data from userspace.
.SH NOTES
The function
-.B mmap2
+.BR mmap2 ()
is available since Linux 2.3.31.
It is Linux specific, and should be avoided in portable applications.
See also the
.sp
.BI "int modify_ldt(int " "func" ", void *" "ptr" ", unsigned long " "bytecount" );
.SH DESCRIPTION
-.B modify_ldt
+.BR modify_ldt ()
reads or writes the local descriptor table (ldt) for a process.
The ldt is a per-process memory management table used by the i386 processor.
For more information on this table, see an Intel 386 processor handbook.
When
.I func
is 0,
-.B modify_ldt
+.BR modify_ldt ()
reads the ldt into the memory pointed to by
.IR ptr .
The number of bytes read is the smaller of
When
.I func
is 1,
-.B modify_ldt
+.BR modify_ldt ()
modifies one ldt entry.
.I ptr
points to a
.\" at the paging layer.
.SH "RETURN VALUE"
On success,
-.B modify_ldt
+.BR modify_ldt ()
returns either the actual number of bytes read (for reading)
or 0 (for writing).
On failure,
-.B modify_ldt
+.BR modify_ldt ()
returns \-1 and sets
.IR errno .
.SH ERRORS
.sp
.BI "int umount2(const char *" target ", int " flags );
.SH DESCRIPTION
-.B mount
+.BR mount ()
attaches the filesystem specified by
.I source
(which is often a device name, but can also be a directory name
programs intended to be portable.
.SH HISTORY
The original
-.B umount
+.BR umount ()
function was called as \fIumount(device)\fP and would return ENOTBLK
when called with something other than a block device.
In Linux 0.98p4 a call \fIumount(dir)\fP was added, in order to
.fi
.SH DESCRIPTION
The function
-.B mprotect
+.BR mprotect ()
specifies the desired protection for the memory page(s) containing
part or all of the interval [\fIaddr\fP,\fIaddr\fP+\fIlen\fP-1].
If an access is disallowed by the protection given it, the program receives a
The memory can contain executing code.
.PP
The new protection replaces any existing protection. For example, if the
-memory had previously been marked \fBPROT_READ\fR, and \fBmprotect\fR
+memory had previously been marked \fBPROT_READ\fR, and \fBmprotect\fR()
is then called with \fIprot\fR \fBPROT_WRITE\fR, it will no longer
be readable.
.SH "RETURN VALUE"
On success,
-.B mprotect
+.BR mprotect ()
returns zero. On error, \-1 is returned, and
.I errno
is set appropriately.
for example, if you
.BR mmap (2)
a file to which you have read-only access, then ask
-.B mprotect
+.BR mprotect ()
to mark it
.BR PROT_WRITE .
.TP
SVr4, POSIX.1b (formerly POSIX.4). SVr4 defines an additional error
code EAGAIN. The SVr4 error conditions don't map neatly onto Linux's.
POSIX says that
-.B mprotect
+.BR mprotect ()
can be used only on regions of memory obtained from
.BR mmap (2).
.SH NOTES
On Linux it is always legal to call
-.B mprotect
+.BR mprotect ()
on any address in a process' address space (except for the
kernel vsyscall area). In particular it can be used
to change existing code mappings to be writable.
.sp
.BI "int msync(void *" start ", size_t " length ", int " flags );
.SH DESCRIPTION
-.B msync
+.BR msync ()
flushes changes made to the in-core copy of a file that was mapped
into memory using
.BR mmap (2)
The indicated memory (or part of it) was not mapped.
.SH AVAILABILITY
On POSIX systems on which
-.B msync
+.BR msync ()
is available, both
.B _POSIX_MAPPED_FILES
and
\fBint nanosleep(const struct timespec *\fIreq\fB, struct timespec *\fIrem\fB);
.fi
.SH DESCRIPTION
-.B nanosleep
+.BR nanosleep ()
delays the execution of the program for at least the time specified in
.IR *req .
The function can return earlier if a signal has been delivered to the
The value of
.I *rem
can then be used to call
-.B nanosleep
+.BR nanosleep ()
again and complete the specified pause.
The structure
.BR sleep (3)
and
.BR usleep (3),
-.B nanosleep
+.BR nanosleep ()
has the advantage of not affecting any signals, it is standardized by
POSIX, it provides higher timing resolution, and it allows to continue
a sleep that has been interrupted by a signal more easily.
.SH ERRORS
In case of an error or exception, the
-.B nanosleep
+.BR nanosleep ()
system call returns \-1 instead of 0 and sets
.I errno
to one of the following values:
The pause has been interrupted by a non-blocked signal that was
delivered to the process. The remaining sleep time has been written
into *\fIrem\fR so that the process can easily call
-.B nanosleep
+.BR nanosleep ()
again and continue with the pause.
.TP
.B EINVAL
was negative.
.SH BUGS
The current implementation of
-.B nanosleep
+.BR nanosleep ()
is based on the normal kernel timer mechanism, which has a resolution
of 1/\fIHZ\fR\ s (i.e, 10\ ms on Linux/i386 and 1\ ms on Linux/Alpha).
Therefore,
-.B nanosleep
+.BR nanosleep ()
pauses always for at least the specified time, however it can take up
to 10 ms longer than specified until the process becomes runnable
again. For the same reason, the value returned in case of a delivered
.SS "Old behaviour"
In order to support applications requiring much more precise pauses
(e.g., in order to control some time-critical hardware),
-.B nanosleep
+.BR nanosleep ()
would handle pauses of up to 2\ ms by busy waiting with microsecond
precision when called from a process scheduled under a real-time policy
like
to receive a segmentation fault.
.SH "CONFORMING TO"
-\fBoutb\fP and friends are hardware specific. The
+\fBoutb\fP() and friends are hardware specific. The
.I value
argument is passed first and the
.I port
.B int pause(void);
.SH DESCRIPTION
The
-.B pause
+.BR pause ()
library function causes the invoking process (or thread) to sleep
until a signal is received that either terminates it or causes it
to call a signal-catching function.
.TP
Most of the interaction with PCI devices is already handled by the kernel PCI layer, and thus these calls should not normally need to be accessed from userspace.
.TP
-.BR pciconfig_read
+.BR pciconfig_read ()
Reads to
.I
buf
off
value.
.TP
-.BR pciconfig_write
+.BR pciconfig_write ()
Writes from
.I
buf
off
value.
.TP
-.BR pciconfig_iobase
+.BR pciconfig_iobase ()
You pass it a bus/devfn pair and get a physical address for either the memory offset (for things like prep, this is 0xc0000000), the IO base for PIO cycles, or the ISA holes if any.
.SH "RETURN VALUE"
.TP
-.BR pciconfig_read
+.BR pciconfig_read ()
On success zero is returned. On error, \-1 is returned and errno is set appropriately.
.TP
-.BR pciconfig_write
+.BR pciconfig_write ()
On success zero is returned. On error, \-1 is returned and errno is set appropriately.
.TP
-.BR pciconfig_iobase
+.BR pciconfig_iobase ()
Returns information on locations of various I/O regions in physical memory according to the
.I which
value. Values for
Unix-like operating systems.
This function will return the current
-.B personality
+.BR personality ()
when
.I persona
equals 0xffffffff. Otherwise, it will make the execution domain
.B EINVAL
The kernel was unable to change the personality.
.SH "CONFORMING TO"
-.B personality
+.BR personality ()
is Linux-specific and should not be used in programs intended to be portable.
.sp
.BI "int pipe(int " filedes "[2]);"
.SH DESCRIPTION
-.B pipe
+.BR pipe ()
creates a pair of file descriptors, pointing to a pipe inode, and places
them in the array pointed to by
.IR filedes .
.sp
.BI "int pivot_root(const char *" new_root ", const char *" put_old );
.SH DESCRIPTION
-\fBpivot_root\fP moves the root file system of the current process to the
+\fBpivot_root\fP() moves the root file system of the current process to the
directory \fIput_old\fP and makes \fInew_root\fP the new root file system
of the current process.
.\"
.\" .B CAP_SYS_ADMIN
.\" capability is required.
-The typical use of \fBpivot_root\fP is during system startup, when the
+The typical use of \fBpivot_root\fP() is during system startup, when the
system mounts a temporary root file system (e.g. an \fBinitrd\fP), then
mounts the real root file system, and eventually turns the latter into
the current root of all relevant processes or threads.
-\fBpivot_root\fP may or may not change the current root and the current
+\fBpivot_root\fP() may or may not change the current root and the current
working directory (cwd) of any processes or threads which use the old
-root directory. The caller of \fBpivot_root\fP
+root directory. The caller of \fBpivot_root\fP()
must ensure that processes with root or cwd at the old root operate
correctly in either case. An easy way to ensure this is to change their
-root and cwd to \fInew_root\fP before invoking \fBpivot_root\fP.
+root and cwd to \fInew_root\fP before invoking \fBpivot_root\fP().
The paragraph above is intentionally vague because the implementation
-of \fBpivot_root\fP may change in the future. At the time of writing,
-\fBpivot_root\fP changes root and cwd of each process or
+of \fBpivot_root\fP() may change in the future. At the time of writing,
+\fBpivot_root\fP() changes root and cwd of each process or
thread to \fInew_root\fP if they point to the old root directory. This
is necessary in order to prevent kernel threads from keeping the old
root directory busy with their root and cwd, even if they never access
the file system in any way. In the future, there may be a mechanism for
kernel threads to explicitly relinquish any access to the file system,
such that this fairly intrusive mechanism can be removed from
-\fBpivot_root\fP.
+\fBpivot_root\fP().
-Note that this also applies to the current process: \fBpivot_root\fP may
+Note that this also applies to the current process: \fBpivot_root\fP() may
or may not affect its cwd. It is therefore recommended to call
-\fBchdir("/")\fP immediately after \fBpivot_root\fP.
+\fBchdir("/")\fP immediately after \fBpivot_root\fP().
The following restrictions apply to \fInew_root\fP and \fIput_old\fP:
.IP \- 3
See also \fBpivot_root(8)\fP for additional usage examples.
If the current root is not a mount point (e.g. after \fBchroot(2)\fP or
-\fBpivot_root\fP, see also below), not the old root directory, but the
+\fBpivot_root\fP(), see also below), not the old root directory, but the
mount point of that file system is mounted on \fIput_old\fP.
.SH NOTES
\fInew_root\fP does not have to be a mount point. In this case,
On success, zero is returned. On error, \-1 is returned, and
\fIerrno\fP is set appropriately.
.SH ERRORS
-\fBpivot_root\fP may return (in \fIerrno\fP) any of the errors returned by
+\fBpivot_root\fP() may return (in \fIerrno\fP) any of the errors returned by
\fBstat(2)\fP. Additionally, it may return:
.TP
.B CAP_SYS_ADMIN
capability.
.SH BUGS
-\fBpivot_root\fP should not have to change root and cwd of all other
+\fBpivot_root\fP() should not have to change root and cwd of all other
processes in the system.
-Some of the more obscure uses of \fBpivot_root\fP may quickly lead to
+Some of the more obscure uses of \fBpivot_root\fP() may quickly lead to
insanity.
.SH "CONFORMING TO"
-\fBpivot_root\fP is Linux-specific and hence is not portable.
+\fBpivot_root\fP() is Linux-specific and hence is not portable.
.SH HISTORY
-\fBpivot_root\fP was introduced in Linux 2.3.41.
+\fBpivot_root\fP() was introduced in Linux 2.3.41.
.SH "SEE ALSO"
.BR chdir (2),
.BR chroot (2),
.BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " len ", int " advice ");"
.fi
.SH DESCRIPTION
-Programs can use \fBposix_fadvise\fP to announce an intention to access
+Programs can use \fBposix_fadvise\fP() to announce an intention to access
file data in a specific pattern in the future, thus allowing the kernel
to perform appropriate optimisations.
The specified file descriptor refers to a pipe or FIFO. (Linux actually
returns EINVAL in this case.)
.SH NOTES
-.BR posix_fadvise
+.BR posix_fadvise ()
appeared in kernel 2.5.60.
.\" Actually as fadvise64() -- MTK
.BI "int prctl(int " option ", unsigned long " arg2 ", unsigned long " arg3
.BI ", unsigned long " arg4 ", unsigned long " arg5 );
.SH DESCRIPTION
-.B prctl
+.BR prctl ()
is called with a first argument describing what to do
(with values defined in <\fIlinux/prctl.h\fP>), and further
parameters with a significance depending on the first one.
must be capable of seeking.
.SH "RETURN VALUE"
On success, the number of bytes read or written is returned (zero
-indicates that nothing was written, in the case of \fBpwrite\fR, or
+indicates that nothing was written, in the case of \fBpwrite\fR(), or
end of file, in the case of \fBpread\fR), or \-1 on error, in which
case
.I errno
is set to indicate the error.
.SH ERRORS
-.B pread
+.BR pread ()
can fail and set
.I errno
to any error specified for \fBread\fR(2) or \fBlseek\fR(2).
-.B pwrite
+.BR pwrite ()
can fail and set
.I errno
to any error specified for \fBwrite\fR(2) or \fBlseek\fR(2).
.SH "CONFORMING TO"
Unix98
.SH HISTORY
-The \fBpread\fR and \fBpwrite\fR system calls were added to Linux in
+The \fBpread\fR() and \fBpwrite\fR() system calls were added to Linux in
version 2.1.60; the entries in the i386 system call table were added
in 2.1.69. The libc support (including emulation on older kernels
without the system calls) was added in glibc 2.1.
.BI "long ptrace(enum __ptrace_request " request ", pid_t " pid ", void *" addr ", void *" data );
.SH DESCRIPTION
The
-.B ptrace
+.BR ptrace ()
system call provides a means by which a parent process may observe and control
the execution of another process, and examine and change its core image and
registers. It is primarily used to implement breakpoint debugging and system
Reads a word at the location
.IR addr
in the child's memory, returning the word as the result of the
-.B ptrace
+.BR ptrace ()
call. Linux does not have separate text and data address spaces, so the two
requests are currently equivalent. (The argument \fIdata\fP is ignored.)
.TP
.B USER
area, which holds the registers and other information about the process (see
<linux/user.h> and <sys/user.h>). The word is returned as the result of the
-.B ptrace
+.BR ptrace ()
call. Typically the offset must be word-aligned, though this might vary by
architecture. (\fIdata\fP is ignored.)
.TP
tracing. (\fIaddr\fP is ignored.)
.SH NOTES
Although arguments to
-.B ptrace
+.BR ptrace ()
are interpreted according to the prototype given, GNU libc currently declares
-.B ptrace
+.BR ptrace ()
as a variadic function with only the \fIrequest\fP argument fixed. This means
that unneeded trailing arguments may be omitted, though doing so makes use of
undocumented
this notification.
.LP
This page documents the way the
-.B ptrace
+.BR ptrace ()
call works currently in Linux. Its behavior differs noticeably on other
flavors of Unix. In any case, use of
-.B ptrace
+.BR ptrace ()
is highly OS- and architecture-specific.
.LP
The SunOS man page describes
-.B ptrace
+.BR ptrace ()
as "unique and arcane", which it is. The proc-based debugging interface
present in Solaris 2 implements a superset of
-.B ptrace
+.BR ptrace ()
functionality in a more powerful and uniform way.
.SH "RETURN VALUE"
On success, PTRACE_PEEK* requests return the requested data, while other requests
at a time: after this week the soft limit counts as hard limit.
The
-.B quotactl
+.BR quotactl ()
system call manipulates these quota. Its first argument is
of the form
.BI QCMD( subcmd , type )
.SH "RETURN VALUE"
On success,
-.B quotactl
+.BR quotactl ()
returns 0. On error, \-1 is returned, and
.I errno
is set appropriately.
Other errors may occur, depending on the object connected to
.IR fd .
POSIX allows a
-.B read
+.BR read ()
that is interrupted after reading some data
to return \-1 (with
.I errno
.B EINVAL
.I fd
does not refer to a file type to which
-.B readahead
+.BR readahead ()
can be applied.
.SH "CONFORMING TO"
The
which can change, and which is superseded by
.BR getdents (2).
.PP
-.B readdir
+.BR readdir ()
reads one
.I dirent
structure from the directory
.sp
.BI "int readlink(const char *" path ", char *" buf ", size_t " bufsiz );
.SH DESCRIPTION
-.B readlink
+.BR readlink ()
places the contents of the symbolic link
.I path
in the buffer
.IR buf ,
which has size
.IR bufsiz .
-.B readlink
+.BR readlink ()
does not append a
.B NUL
character to
A component of the path prefix is not a directory.
.SH "CONFORMING TO"
X/OPEN, 4.4BSD (the
-.B readlink
+.BR readlink ()
function call appeared in 4.2BSD).
.SH "SEE ALSO"
.BR lstat (2),
.BI "int reboot(int " flag );
.SH DESCRIPTION
The
-.B reboot
+.BR reboot ()
call reboots the system, or enables/disables the reboot keystroke
(abbreviated CAD, since the default is Ctrl-Alt-Delete;
it can be changed using
.TP
.B EPERM
The calling process has insufficient privilege to call
-.BR reboot ;
+.BR reboot ();
the
.B CAP_SYS_BOOT
capability is required.
.SH "CONFORMING TO"
-.B reboot
+.BR reboot ()
is Linux specific, and should not be used in programs intended to be portable.
.SH "SEE ALSO"
.BR sync (2),
.BI "ssize_t recvmsg(int " s ", struct msghdr *" msg ", int " flags );
.SH DESCRIPTION
The
-.B recvfrom
+.BR recvfrom ()
and
-.B recvmsg
+.BR recvmsg ()
calls are used to receive messages from a socket, and may be used
to receive data on a socket whether or not it is connection-oriented.
.PP
there.
.PP
The
-.B recv
+.BR recv ()
call is normally used only on a
.I connected
socket (see
.BR connect (2))
and is identical to
-.B recvfrom
+.BR recvfrom ()
with a NULL
.I from
parameter.
on the next socket operation.
.PP
The
-.B recvmsg
+.BR recvmsg ()
call uses a
.I msghdr
structure to minimize the number of directly supplied parameters. This
.IR msg_controllen ,
points to a buffer for other protocol control related messages or
miscellaneous ancillary data. When
-.B recvmsg
+.BR recvmsg ()
is called,
.I msg_controllen
should contain the length of the available buffer in
A complete overview of extended attributes concepts can be found in
.BR attr (5).
.PP
-.B removexattr
+.BR removexattr ()
removes the extended attribute identified by
.I name
and associated with the given
.I path
in the filesystem.
.PP
-.B lremovexattr
+.BR lremovexattr ()
is identical to
-.BR removexattr ,
+.BR removexattr (),
except in the case of a symbolic link, where the extended attribute is
removed from the link itself, not the file that it refers to.
.PP
-.B fremovexattr
+.BR fremovexattr ()
is identical to
-.BR removexattr ,
+.BR removexattr (),
only the extended attribute is removed from the open file pointed to by
.I filedes
(as returned by
.sp
.BI "int rename(const char *" oldpath ", const char *" newpath );
.SH DESCRIPTION
-.B rename
+.BR rename ()
renames a file, moving it between directories if required.
Any other hard links to the file (as created using
If
.I newpath
exists but the operation fails for some reason
-.B rename
+.BR rename ()
guarantees to leave an instance of
.I newpath
in place.
.sp
.BI "int rmdir(const char *" pathname );
.SH DESCRIPTION
-.B rmdir
+.BR rmdir ()
deletes a directory, which must be empty.
.SH "RETURN VALUE"
On success, zero is returned. On error, \-1 is returned, and
\fBint sched_get_priority_min(int \fIpolicy\fB);
.fi
.SH DESCRIPTION
-.B sched_get_priority_max
+.BR sched_get_priority_max ()
returns the maximum priority value that can be used with the
scheduling algorithm identified by \fIpolicy\fR.
-.B sched_get_priority_min
+.BR sched_get_priority_min ()
returns the minimum priority value that can be used with the
scheduling algorithm identified by \fIpolicy\fR. Supported \fIpolicy\fR
values are
Processes with numerically higher priority values are scheduled before
processes with numerically lower priority values. Thus, the value
-returned by \fBsched_get_priority_max\fR will be greater than the
-value returned by \fBsched_get_priority_min\fR.
+returned by \fBsched_get_priority_max\fR() will be greater than the
+value returned by \fBsched_get_priority_min\fR().
Linux allows the static priority value range 1 to 99 for
\fISCHED_FIFO\fR and \fISCHED_RR\fR and the priority 0 for
The range of scheduling priorities may vary on other POSIX systems,
thus it is a good idea for portable applications to use a virtual
priority range and map it to the interval given by
-\fBsched_get_priority_max\fR and \fBsched_get_priority_min\fR.
+\fBsched_get_priority_max\fR() and \fBsched_get_priority_min\fR().
POSIX.1b requires a spread of at least 32 between the maximum and the
minimum values for \fISCHED_FIFO\fR and \fISCHED_RR\fR.
POSIX systems on which
-.B sched_get_priority_max
+.BR sched_get_priority_max ()
and
-.B sched_get_priority_min
+.BR sched_get_priority_min ()
are available define
.I _POSIX_PRIORITY_SCHEDULING
in <unistd.h>.
.SH "RETURN VALUE"
On success,
-.B sched_get_priority_max
+.BR sched_get_priority_max ()
and
-.B sched_get_priority_min
+.BR sched_get_priority_min ()
return the maximum/minimum priority value for the named scheduling
policy.
On error, \-1 is returned,
.ta
.fi
.SH DESCRIPTION
-.B sched_rr_get_interval
+.BR sched_rr_get_interval ()
writes into the \fItimespec\fR structure pointed to by \fItp\fR the
round robin time quantum for the process identified by \fIpid\fR. If
\fIpid\fR is zero, the time quantum for the calling process is written
1.3.81.
POSIX systems on which
-.B sched_rr_get_interval
+.BR sched_rr_get_interval ()
is available define
.I _POSIX_PRIORITY_SCHEDULING
in <unistd.h>.
.SH "RETURN VALUE"
On success,
-.B sched_rr_get_interval
+.BR sched_rr_get_interval ()
returns 0.
On error, \-1 is returned, and
.I errno
.SH "CONFORMING TO"
POSIX.1b (formerly POSIX.4)
.SH BUGS
-As of Linux 1.3.81 \fBsched_rr_get_interval\fR returns with error
+As of Linux 1.3.81 \fBsched_rr_get_interval\fR() returns with error
ENOSYS, because SCHED_RR has not yet been fully implemented and tested
properly.
.SH "SEE ALSO"
.BI "int sched_getaffinity(pid_t " pid ", unsigned int " len ,
.BI "unsigned long *" mask );
.SH DESCRIPTION
-.B sched_setaffinity
+.BR sched_setaffinity ()
sets the CPU affinity mask of the process denoted by
.IR pid .
If
supplied must be at least as large as the affinity mask stored in the kernel.
.sp
The function
-.B sched_getaffinity
+.BR sched_getaffinity ()
writes into the pointer supplied by
.I mask
that has size
.SH "RETURN VALUE"
On success,
-.B sched_setaffinity
+.BR sched_setaffinity ()
returns 0.
On error, \-1 is returned, and
.I errno
is set appropriately.
On success,
-.B sched_getaffinity
+.BR sched_getaffinity ()
always returns the size (in bytes) of the affinity mask used by the kernel.
On error, \-1 is returned, and
.I errno
.B EPERM
The calling process does not have appropriate privileges.
The process calling
-.BR sched_setaffinity
+.BR sched_setaffinity ()
needs an effective user ID equal to the user ID or effective user ID
of the process identified by
.IR pid ,
.ta
.fi
.SH DESCRIPTION
-.B sched_setparam
+.BR sched_setparam ()
sets the scheduling parameters associated with the scheduling policy
for the process identified by \fIpid\fR. If \fIpid\fR is zero, then
the parameters of the current process are set. The interpretation of
and
.IR SCHED_OTHER .
-.B sched_getparam
+.BR sched_getparam ()
retrieves the scheduling parameters for the
process identified by \fIpid\fR. If \fIpid\fR is zero, then the parameters
of the current process are retrieved.
-.B sched_setparam
+.BR sched_setparam ()
checks the validity of \fIp\fR for the scheduling policy of the
process. The parameter \fIp->sched_priority\fR must lie within the
range given by \fBsched_get_priority_min\fR and
.BR sched_setscheduler (2).
POSIX systems on which
-.B sched_setparam
+.BR sched_setparam ()
and
-.B sched_getparam
+.BR sched_getparam ()
are available define
.I _POSIX_PRIORITY_SCHEDULING
in <unistd.h>.
.SH "RETURN VALUE"
On success,
-.BR sched_setparam
+.BR sched_setparam ()
and
-.BR sched_getparam
+.BR sched_getparam ()
return 0.
On error, \-1 is returned,
.I errno
.ta
.fi
.SH DESCRIPTION
-.B sched_setscheduler
+.BR sched_setscheduler ()
sets both the scheduling policy and the associated parameters for the
process identified by \fIpid\fP. If \fIpid\fP equals zero, the
scheduler of the calling process will be set. The interpretation of
.IR SCHED_OTHER ;
their respective semantics are described below.
-.B sched_getscheduler
+.BR sched_getscheduler ()
queries the scheduling policy currently applied to the process
identified by \fIpid\fP. If \fIpid\fP equals zero, the policy of the
calling process will be retrieved.
will resume execution as soon as all processes of higher priority are
blocked again. When a \fISCHED_FIFO\fP process becomes runnable, it
will be inserted at the end of the list for its priority. A call to
-\fBsched_setscheduler\fP or \fBsched_setparam\fP will put the
+\fBsched_setscheduler\fP() or \fBsched_setparam\fP will put the
\fISCHED_FIFO\fP (or \fISCHED_RR\fP) process identified by
\fIpid\fP at the start of the list if it was runnable.
As a consequence, it may preempt the currently running process if
The only change that an unprivileged process can make is to set the
.B SCHED_OTHER
policy, and this can only be done if the effective user ID of the caller of
-.BR sched_setscheduler
+.BR sched_setscheduler ()
matches the real or effective user ID of the target process
(i.e., the process specified by
.IR pid )
real-time applications that do not block or terminate as expected.
POSIX systems on which
-.B sched_setscheduler
+.BR sched_setscheduler ()
and
-.B sched_getscheduler
+.BR sched_getscheduler ()
are available define
.I _POSIX_PRIORITY_SCHEDULING
in <unistd.h>.
.SH "RETURN VALUE"
On success,
-.BR sched_setscheduler
+.BR sched_setscheduler ()
returns zero.
On success,
-.BR sched_getscheduler
+.BR sched_getscheduler ()
returns the policy for the process (a non-negative integer).
On error, \-1 is returned,
.I errno
.fi
.SH DESCRIPTION
A process can relinquish the processor voluntarily without blocking by calling
-.BR sched_yield .
+.BR sched_yield ().
The process will then be moved to the end of the queue for its static
priority and a new process gets to run.
Note: If the current process is the only process in the highest
priority list at that time, this process will continue to run after a
call to
-.BR sched_yield .
+.BR sched_yield ().
POSIX systems on which
-.B sched_yield
+.BR sched_yield ()
is available define
.I _POSIX_PRIORITY_SCHEDULING
in <unistd.h>.
.SH "RETURN VALUE"
On success,
-.B sched_yield
+.BR sched_yield ()
returns 0.
On error, \-1 is returned, and
.I errno
.fi
.SH DESCRIPTION
The functions
-.B select
+.BR select ()
and
-.B pselect
+.BR pselect ()
wait for a number of file descriptors to change status.
.PP
Their function is identical, with three differences:
.TP
(i)
The
-.B select
+.BR select ()
function uses a timeout that is a
.I struct timeval
(with seconds and microseconds), while
-.B pselect
+.BR pselect ()
uses a
.I struct timespec
(with seconds and nanoseconds).
.TP
(ii)
The
-.B select
+.BR select ()
function may update the
.I timeout
parameter to indicate how much time was left. The
-.B pselect
+.BR pselect ()
function does not change this parameter.
.TP
(iii)
The
-.B select
+.BR select ()
function has no
.I sigmask
parameter, and behaves as
-.B pselect
+.BR pselect ()
called with NULL
.IR sigmask .
.PP
to indicate which descriptors actually changed status.
.PP
Four macros are provided to manipulate the sets.
-.B FD_ZERO
+.BR FD_ZERO ()
will clear a set.
-.B FD_SET
+.BR FD_SET ()
and
-.B FD_CLR
+.BR FD_CLR ()
add or remove a given descriptor from a set.
-.B FD_ISSET
+.BR FD_ISSET ()
tests to see if a descriptor is part of the set; this is useful after
-.B select
+.BR select ()
returns.
.PP
.I n
.PP
.I timeout
is an upper bound on the amount of time elapsed before
-.B select
+.BR select ()
returns. It may be zero, causing
-.B select
+.BR select ()
to return immediately. (This is useful for polling.) If
.I timeout
is NULL (no timeout),
-.B select
+.BR select ()
can block indefinitely.
.PP
.I sigmask
is a pointer to a signal mask (see
.BR sigprocmask (2));
if it is not NULL, then
-.B pselect
+.BR pselect ()
first replaces the current signal mask by the one pointed to by
.IR sigmask ,
then does the `select' function, and then restores the original
signal mask again.
.PP
The idea of
-.B pselect
+.BR pselect ()
is that if one wants to wait for an event, either a signal
or something on a file descriptor, an atomic test is needed to prevent
race conditions. (Suppose the signal handler sets a global flag and
.BR select ()
could hang indefinitely if the signal arrived just after the test
but just before the call. On the other hand,
-.B pselect
+.BR pselect ()
allows one to first block signals, handle the signals that have come in,
then call
.BR pselect ()
(However, see below on the POSIX 1003.1-2001 versions.)
.PP
Some code calls
-.B select
+.BR select ()
with all three sets empty,
.I n
zero, and a non-null
as a fairly portable way to sleep with subsecond precision.
.PP
On Linux, the function
-.B select
+.BR select ()
modifies
.I timeout
to reflect the amount of time not slept; most other implementations
.I timeout
is ported to other operating systems, and when code is ported to Linux
that reuses a struct timeval for multiple
-.BR select s
+.BR select ()s
in a loop without reinitializing it. Consider
.I timeout
to be undefined after
-.B select
+.BR select ()
returns.
.\" .PP - it is rumoured that:
.\" On BSD, when a timeout occurs, the file descriptor bits are not changed.
.\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout.
.SH "RETURN VALUE"
On success,
-.B select
+.BR select ()
and
-.B pselect
+.BR pselect ()
return the number of descriptors contained in the three returned
descriptor sets (that is, the total number of one bits in
.IR readfds ,
is invalid.
.TP
.B ENOMEM
-.B select
+.BR select ()
was unable to allocate memory for internal tables.
.SH EXAMPLE
.nf
.fi
.SH "CONFORMING TO"
4.4BSD (the
-.B select
+.BR select ()
function first appeared in 4.2BSD). Generally portable to/from
non-BSD systems supporting clones of the BSD socket layer (including
System V variants). However, note that the System V variant typically
sets the timeout variable before exit, but the BSD variant does not.
.PP
The
-.B pselect
+.BR pselect ()
function is defined in IEEE Std 1003.1g-2000 (POSIX.1g), and part of
POSIX 1003.1-2001.
It is found in glibc2.1 and later.
include
.I <time.h>
for
-.BR select .
+.BR select ().
The POSIX 1003.1-2001 situation is that one should include
.I <sys/select.h>
for
-.B select
+.BR select ()
and
-.BR pselect .
+.BR pselect ().
Libc4 and libc5 do not have a
.I <sys/select.h>
header; under glibc 2.0 and later this header exists.
Under glibc 2.0 it unconditionally gives the wrong prototype for
-.BR pselect ,
+.BR pselect (),
under glibc 2.1-2.2.1 it gives
-.B pselect
+.BR pselect ()
when
.B _GNU_SOURCE
is defined, under glibc 2.2.2-2.2.4 it gives it when
is defined and has a value of 600 or larger.
No doubt, since POSIX 1003.1-2001, it should give the prototype by default.
.SH BUGS
-.B pselect
+.BR pselect ()
is currently emulated with a user-space wrapper that has a race condition.
For reliable (and more portable) signal trapping, use the self-pipe trick.
(Where a signal handler writes to a pipe whose other end is read by the
main loop.)
Under Linux,
-.B select
+.BR select ()
may report a socket file descriptor as "ready for reading", while
nevertheless a subsequent read blocks. This could for example
happen when data has arrived but upon examination has wrong
.fi
.SH DESCRIPTION
-\fBselect\fP (or \fBpselect\fP) is the pivot function of most C programs that
+\fBselect\fP() (or \fBpselect\fP) is the pivot function of most C programs that
handle more than one simultaneous file descriptor (or socket handle) in an efficient
manner. Its principal arguments are three arrays of file descriptors:
\fIreadfds\fP, \fIwritefds\fP, and \fIexceptfds\fP. The way that
-\fBselect\fP is usually used is to block while waiting for a "change of
+\fBselect\fP() is usually used is to block while waiting for a "change of
status" on one or more of the file descriptors. A "change of status" is
when more characters become available from the file descriptor, \fIor\fP
when space becomes available within the kernel's internal buffers for
descriptor goes into error (in the case of a socket or pipe this is
when the other end of the connection is closed).
-In summary, \fBselect\fP just watches multiple file descriptors,
+In summary, \fBselect\fP() just watches multiple file descriptors,
and is the standard Unix call to do so.
The arrays of file descriptors are called \fIfile descriptor sets\fP.
Each set is declared as type \fBfd_set\fP, and its contents can be
-altered with the macros \fBFD_CLR\fP, \fBFD_ISSET\fP, \fBFD_SET\fP, and
-\fBFD_ZERO\fP. \fBFD_ZERO\fP is usually the first function to be used on
+altered with the macros \fBFD_CLR\fP(), \fBFD_ISSET\fP(), \fBFD_SET\fP(), and
+\fBFD_ZERO\fP(). \fBFD_ZERO\fP() is usually the first function to be used on
a newly declared set. Thereafter, the individual file descriptors that
-you are interested in can be added one by one with \fBFD_SET\fP.
-\fBselect\fP modifies the contents of the sets according to the rules
-described below; after calling \fBselect\fP you can test if your file
-descriptor is still present in the set with the \fBFD_ISSET\fP macro.
-\fBFD_ISSET\fP returns non-zero if the descriptor is present and zero if
-it is not. \fBFD_CLR\fP removes a file descriptor from the set although
+you are interested in can be added one by one with \fBFD_SET\fP().
+\fBselect\fP() modifies the contents of the sets according to the rules
+described below; after calling \fBselect\fP() you can test if your file
+descriptor is still present in the set with the \fBFD_ISSET\fP() macro.
+\fBFD_ISSET\fP() returns non-zero if the descriptor is present and zero if
+it is not. \fBFD_CLR\fP() removes a file descriptor from the set although
I can't see the use for it in a clean program.
.SH ARGUMENTS
.TP
\fIreadfds\fP
This set is watched to see if data is available for reading from any of
-its file descriptors. After \fBselect\fP has returned, \fIreadfds\fP will be
+its file descriptors. After \fBselect\fP() has returned, \fIreadfds\fP will be
cleared of all file descriptors except for those file descriptors that
are immediately available for reading with a \fBrecv()\fP (for sockets) or
\fBread()\fP (for pipes, files, and sockets) call.
.TP
\fIwritefds\fP
This set is watched to see if there is space to write data to any of
-its file descriptor. After \fBselect\fP has returned, \fIwritefds\fP will be
+its file descriptor. After \fBselect\fP() has returned, \fIwritefds\fP will be
cleared of all file descriptors except for those file descriptors that
are immediately available for writing with a \fBsend()\fP (for sockets) or
\fBwrite()\fP (for pipes, files, and sockets) call.
\fIexceptfds\fP is to watch for \fIout\-of\-band\fP (OOB) data. OOB data
is data sent on a socket using the \fBMSG_OOB\fP flag, and hence
\fIexceptfds\fP only really applies to sockets. See \fBrecv\fP(2) and
-\fBsend\fP(2) about this. After \fBselect\fP has returned,
+\fBsend\fP(2) about this. After \fBselect\fP() has returned,
\fIexceptfds\fP will be cleared of all file descriptors except for those
descriptors that are available for reading OOB data. You can only ever
read one byte of OOB data though (which is done with \fBrecv()\fP), and
any of the sets. In other words, while you are busy adding file descriptors
to your sets, you must calculate the maximum integer value of all of
them, then increment this value by one, and then pass this as \fInfds\fP to
-\fBselect\fP.
+\fBselect\fP().
.TP
\fIutimeout\fP
.RS
-This is the longest time \fBselect\fP must wait before returning, even
+This is the longest time \fBselect\fP() must wait before returning, even
if nothing interesting happened. If this value is passed as \fBNULL\fP,
-then \fBselect\fP blocks indefinitely waiting for an event.
-\fIutimeout\fP can be set to zero seconds, which causes \fBselect\fP to
+then \fBselect\fP() blocks indefinitely waiting for an event.
+\fIutimeout\fP can be set to zero seconds, which causes \fBselect\fP() to
return immediately. The structure \fBstruct timeval\fP is defined as,
.PP
.nf
.RE
.TP
\fIsigmask\fP
-This argument holds a set of signals to allow while performing a \fBpselect\fP
+This argument holds a set of signals to allow while performing a \fBpselect\fP()
call (see \fBsigaddset\fP(3) and \fBsigprocmask\fP(2)). It can be passed
as NULL, in which case it does not modify the set of allowed signals on
-entry and exit to the function. It will then behave just like \fBselect\fP.
+entry and exit to the function. It will then behave just like \fBselect\fP().
.SH COMBINING SIGNAL AND DATA EVENTS
-\fBpselect\fP must be used if you are waiting for a signal as well as
+\fBpselect\fP() must be used if you are waiting for a signal as well as
data from a file descriptor. Programs that receive signals as events
normally use the signal handler only to raise a global flag. The global
flag will indicate that the event must be processed in the main loop of
-the program. A signal will cause the \fBselect\fP (or \fBpselect\fP)
+the program. A signal will cause the \fBselect\fP() (or \fBpselect\fP)
call to return with \fBerrno\fP set to \fBEINTR\fP. This behavior is
essential so that signals can be processed in the main loop of the
-program, otherwise \fBselect\fP would block indefinitely. Now, somewhere
+program, otherwise \fBselect\fP() would block indefinitely. Now, somewhere
in the main loop will be a conditional to check the global flag. So we
must ask: what if a signal arrives after the conditional, but before the
-\fBselect\fP call? The answer is that \fBselect\fP would block
+\fBselect\fP() call? The answer is that \fBselect\fP() would block
indefinitely, even though an event is actually pending. This race
-condition is solved by the \fBpselect\fP call. This call can be used to
+condition is solved by the \fBpselect\fP() call. This call can be used to
mask out signals that are not to be received except within the
-\fBpselect\fP call. For instance, let us say that the event in question
+\fBpselect\fP() call. For instance, let us say that the event in question
was the exit of a child process. Before the start of the main loop, we
-would block \fBSIGCHLD\fP using \fBsigprocmask\fP. Our \fBpselect\fP
+would block \fBSIGCHLD\fP using \fBsigprocmask\fP. Our \fBpselect\fP()
call would enable \fBSIGCHLD\fP by using the virgin signal mask. Our
program would look like:
.PP
}
.fi
.PP
-Note that the above \fBpselect\fP call can be replaced with:
+Note that the above \fBpselect\fP() call can be replaced with:
.PP
.nf
sigprocmask (SIG_BLOCK, &orig_sigmask, 0);
.PP
but then there is still the possibility that a signal
could arrive after the first \fBsigprocmask\fP and before
-the \fBselect\fP. If you do do this, it is prudent to
+the \fBselect\fP(). If you do do this, it is prudent to
at least put a finite timeout so that the process does
not block. At present glibc probably works this way.
-The Linux kernel does not have a native \fBpselect\fP
+The Linux kernel does not have a native \fBpselect\fP()
system call as yet so this is all probably much of a
moot point.
.PP
merely create a sequence of \fBread\fP and \fBwrite\fP calls, you would
find that one of your calls may block waiting for data from/to a file
descriptor, while another file descriptor is unused though available
-for data. \fBselect\fP efficiently copes with this situation.
+for data. \fBselect\fP() efficiently copes with this situation.
-A classic example of \fBselect\fP comes from the \fBselect\fP
+A classic example of \fBselect\fP() comes from the \fBselect\fP()
man page:
.nf
.SH PORT FORWARDING EXAMPLE
Here is an example that better demonstrates the true utility of
-\fBselect\fP.
+\fBselect\fP().
The listing below is a TCP forwarding program that forwards
from one TCP port to another.
.PP
.SH SELECT LAW
-Many people who try to use \fBselect\fP come across behavior that is
+Many people who try to use \fBselect\fP() come across behavior that is
difficult to understand and produces non-portable or borderline
results. For instance, the above program is carefully written not to
block at any point, even though it does not set its file descriptors to
non-blocking mode at all (see \fBioctl\fP(2)). It is easy to introduce
-subtle errors that will remove the advantage of using \fBselect\fP,
+subtle errors that will remove the advantage of using \fBselect\fP(),
hence I will present a list of essentials to watch for when using the
-\fBselect\fP call.
+\fBselect\fP() call.
.TP
\fB1.\fP
-You should always try use \fBselect\fP without a timeout. Your program
+You should always try use \fBselect\fP() without a timeout. Your program
should have nothing to do if there is no data available. Code that
depends on timeouts is not usually portable and difficult to debug.
.TP
.TP
\fB3.\fP
No file descriptor must be added to any set if you do not intend
-to check its result after the \fBselect\fP call, and respond
+to check its result after the \fBselect\fP() call, and respond
appropriately. See next rule.
.TP
\fB4.\fP
-After \fBselect\fP returns, all file descriptors in all sets
+After \fBselect\fP() returns, all file descriptors in all sets
\fImust\fP be checked. Any file descriptor that is available
for writing \fImust\fP be written to, and any file descriptor
available for reading \fImust\fP be read, etc.
to prevent it being included in a set.
.TP
\fB10.\fP
-The timeout value must be initialized with each new call to \fBselect\fP,
-since some operating systems modify the structure. \fBpselect\fP
+The timeout value must be initialized with each new call to \fBselect\fP(),
+since some operating systems modify the structure. \fBpselect\fP()
however does not modify its timeout structure.
.TP
\fB11.\fP
I have heard that the Windows socket layer does not cope with OOB data
-properly. It also does not cope with \fBselect\fP calls when no file
+properly. It also does not cope with \fBselect\fP() calls when no file
descriptors are set at all. Having no file descriptors set is a useful
way to sleep the process with sub-second precision by using the timeout.
(See further on.)
.SH USLEEP EMULATION
On systems that do not have a \fBusleep\fP function, you can call
-\fBselect\fP with a finite timeout and no file descriptors as
+\fBselect\fP() with a finite timeout and no file descriptors as
follows:
.PP
.nf
.SH RETURN VALUE
-On success, \fBselect\fP returns the total number of file descriptors
+On success, \fBselect\fP() returns the total number of file descriptors
still present in the file descriptor sets.
-If \fBselect\fP timed out, then the file descriptors sets should be all
+If \fBselect\fP() timed out, then the file descriptors sets should be all
empty (but may not be on some systems). However the return value will
definitely be zero.
A return value of \-1 indicates an error, with \fBerrno\fP being
set appropriately. In the case of an error, the returned sets and
the timeout struct contents are undefined and should not be used.
-\fBpselect\fP however never modifies \fIntimeout\fP.
+\fBpselect\fP() however never modifies \fIntimeout\fP.
.SH ERRORS
.TP
.SH NOTES
Generally speaking, all operating systems that support sockets, also
-support \fBselect\fP. Some people consider \fBselect\fP to be an
+support \fBselect\fP(). Some people consider \fBselect\fP() to be an
esoteric and rarely used function. Indeed, many types of programs become
-extremely complicated without it. \fBselect\fP can be used to solve
+extremely complicated without it. \fBselect\fP() can be used to solve
many problems in a portable and efficient way that naive programmers try
to solve with threads, forking, IPCs, signals, memory sharing and other
-dirty methods. \fBpselect\fP is a newer function that is less commonly
+dirty methods. \fBpselect\fP() is a newer function that is less commonly
used.
.PP
The
.BR poll (2)
-system call has the same functionality as \fBselect\fP,
-but with less subtle behavior. It is less portable than \fBselect\fP.
+system call has the same functionality as \fBselect\fP(),
+but with less subtle behavior. It is less portable than \fBselect\fP().
.SH CONFORMING TO
-4.4BSD (the \fBselect\fP function first appeared in 4.2BSD). Generally
+4.4BSD (the \fBselect\fP() function first appeared in 4.2BSD). Generally
portable to/from non-BSD systems supporting clones of the BSD socket
layer (including System V variants). However, note that the System V
variant typically sets the timeout variable before exit, but the BSD
variant does not.
.PP
-The \fBpselect\fP function is defined in IEEE Std 1003.1g-2000 (POSIX.1g).
+The \fBpselect\fP() function is defined in IEEE Std 1003.1g-2000 (POSIX.1g).
It is found in glibc2.1 and later. Glibc2.0 has a function with this name,
that however does not take a \fIsigmask\fP parameter.
.BI "int " flags );
.SH DESCRIPTION
The system calls
-.BR send ,
-.BR sendto ,
+.BR send (),
+.BR sendto (),
and
-.B sendmsg
+.BR sendmsg ()
are used to transmit a message to another socket.
.PP
The
-.B send
+.BR send ()
call may be used only when the socket is in a
.I connected
state (so that the intended recipient is known).
The only difference between
-.B send
+.BR send ()
and
.B write
is the presence of
With zero
.I flags
parameter,
-.B send
+.BR send ()
is equivalent to
.BR write .
Also,
is the file descriptor of the sending socket.
.PP
If
-.B sendto
+.BR sendto ()
is used on a connection-mode (SOCK_STREAM, SOCK_SEQPACKET) socket,
the parameters
.I to
.I tolen
specifying its size.
For
-.BR sendmsg ,
+.BR sendmsg (),
the address of the target is given by
.IR msg.msg_name ,
with
specifying its size.
.PP
For
-.B send
+.BR send ()
and
-.BR sendto ,
+.BR sendto (),
the message is found in
.I buf
and has length
.IR len .
For
-.BR sendmsg ,
+.BR sendmsg (),
the message is pointed to by the elements of the array
.IR msg.msg_iov .
The
-.B sendmsg
+.BR sendmsg ()
call also allows sending ancillary data (also known as control information).
.PP
If the message is too long to pass atomically through the
is returned, and the message is not transmitted.
.PP
No indication of failure to deliver is implicit in a
-.BR send .
+.BR send ().
Locally detected errors are indicated by a return value of \-1.
.PP
When the message does not fit into the send buffer of the socket,
-.B send
+.BR send ()
normally blocks, unless the socket has been placed in non-blocking I/O
mode. In non-blocking mode it would return
.B EAGAIN
.sp
.BI "int set_thread_area (struct user_desc *" u_info );
.SH "DESCRIPTION"
-.B set_thread_area
+.BR set_thread_area ()
sets an entry in the current thread's Thread Local Storage (TLS) array.
The TLS array entry set by
-.B set_thread_area
+.BR set_thread_area ()
corresponds to the value of
.I u_info->entry_number
passed in by the user. If this value is in bounds,
-.B set_thread_area
+.BR set_thread_area ()
copies the TLS descriptor pointed to by
.I u_info
into the thread's TLS array.
.PP
When
-.B set_thread_area
+.BR set_thread_area ()
is passed an
.I entry_number
of \-1, it uses a free TLS entry. If
-.B set_thread_area
+.BR set_thread_area ()
finds a free TLS entry, the value of
.I u_info->entry_number
is set upon return to show which entry was changed.
.SH "RETURN VALUE"
-.B set_thread_area
+.BR set_thread_area ()
returns 0 on success, and \-1 on failure, with
.I errno
set appropriately.
A free TLS entry could not be located.
.SH "CONFORMING TO"
-.B set_thread_area
+.BR set_thread_area ()
is Linux specific and should not be used in programs that are intended
to be portable.
.SH "VERSIONS"
A version of
-.B set_thread_area
+.BR set_thread_area ()
first appeared in Linux 2.5.29.
.SH "SEE ALSO"
the fifth parameter of that system call.
.LP
The system call
-.B set_tid_address
+.BR set_tid_address ()
sets the
.I clear_child_tid
value for the calling process to
call is done. (That is, wake a single process waiting on this futex.)
Errors are ignored.
.SH "RETURN VALUE"
-.B set_tid_address
+.BR set_tid_address ()
returns the PID of the current process.
.SH HISTORY
This call is present since Linux 2.5.48.
.br
.BI "int setegid(gid_t " egid );
.SH DESCRIPTION
-.B seteuid
+.BR seteuid ()
sets the effective user ID of the current process.
Unprivileged user processes may only set the effective user ID to the
real user ID, the effective user ID or the saved set-user-ID.
Precisely the same holds for
-.B setegid
+.BR setegid ()
with "group" instead of "user".
.\" When
.BI setresuid(\-1, " euid" ,\-1)
and hence does not change the saved set-user-ID.
Similar remarks hold for
-.BR setegid .
+.BR setegid ().
.SH "CONFORMING TO"
4.3BSD
.SH "SEE ALSO"
.BI "int setfsgid(uid_t " fsgid );
.SH DESCRIPTION
The system call
-.B setfsgid
+.BR setfsgid ()
sets the group ID that the Linux kernel uses to check for all accesses
to the file system. Normally, the value of
.I fsgid
Explicit calls to
.B setfsuid
and
-.B setfsgid
+.BR setfsgid ()
are usually only used by programs such as the Linux NFS server that
need to change what user and group ID is used for file access without a
corresponding change in the real and effective user and group IDs.
A change in the normal user IDs for a program such as the NFS server
is a security hole that can expose it to unwanted signals. (But see below.)
-.B setfsgid
+.BR setfsgid ()
will only succeed if the caller is the superuser or if
.I fsgid
matches either the real group ID, effective group ID,
.I fsgid
is returned.
.SH "CONFORMING TO"
-.B setfsgid
+.BR setfsgid ()
is Linux specific and should not be used in programs intended to be portable.
It is present since Linux 1.1.44 and in libc since libc 4.7.6.
.SH BUGS
.BI "int setfsuid(uid_t " fsuid );
.SH DESCRIPTION
The system call
-.B setfsuid
+.BR setfsuid ()
sets the user ID that the Linux kernel uses to check for all accesses
to the file system. Normally, the value of
.I fsuid
will also be changed to the new value of the effective user ID.
Explicit calls to
-.B setfsuid
+.BR setfsuid ()
and
.B setfsgid
are usually only used by programs such as the Linux NFS server that
A change in the normal user IDs for a program such as the NFS server
is a security hole that can expose it to unwanted signals. (But see below.)
-.B setfsuid
+.BR setfsuid ()
will only succeed if the caller is the superuser or if
.I fsuid
matches either the real user ID, effective user ID, saved set-user-ID, or
.I fsuid
is returned.
.SH "CONFORMING TO"
-.B setfsuid
+.BR setfsuid ()
is Linux specific and should not be used in programs intended to be portable.
It is present since Linux 1.1.44 and in libc since libc 4.7.6.
.SH BUGS
.sp
.BI "int setgid(gid_t " gid );
.SH DESCRIPTION
-.B setgid
+.BR setgid ()
sets the effective group ID of the current process. If the caller is the
superuser, the real GID and saved set-group-ID are also set.
Under Linux,
-.B setgid
+.BR setgid ()
is implemented like the POSIX version with the _POSIX_SAVED_IDS feature.
This allows a set-group-ID program that is not set-user-ID-root
to drop all of its group
.br
.B pid_t getpgrp(void);
.SH DESCRIPTION
-.B setpgid
+.BR setpgid ()
sets the process group ID of the process specified by
.I pid
to
.I pgid
is zero, the process ID of the process specified by
.I pid
-is used. If \fBsetpgid\fP is used to move a process from one process
+is used. If \fBsetpgid\fP() is used to move a process from one process
group to another (as is done by some shells when creating pipelines),
both process groups must be part of the same session. In this case,
the \fIpgid\fP specifies an existing process group to be joined and the
session ID of that group must match the session ID of the joining process.
-.B getpgid
+.BR getpgid ()
returns the process group ID of the process specified by
.IR pid .
If
.I errno
is set appropriately.
-.B getpgid
+.BR getpgid ()
returns a process group on success.
On error, \-1 is returned, and
.I errno
is set appropriately.
-.B getpgrp
+.BR getpgrp ()
always returns the current process group.
.SH ERRORS
.TP
An attempt was made to change the process group ID
of one of the children of the calling process and the child had
already performed an \fBexecve\fP
-(\fBsetpgid\fP, \fBsetpgrp\fP).
+(\fBsetpgid\fP(), \fBsetpgrp\fP).
.TP
.B EINVAL
.I pgid
is less than 0
-(\fBsetpgid\fP, \fBsetpgrp\fP).
+(\fBsetpgid\fP(), \fBsetpgrp\fP).
.TP
.B EPERM
An attempt was made to move a process into a process group in a
group ID of one of the children of the calling process and the
child was in a different session, or to change the process group ID of
a session leader
-(\fBsetpgid\fP, \fBsetpgrp\fP).
+(\fBsetpgid\fP(), \fBsetpgrp\fP).
.TP
.B ESRCH
For
-.BR getpgid :
+.BR getpgid ():
.I pid
does not match any process.
For
-.BR setpgid :
+.BR setpgid ():
.I pid
is not the current process and not a child of the current process.
.SH "CONFORMING TO"
The functions
-.B setpgid
+.BR setpgid ()
and
-.B getpgrp
+.BR getpgrp ()
conform to POSIX.1.
The function
-.B setpgrp
+.BR setpgrp ()
is from 4.2BSD.
The function
-.B getpgid
+.BR getpgid ()
conforms to SVr4.
.SH NOTES
POSIX took
-.B setpgid
+.BR setpgid ()
from the BSD function
-.BR setpgrp .
+.BR setpgrp ().
Also SysV has a function with the same name, but it is identical to
.BR setsid (2).
.LP
.br
.BI "int setresgid(gid_t " rgid ", gid_t " egid ", gid_t " sgid );
.SH DESCRIPTION
-.B setresuid
+.BR setresuid ()
sets the real user ID, the effective user ID, and the
saved set-user-ID of the current process.
If one of the parameters equals \-1, the corresponding value is not changed.
Completely analogously,
-.B setresgid
+.BR setresgid ()
sets the real GID, effective GID, and saved set-group-ID
of the current process,
with the same restrictions for non-privileged processes.
.br
.BI "int setregid(gid_t " rgid ", gid_t " egid );
.SH DESCRIPTION
-.B setreuid
+.BR setreuid ()
sets real and effective user IDs of the current process.
Supplying a value of \-1 for either the real or effective user ID forces
the saved set-user-ID will be set to the new effective user ID.
Completely analogously,
-.B setregid
+.BR setregid ()
sets real and effective group ID's of the current process,
and all of the above holds with "group" instead of "user".
possible since Linux 1.1.37 (1.1.38).
.SH "CONFORMING TO"
4.3BSD (the
-.B setreuid
+.BR setreuid ()
and
-.B setregid
+.BR setregid ()
function calls first appeared in 4.2BSD).
.SH "SEE ALSO"
.BR getgid (2),
The only error which can happen is
EPERM. It is returned when the process group ID of any process
equals the PID of the calling process. Thus, in particular,
-.B setsid
+.BR setsid ()
fails if the calling process is already a process group leader.
.SH NOTES
A process group leader is a process with process group ID equal
to its PID. In order to be sure that
-.B setsid
+.BR setsid ()
will succeed, fork and exit, and have the child do
.BR setsid ().
.SH "CONFORMING TO"
.sp
.BI "int setuid(uid_t " uid );
.SH DESCRIPTION
-.B setuid
+.BR setuid ()
sets the effective user ID of the current process.
If the effective UID of the caller is root,
the real UID and saved set-user-ID are also set.
.PP
Under Linux,
-.B setuid
+.BR setuid ()
is implemented like the POSIX version with the _POSIX_SAVED_IDS feature.
This allows a set-user-ID (other than root) program to drop all of its user
privileges, do some un-privileged work, and then re-engage the original
.PP
If the user is root or the program is set-user-ID-root, special care must be
taken. The
-.B setuid
+.BR setuid ()
function checks the effective user ID of the caller and if it is
the superuser, all process related user ID's are set to
.IR uid .
Thus, a set-user-ID-root program wishing to temporarily drop root
privileges, assume the identity of a non-root user, and then regain
root privileges afterwards cannot use
-.BR setuid .
+.BR setuid ().
You can accomplish this with the (non-POSIX, BSD) call
.BR seteuid .
.SH "RETURN VALUE"
.SH "LINUX-SPECIFIC REMARKS"
Linux has the concept of filesystem user ID, normally equal to the
effective user ID. The
-.B setuid
+.BR setuid ()
call also sets the filesystem user ID of the current process.
See
.BR setfsuid (2).
.sp
.B int setup(void);
.SH DESCRIPTION
-.B setup
+.BR setup ()
is called once from within
.IR linux/init/main.c .
It calls initialization functions for devices and file systems
configured into the kernel and then mounts the root file system.
.PP
No user process may call
-.BR setup .
+.BR setup ().
Any user process, even a process with superuser permission,
will receive
.BR EPERM .
.SH "RETURN VALUE"
-.B setup
+.BR setup ()
always returns \-1 for a user process.
.SH ERRORS
.TP
A complete overview of extended attributes concepts can be found in
.BR attr (5).
.PP
-.B setxattr
+.BR setxattr ()
sets the
.I value
of the extended attribute identified by
.I value
must be specified.
.PP
-.B lsetxattr
+.BR lsetxattr ()
is identical to
-.BR setxattr ,
+.BR setxattr (),
except in the case of a symbolic link, where the extended attribute is
set on the link itself, not the file that it refers to.
.PP
-.B fsetxattr
+.BR fsetxattr ()
is identical to
-.BR setxattr ,
+.BR setxattr (),
only the extended attribute is set on the open file pointed to by
.I filedes
(as returned by
.BI "int shutdown(int " s ", int " how );
.SH DESCRIPTION
The
-.B shutdown
+.BR shutdown ()
call causes all or part of a full-duplex connection on the socket
associated with
.I s
since glibc-2.1.91.
.SH "CONFORMING TO"
4.4BSD (the
-.B shutdown
+.BR shutdown ()
function call first appeared in 4.2BSD).
.SH "SEE ALSO"
.BR connect (2),
.sp
.BI "int sigaltstack(const stack_t *" ss ", stack_t *" oss );
.SH DESCRIPTION
-\fBsigaltstack\fP allows a process to define a new alternate
+\fBsigaltstack\fP() allows a process to define a new alternate
signal stack and/or retrieve the state of an existing
alternate signal stack. An alternate signal stack is used during the
execution of a signal handler if the establishment of that handler (see
signal stack.
.TP
2.
-Use \fBsigaltstack\fP to inform the system of the existence and
+Use \fBsigaltstack\fP() to inform the system of the existence and
location of the alternate signal stack.
.TP
3.
If \fIoss\fP is not NULL, then it is used to return information about
the alternate signal stack which was in effect prior to the
-call to \fBsigaltstack\fP.
+call to \fBsigaltstack\fP().
The \fIoss.ss_sp\fP and \fIoss.ss_size\fP fields return the starting
address and size of that stack.
The \fIoss.ss_flags\fP may return either of the following values:
.B SS_DISABLE
The alternate signal stack is currently disabled.
.SH "RETURN VALUE"
-\fBsigaltstack\fP returns 0 on success, or \-1 on failure with
+\fBsigaltstack\fP() returns 0 on success, or \-1 on failure with
\fIerrno\fP set to indicate the error.
.SH ERRORS
.TP
it was active (i.e., the process was already executing
on the current alternate signal stack).
.SH NOTES
-The following code segment demonstrates the use of \fBsigaltstack\fP:
+The following code segment demonstrates the use of \fBsigaltstack\fP():
.RS
.nf
on an alternate signal stack.
.P
On most hardware architectures supported by Linux, stacks grow
-downwards. \fBsigaltstack\fP automatically takes account
+downwards. \fBsigaltstack\fP() automatically takes account
of the direction of stack growth.
.P
Functions called from a signal handler executing on an alternate
A successful call to \fBexecve\fP removes any existing alternate
signal stack.
.P
-\fBsigaltstack\fP supersedes the older \fBsigstack\fP call.
+\fBsigaltstack\fP() supersedes the older \fBsigstack\fP call.
For backwards compatibility, glibc also provides \fBsigstack\fP.
All new applications should be written using \fBsigaltstack\fB.
.SH HISTORY
.BR sigprocmask (2).
The
-.B sigblock
+.BR sigblock ()
system call adds the signals specified in
.I mask
to the set of signals currently being blocked from delivery.
.PP
The
-.B sigsetmask
+.BR sigsetmask ()
system call replaces the set of blocked signals totally with a new set
specified in
.IR mask .
is a 1.
.PP
The current set of blocked signals can be obtained using
-.BR siggetmask .
+.BR siggetmask ().
.PP
The
-.B sigmask
+.BR sigmask ()
macro is provided to construct the mask for a given
.IR signum .
.SH "RETURN VALUE"
-.B siggetmask
+.BR siggetmask ()
returns the current set of masked signals.
-.B sigsetmask
+.BR sigsetmask ()
and
-.B sigblock
+.BR sigblock ()
return the previous set of masked signals.
.SH NOTES
Prototypes for these functions are only available if
instead of
.B "<signal.h>"
then
-.B signal
+.BR signal ()
is redefined as
.B __bsd_signal
and signal has the BSD semantics. This is not recommended.
Trying to change the semantics of this call using
defines and includes is not a good idea. It is better to avoid
-.B signal
+.BR signal ()
altogether, and use
.BR sigaction (2)
instead.
instead.
.LP
The function
-.B sigpause
+.BR sigpause ()
is designed to wait for some signal.
It changes the process' signal mask (set of blocked signals),
and then waits for a signal to arrive.
Upon arrival of a signal, the original signal mask is restored.
.SH "RETURN VALUE"
If
-.B sigpause
+.BR sigpause ()
returns, it was interrupted by a signal and the return value is \-1
with
.I errno
.SH DESCRIPTION
When the Linux kernel creates the stack frame for a signal handler, a
call to
-.B sigreturn
+.BR sigreturn ()
is inserted into the stack frame so that the signal handler will
call
-.B sigreturn
+.BR sigreturn ()
upon return. This inserted call to
-.B sigreturn
+.BR sigreturn ()
cleans up the stack so that the process can restart from where it was
interrupted by the signal.
.SH "RETURN VALUE"
-.B sigreturn
+.BR sigreturn ()
never returns.
.SH WARNING
The
-.B sigreturn
+.BR sigreturn ()
call is used by the kernel to implement signal handlers. It should
.B never
be called directly. Better yet, the specific use of the
.I __unused
argument varies depending on the architecture.
.SH "CONFORMING TO"
-.B sigreturn
+.BR sigreturn ()
is specific to Linux and should not be used in programs intended to be
portable.
.SH FILES
.BR sigaction (2).
.PP
Under Linux
-.B sigvec
+.BR sigvec ()
is #define'd to
.BR sigaction ,
and provides at best a rough approximation of the BSD sigvec interface.
.SH SYNOPSIS
.BI "int socketcall(int" " call, " "unsigned long *" "args);"
.SH DESCRIPTION
-.B socketcall
+.BR socketcall ()
is a common kernel entry point for the socket system calls.
.I call
determines which socket function to invoke.
.PP
User programs should call the appropriate functions by their usual names.
Only standard library implementors and kernel hackers need to know about
-.BR socketcall .
+.BR socketcall ().
.SH "CONFORMING TO"
This call is specific to Linux, and should not be used in programs
intended to be portable.
.SH "CONFORMING TO"
4.4BSD, SUSv2, POSIX 1003.1-2001.
The
-.B socketpair
+.BR socketpair ()
function call appeared in 4.2BSD. It is generally portable to/from
non-BSD systems supporting clones of the BSD socket layer (including
System V variants).
.BI "int fstatfs(int " fd ", struct statfs *" buf );
.SH DESCRIPTION
The function
-.B statfs
+.BR statfs ()
returns information about a mounted file system.
.I path
is the path name of any file within the mounted filesystem.
is supposed to contain (but see below).
.PP
Fields that are undefined for a particular file system are set to 0.
-.B fstatfs
+.BR fstatfs ()
returns the same information about an open file referenced by descriptor
.IR fd .
.SH "RETURN VALUE"
.PP
.SH "CONFORMING TO"
The Linux
-.B statfs
+.BR statfs ()
was inspired by the 4.4BSD one
(but they do not use the same structure).
.SH "NOTES ON f_fsid"
.BI "int fstatvfs(int " fd ", struct statvfs *" buf );
.SH DESCRIPTION
The function
-.B statvfs
+.BR statvfs ()
returns information about a mounted file system.
.I path
is the path name of any file within the mounted filesystem.
It is unspecified whether all members of the returned struct
have meaningful values on all filesystems.
-.B fstatvfs
+.BR fstatvfs ()
returns the same information about an open file referenced by descriptor
.IR fd .
.SH "RETURN VALUE"
.sp
.BI "int stime(time_t *" t );
.SH DESCRIPTION
-\fBstime\fP sets the system's idea of the time and date. Time, pointed
+\fBstime\fP() sets the system's idea of the time and date. Time, pointed
to by \fIt\fP, is measured in seconds from 00:00:00 GMT January 1, 1970.
\fBstime()\fP may only be executed by the superuser.
.SH "RETURN VALUE"
.sp
.BI "int symlink(const char *" oldpath ", const char *" newpath );
.SH DESCRIPTION
-.B symlink
+.BR symlink ()
creates a symbolic link named
.I newpath
which contains the string
.sp
.B void sync(void);
.SH DESCRIPTION
-.B sync
+.BR sync ()
first commits inodes to buffers, and then buffers to disk.
.SH ERRORS
This function is always successful.
.BI "int _sysctl(struct __sysctl_args *" args );
.SH DESCRIPTION
The
-.B _sysctl
+.BR _sysctl ()
call reads and/or writes kernel parameters. For example, the hostname,
or the maximum number of open files. The argument has the form
.PP
.SH "RETURN VALUE"
Upon successful completion,
-.B _sysctl
+.BR _sysctl ()
returns 0. Otherwise, a value of \-1 is returned and
.I errno
is set to indicate the error.
This call is Linux-specific, and should not be used in programs
intended to be portable.
A
-.B sysctl
+.BR sysctl ()
call has been present in Linux since version 1.3.57. It originated in
4.4BSD. Only Linux has the
.I /proc/sys
.BI "int sysfs(int " option );
.SH DESCRIPTION
-.B sysfs
+.BR sysfs ()
returns information about the file system types currently present in
the kernel. The specific form of the
-.B sysfs
+.BR sysfs ()
call and the information returned depends on the
.I option
in effect:
The numbering of the file-system type indexes begins with zero.
.SH "RETURN VALUE"
On success,
-.B sysfs
+.BR sysfs ()
returns the file-system index for option
.BR 1 ,
zero for option
.BI "int sysinfo(struct sysinfo *" info );
.SH DESCRIPTION
Until Linux 2.3.16,
-.B sysinfo
+.BR sysinfo ()
used to return information in the following structure:
.RS
and the sizes are given as multiples of \fImem_unit\fP bytes.
-.B sysinfo
+.BR sysinfo ()
provides a simple way of getting overall system statistics. This is more
portable than reading \fI/dev/kmem\fP.
For an example of its use, see intro(2).
(regardless of their loglevel).
The call
-.B syslog
+.BR syslog ()
.RI (2, buf , len )
waits until this kernel log buffer is nonempty, and then reads
at most \fIlen\fP bytes into the buffer \fIbuf\fP. It returns
.IR /proc/kmsg .
The call
-.B syslog
+.BR syslog ()
.RI (3, buf , len )
will read the last \fIlen\fP bytes from the log buffer (nondestructively),
but will not read more than was written into the buffer since the
It returns the number of bytes read.
The call
-.B syslog
+.BR syslog ()
.RI (4, buf , len )
does precisely the same, but also executes the `clear ring buffer' command.
The call
-.B syslog
+.BR syslog ()
.RI (5, dummy , idummy )
only executes the `clear ring buffer' command.
kernel command line contains the word `debug', and to 15 in case
of a kernel fault (the 10 and 15 are just silly, and equivalent to 8).
This variable is set (to a value in the range 1-8) by the call
-.B syslog
+.BR syslog ()
.RI (8, dummy , value ).
The calls
-.B syslog
+.BR syslog ()
.RI ( type , dummy , idummy )
with \fItype\fP equal to 6 or 7, set it to 1 (kernel panics only)
or 7 (all except debugging messages), respectively.
In libc4 and libc5 the number of this call was defined by
.BR SYS_klog .
In glibc 2.0 the syscall is baptised
-.BR klogctl .
+.BR klogctl ().
.SH "SEE ALSO"
.BR syslog (3)
.sp
.BI "time_t time(time_t *" t );
.SH DESCRIPTION
-\fBtime\fP returns the time since the Epoch
+\fBtime\fP() returns the time since the Epoch
(00:00:00 UTC, January 1, 1970), measured in seconds.
If
.B int tgkill(int tgid, int tid, int sig);
.fi
.SH DESCRIPTION
-The \fBtkill\fP system call is analogous to
+The \fBtkill\fP() system call is analogous to
.BR kill (2),
except when the specified process is part of a thread group
(created by specifying the CLONE_THREAD flag in the call to clone).
Since all the processes in a thread group have the same PID,
they cannot be individually signalled with \fBkill\fP.
-With \fBtkill\fP, however, one can address each process
+With \fBtkill\fP(), however, one can address each process
by its unique TID.
.PP
-The \fBtgkill\fP call improves on \fBtkill\fP by allowing the caller to
+The \fBtgkill\fP() call improves on \fBtkill\fP() by allowing the caller to
specify the thread group ID of the thread to be signalled, protecting
-against TID reuse. If the tgid is specified as \-1, \fBtgkill\fP degenerates
-into \fBtkill\fP.
+against TID reuse. If the tgid is specified as \-1, \fBtgkill\fP() degenerates
+into \fBtkill\fP().
.PP
These are the raw system call interfaces, meant for internal
thread library use.
.B ESRCH
No process with the specified thread ID (and thread group ID) exists.
.SH "CONFORMING TO"
-\fBtkill\fP and \fBtgkill\fP are Linux specific and should not be used
+\fBtkill\fP() and \fBtgkill\fP() are Linux specific and should not be used
in programs that are intended to be portable.
-\fBtkill\fP is supported since Linux 2.4.19 / 2.5.4.
-\fBtgkill\fP was added in Linux 2.5.75.
+\fBtkill\fP() is supported since Linux 2.4.19 / 2.5.4.
+\fBtgkill\fP() was added in Linux 2.5.75.
.SH "SEE ALSO"
.BR gettid (2),
.BR kill (2)
is set appropriately.
.SH ERRORS
For
-.BR truncate :
+.BR truncate ():
.TP
.B EACCES
Search permission is denied for a component of the path prefix,
.SH "CONFORMING TO"
4.4BSD, SVr4 (these function calls first appeared in 4.2BSD).
POSIX 1003.1-1996 has
-.BR ftruncate .
+.BR ftruncate ().
POSIX 1003.1-2001 also has
.IR truncate ,
as an XSI extension.
.sp
.BI "int uname(struct utsname *" buf );
.SH DESCRIPTION
-.B uname
+.BR uname ()
returns system information in the structure pointed to by
.IR buf .
The
.SH "CONFORMING TO"
SVr4, SVID, POSIX, X/OPEN.
There is no
-.B uname
+.BR uname ()
call in 4.3BSD.
.PP
The
Note that there is no standard that says that the hostname set by
.BR sethostname (2)
is the same string as the \fInodename\fP field of the struct returned by
-.B uname
+.BR uname ()
(indeed, some systems allow a 256-byte hostname and an 8-byte nodename),
but this is true on Linux. The same holds for
.BR setdomainname (2)
.sp
.BI "int unlink(const char *" pathname );
.SH DESCRIPTION
-.B unlink
+.BR unlink ()
deletes a name from the filesystem. If that name was the
last link to a file and no processes have the file open the file is
deleted and the space it was using is made available for reuse.
.sp
.BI "int uselib(const char *" library );
.SH DESCRIPTION
-The system call \fBuselib\fP serves to load
+The system call \fBuselib\fP() serves to load
a shared library to be used by the calling process.
It is given a pathname. The address where to load is found
in the library itself. The library can have any recognized
.sp
.BI "int ustat(dev_t " dev ", struct ustat *" ubuf );
.SH DESCRIPTION
-.B ustat
+.BR ustat ()
returns information about a mounted file system.
.I dev
is a device number identifying a device containing
SVr4. SVr4 documents additional error conditions ENOLINK, ECOMM, and EINTR
but has no ENOSYS condition.
.SH NOTES
-.B ustat
+.BR ustat ()
is deprecated and has only been provided for compatibility.
All new programs should use
.BR statfs (2)
.BI "int utimes(const char *" filename ", const struct timeval " tv [2]);
.fi
.SH DESCRIPTION
-.B utime
+.BR utime ()
changes the access and modification times of the inode specified by
.I filename
to the
.RE
The function
-.B utime
+.BR utime ()
allows specification of time stamps with a resolution of 1 second.
The function
-.B utimes
+.BR utimes ()
is similar, but allows a resolution of 1 microsecond.
Here
.IR tv [0]
on an append-only file.
In libc4 and libc5,
-.B utimes
+.BR utimes ()
is just a wrapper for
-.B utime
+.BR utime ()
and hence does not allow a subsecond resolution.
POSIX calls
-.B utimes
+.BR utimes ()
legacy.
.SH BUGS
Linux is not careful to distinguish between the EACCES and EPERM error returns.
On the other hand, POSIX 1003.1-2003 is buggy in its error description for
-.BR utimes .
+.BR utimes ().
.SH "CONFORMING TO"
-.BR utime :
+.BR utime ():
SVr4, SVID, POSIX. SVr4 documents additional error conditions EFAULT,
EINTR, ELOOP, EMULTIHOP, ENAMETOOLONG, ENOLINK, ENOLINK, ENOTDIR.
.br
-.BR utimes :
+.BR utimes ():
4.3BSD
.SH "SEE ALSO"
.BR chattr (1),
.sp
.B int vhangup(void);
.SH DESCRIPTION
-.B vhangup
+.BR vhangup ()
simulates a hangup on the current terminal. This call arranges for other
users to have a \*(lqclean\*(rq tty at login time.
.SH "RETURN VALUE"
.TP
.B EPERM
The calling process has insufficient privilege to call
-.BR vhangup ;
+.BR vhangup ();
the
.B CAP_SYS_TTY_CONFIG
capability is required.
.BI "int vm86(unsigned long " fn ", struct vm86plus_struct *" v86 );
.SH DESCRIPTION
The system call
-.B vm86
+.BR vm86 ()
was introduced in Linux 0.97p2. In Linux 2.1.15 and 2.0.28 it was renamed to
-.BR vm86old ,
+.BR vm86old (),
and a new
-.B vm86
+.BR vm86 ()
was introduced. The definition of `struct vm86_struct' was changed
in 1.1.8 and 1.1.9.
.LP
.sp
.BI "ssize_t write(int " fd ", const void *" buf ", size_t " count );
.SH DESCRIPTION
-.B write
+.BR write ()
writes up to
.I count
bytes to the file referenced by the file descriptor
not just before any data is written.
.SH NOTES
A successful return from
-.B write
+.BR write ()
does not make any guarantee that data has been committed to disk.
In fact, on some buggy implementations, it does not even guarantee
that space has successfully been reserved for the data.
.BI "void __setfpucw((unsigned short) " control_word );
.br
.SH DESCRIPTION
-.B __setfpucw
+.BR __setfpucw ()
transfers
.I control_word
to the registers of the fpu (floating point unit) on i386 architecture. This
.sp
.SH DESCRIPTION
The
-.B aio_cancel
+.BR aio_cancel ()
function attempts to cancel outstanding asynchronous I/O requests
for the file descriptor
.IR fd .
.sp
.SH DESCRIPTION
The
-.B aio_error
+.BR aio_error ()
function returns the error status for the asynchronous I/O request
with control block pointed to by
.IR aiocbp .
.sp
.SH DESCRIPTION
The
-.B aio_fsync
+.BR aio_fsync ()
function does a sync on all outstanding asynchronous I/O operations
associated with
.IR aiocbp->aio_fildes .
.sp
.SH DESCRIPTION
The
-.B aio_read
+.BR aio_read ()
function requests an asynchronous "n = read(fd, buf, count)"
with fd, buf, count given by
.IR aiocbp->aio_fildes ,
.sp
.SH DESCRIPTION
The
-.B aio_return
+.BR aio_return ()
function returns the final return status for the asynchronous I/O request
with control block pointed to by
.IR aiocbp .
.fi
.SH DESCRIPTION
The
-.B aio_suspend
+.BR aio_suspend ()
function suspends the calling process until at least one of the
asynchronous I/O requests in the list
.I cblist
.sp
.SH DESCRIPTION
The
-.B aio_write
+.BR aio_write ()
function requests an asynchronous "n = write(fd, buf, count)"
with fd, buf, count given by
.IR aiocbp->aio_fildes ,
.BI "void *alloca(size_t " size );
.SH DESCRIPTION
The
-.B alloca
+.BR alloca ()
function allocates
.I size
bytes of space in the stack frame of the caller. This temporary space is
automatically freed when the function that called
-.B alloca
+.BR alloca ()
returns to its caller.
.SH "RETURN VALUE"
The
-.B alloca
+.BR alloca ()
function returns a pointer to the beginning of the allocated space.
If the allocation causes stack overflow, program behaviour is undefined.
.SH "CONFORMING TO"
There is evidence that the
-.B alloca
+.BR alloca ()
function appeared in 32v, pwb, pwb.2, 3bsd, and 4bsd. There is a man page
for it in 4.3BSD. Linux uses the GNU version.
This function is not in POSIX or SUSv3.
Normally,
.B gcc
translates calls to
-.B alloca
+.BR alloca ()
by inlined code. This is not done when either the \-ansi or
the \-fno\-builtin option is given. But beware! By default
the glibc version of
Thus, there is no NULL error return.
.SH BUGS
The
-.B alloca
+.BR alloca ()
function is machine and compiler dependent. On many systems
its implementation is buggy. Its use is discouraged.
.LP
On many systems
-.B alloca
+.BR alloca ()
cannot be used inside the list of arguments of a function call, because
the stack space reserved by
-.B alloca
+.BR alloca ()
would appear on the stack in the middle of the space for the
function arguments.
.SH "SEE ALSO"
.BI "int vasprintf(char **" strp ", const char *" fmt ", va_list " ap );
.SH DESCRIPTION
The functions
-.B asprintf
+.BR asprintf ()
and
-.B vasprintf
+.BR vasprintf ()
are analogues of
.B sprintf
and
.fi
.SH DESCRIPTION
Warning: there are two different functions
-.B basename
+.BR basename ()
- see below.
.LP
The functions
-.B dirname
+.BR dirname ()
and
-.B basename
+.BR basename ()
break a null-terminated pathname string into directory
and filename components.
In the usual case,
-.B dirname
+.BR dirname ()
returns the string up to, but not including, the final '/', and
-.B basename
+.BR basename ()
returns the component following the final '/'.
Trailing '/' characters are not counted as part of the pathname.
.PP
If
.I path
does not contain a slash,
-.B dirname
+.BR dirname ()
returns the string "." while
-.B basename
+.BR basename ()
returns a copy of
.IR path .
If
.I path
is the string "/", then both
-.B dirname
+.BR dirname ()
and
-.B basename
+.BR basename ()
return the string "/".
If
.I path
is a NULL pointer or points to an empty string, then both
-.B dirname
+.BR dirname ()
and
-.B basename
+.BR basename ()
return the string ".".
.PP
Concatenating the string returned by
-.BR dirname ,
+.BR dirname (),
a "/", and the string returned by
-.B basename
+.BR basename ()
yields a complete pathname.
.PP
Both
-.B dirname
+.BR dirname ()
and
-.B basename
+.BR basename ()
may modify the contents of
.IR path ,
so copies should be passed to these functions.
Furthermore,
-.B dirname
+.BR dirname ()
and
-.B basename
+.BR basename ()
may return pointers to statically allocated memory
which may be overwritten by subsequent calls.
.PP
The following list of examples (taken from SUSv2)
shows the strings returned by
-.B dirname
+.BR dirname ()
and
-.B basename
+.BR basename ()
for different paths:
.sp
.nf
.RE
.SH "RETURN VALUE"
Both
-.B dirname
+.BR dirname ()
and
-.B basename
+.BR basename ()
return pointers to null-terminated strings.
.SH NOTES
There are two different versions of
-.B basename
+.BR basename ()
- the POSIX version described above, and the GNU version one gets
after
.br
.I path
has a trailing slash, and in particular also when it is "/".
There is no GNU version of
-.BR dirname .
+.BR dirname ().
.LP
With glibc, one gets the POSIX version of
-.B basename
+.BR basename ()
when <libgen.h> is included, and the GNU version otherwise.
.SH BUGS
In the glibc implementation of the POSIX versions of these functions
they modify their argument, and segfault when called with a static string
like "/usr/".
Before glibc 2.2.1, the glibc version of
-.B dirname
+.BR dirname ()
did not correctly handle pathnames with trailing '/' characters,
and generated a segfault if given a NULL argument.
.SH "CONFORMING TO"
.BI "wint_t btowc(int " c );
.fi
.SH DESCRIPTION
-The \fBbtowc\fP function converts \fIc\fP, interpreted as a multibyte sequence
+The \fBbtowc\fP() function converts \fIc\fP, interpreted as a multibyte sequence
of length 1, starting in the initial shift state, to a wide character and
returns it. If \fIc\fP is EOF or not a valid multibyte sequence of length 1,
-the \fBbtowc\fP function returns WEOF.
+the \fBbtowc\fP() function returns WEOF.
.SH "RETURN VALUE"
-The \fBbtowc\fP function returns the wide character converted from the single
+The \fBbtowc\fP() function returns the wide character converted from the single
byte \fIc\fP. If \fIc\fP is EOF or not a valid multibyte sequence of length 1,
it returns WEOF.
.SH "CONFORMING TO"
.SH "SEE ALSO"
.BR mbtowc (3)
.SH NOTES
-The behaviour of \fBbtowc\fP depends on the LC_CTYPE category of the
+The behaviour of \fBbtowc\fP() depends on the LC_CTYPE category of the
current locale.
.PP
This function should never be used. It does not work for encodings which have
sysctl; see
.BR socket (7).
.PP
-.B CMSG_FIRSTHDR
+.BR CMSG_FIRSTHDR ()
returns a pointer to the first
.B cmsghdr
in the ancillary
data buffer associated with the passed
.BR msghdr .
.PP
-.B CMSG_NXTHDR
+.BR CMSG_NXTHDR ()
returns the next valid
.B cmsghdr
after the passed
.B NULL
when there isn't enough space left in the buffer.
.PP
-.BR CMSG_ALIGN ,
+.BR CMSG_ALIGN (),
given a length, returns it including the required alignment. This is a
constant expression.
.PP
-.B CMSG_SPACE
+.BR CMSG_SPACE ()
returns the number of bytes an ancillary element with payload of the passed data length
occupies. This is a constant expression.
.PP
member of the
.B msghdr
with the length of the control message buffer. Use
-.B CMSG_FIRSTHDR
+.BR CMSG_FIRSTHDR ()
on the
.B msghdr
to get the first control message and
field of the
.B msghdr
should be set to the sum of the
-.B CMSG_SPACE
+.BR CMSG_SPACE ()
of the length of
all control messages in the buffer.
For more information on the
.SH NOTES
For portability, ancillary data should be accessed only using the macros
described here.
-.B CMSG_ALIGN
+.BR CMSG_ALIGN ()
is a Linux extension and should be not used in portable programs.
.PP
In Linux,
.BR CMSG_LEN ,
.BR CMSG_DATA ,
and
-.B CMSG_ALIGN
+.BR CMSG_ALIGN ()
are constant expressions (assuming their argument is constant);
this could be used to declare the size of global
variables. This may be not portable, however.
.sp
.BI "char *crypt(const char *" key ", const char *" salt );
.SH DESCRIPTION
-.B crypt
+.BR crypt ()
is the password encryption function. It is based on the Data Encryption
Standard algorithm with variations intended (among other things) to
discourage use of hardware implementations of a key search.
.TP
.B ENOSYS
The
-.B crypt
+.BR crypt ()
function was not implemented, probably because of U.S.A. export restrictions.
.\" This level of detail is not necessary in this man page. . .
.\" .PP
To set the key's parity, which for
.SM DES
is in the low bit of each byte, use
-.BR des_setparity .
+.BR des_setparity ().
The second parameter,
.IR data ,
contains the data to be encrypted or decrypted. The
in software and the routine returns
.SM DESERR_NOHWDEVICE\s0.
For
-.BR cbc_crypt ,
+.BR cbc_crypt (),
the parameter
.I ivec
is the 8-byte initialization
On error \-1 is returned.
.SH NOTES
The prototype for
-.B dirfd
+.BR dirfd ()
is only available if
.B _BSD_SOURCE
or
.BR __attribute__((destructor))
function attributes. See the gcc info pages for information on these.
Constructor routines are executed before
-.B dlopen
+.BR dlopen ()
returns, and destructor routines are executed before
-.B dlclose
+.BR dlclose ()
returns.
.SH "GNU EXTENSIONS"
Glibc adds two functions not described by POSIX, with prototypes
.BI "int vdprintf(int " fd ", const char *" format ", va_list " ap );
.SH DESCRIPTION
The functions
-.B dprintf
+.BR dprintf ()
and
-.B vdprintf
+.BR vdprintf ()
(as found in the glibc2 library) are exact analogues of
.B fprintf
and
where the first parameter is a debugging level (and output is to
.IR stderr ).
Moreover,
-.B dprintf
+.BR dprintf ()
(or
.BR DPRINTF )
is also a popular macro name for a debugging printf.
.BI "int *" sign ", char *" buf ", size_t " len );
.SH DESCRIPTION
The functions
-.BR ecvt_r ,
-.BR fcvt_r ,
-.BR qecvt_r
+.BR ecvt_r (),
+.BR fcvt_r (),
+.BR qecvt_r ()
and
-.BR qfcvt_r
+.BR qfcvt_r ()
are identical to
.BR ecvt ,
.BR fcvt ,
.RI (* envz ,* envz_len )
if there was one.
.LP
-.B envz_strip
+.BR envz_strip ()
removes all entries with value NULL.
.SH "RETURN VALUE"
All envz functions that do memory allocation have a return type of
from the standard hex-digits-and-colons notation into binary data in
network byte order and returns a pointer to it in a statically
allocated buffer, which subsequent calls will
-overwrite. \fBether_aton\fP returns NULL if the address is invalid.
+overwrite. \fBether_aton\fP() returns NULL if the address is invalid.
.PP
The \fBether_ntoa()\fP function converts the Ethernet host address
\fIaddr\fP given in network byte order to a string in standard
must be sufficiently long, e.g., have the same length as
.IR line .
.PP
-The functions \fBether_ntoa_r\fP and \fBether_aton_r\fP are re-entrant
-threadsafe versions of \fBether_ntoa\fP and \fBether_aton\fP
+The functions \fBether_ntoa_r\fP() and \fBether_aton_r\fP() are re-entrant
+threadsafe versions of \fBether_ntoa\fP() and \fBether_aton\fP()
respectively, and do not use static buffers.
.PP
The structure \fIether_addr\fP is defined in \fInet/ethernet.h\fP as:
The
.I "const char *arg"
and subsequent ellipses in the
-.BR execl ,
-.BR execlp ,
+.BR execl (),
+.BR execlp (),
and
-.B execle
+.BR execle ()
functions can be thought of as
.IR arg0 ,
.IR arg1 ,
.BR "(char *) NULL" .
.PP
The
-.B execv
+.BR execv ()
and
-.B execvp
+.BR execvp ()
functions provide an array of pointers to null-terminated strings that
represent the argument list available to the new program. The first
argument, by convention, should point to the file name associated with the
pointer.
.PP
The
-.B execle
+.BR execle ()
function also specifies the environment of the executed process by following
the
.B NULL
Some of these functions have special semantics.
.PP
The functions
-.B execlp
+.BR execlp ()
and
-.B execvp
+.BR execvp ()
will duplicate the actions of the shell in searching for an executable file
if the specified file name does not contain a slash (/) character. The
search path is the path specified in the environment by the
traditional "current directory first" default path.
.PP
The behavior of
-.B execlp
+.BR execlp ()
and
-.B execvp
+.BR execvp ()
when errors occur while attempting to execute the file is historic
practice, but has not traditionally been documented and is not specified by
the POSIX standard. BSD (and possibly other systems) do an automatic
error and returns immediately.
.PP
Traditionally, the functions
-.B execlp
+.BR execlp ()
and
-.B execvp
+.BR execvp ()
ignored all errors except for the ones described above and
.B ENOMEM
and
upon which they returned. They now return if any error other than the ones
described above occurs.
.SH "CONFORMING TO"
-.BR execl ,
-.BR execv ,
-.BR execle ,
-.B execlp
+.BR execl (),
+.BR execv (),
+.BR execle (),
+.BR execlp ()
and
-.B execvp
+.BR execvp ()
conform to
IEEE Std1003.1-88 (``POSIX.1'').
.sp
Link with \-lm.
.SH DESCRIPTION
-The \fBfabs\fP functions return the absolute value of the floating-point
+The \fBfabs\fP() functions return the absolute value of the floating-point
number \fIx\fP.
.SH ERRORS
No errors can occur.
.BI "int fclose(FILE *" fp );
.SH DESCRIPTION
The
-.B fclose
+.BR fclose ()
function will flush the stream pointed to by
.IR fp
(writing any buffered output data using
.\" something like close(fileno(fp)).
.PP
The
-.B fclose
+.BR fclose ()
function may also fail and set
.I errno
for any of the errors specified for the routines
.BR fflush (3).
.SH NOTES
Note that
-.B fclose
+.BR fclose ()
only flushes the user space buffers provided by the
C library. To ensure that the data is physically stored
on disk the kernel buffers must be flushed too, e.g. with
.BR fsync (2).
.SH "CONFORMING TO"
The
-.B fclose
+.BR fclose ()
function conforms to ANSI X3.159-1989 (``ANSI C'').
.SH "SEE ALSO"
.BR close (2),
.B int fcloseall(void);
.SH DESCRIPTION
The
-.B fcloseall
+.BR fcloseall ()
function dissociates all open streams
from its underlying file or set of functions. Any buffered output data is
written first, using
.BR setbuf (3)
.SH "CONFORMING TO"
The
-.B fcloseall
+.BR fcloseall ()
function is a GNU extension.
is the bitwise OR of all bits corresponding to supported exceptions.
.PP
The
-.B feclearexcept
+.BR feclearexcept ()
function clears the supported exceptions represented by the bits
in its argument.
.LP
The
-.B fegetexceptflag
+.BR fegetexceptflag ()
function stores a representation of the state of the exception flags
represented by the argument
.I excepts
.RI * flagp .
.LP
The
-.B feraiseexcept
+.BR feraiseexcept ()
function raises the supported exceptions represented by the bits in
.IR excepts .
.LP
The
-.B fesetexceptflag
+.BR fesetexceptflag ()
function sets the complete status for the exceptions represented by
.I excepts
to the value
.RI * flagp .
This value must have been obtained by an earlier call of
-.B fegetexceptflag
+.BR fegetexceptflag ()
with a last argument that contained all bits in
.IR excepts .
.LP
The
-.B fetestexcept
+.BR fetestexcept ()
function returns a word in which the bits are set that were
set in the argument
.I excepts
the corresponding rounding direction.
.LP
The
-.B fegetround
+.BR fegetround ()
function returns the macro corresponding to the current
rounding mode.
.LP
The
-.B fesetround
+.BR fesetround ()
function sets the rounding mode as specified by its argument
and returns zero when it was successful.
.SS "Floating point environment"
(continue on exceptions) mode.
.LP
The
-.B fegetenv
+.BR fegetenv ()
function saves the current floating point environment in the object
.RI * envp .
.LP
The
-.B feholdexcept
+.BR feholdexcept ()
function does the same, then clears all exception flags,
and sets a non-stop (continue on exceptions) mode,
if available. It returns zero when successful.
.LP
The
-.B fesetenv
+.BR fesetenv ()
function restores the floating point environment from
the object
.RI * envp .
This object must be known to be valid, e.g., the result of a call to
-.B fegetenv
+.BR fegetenv ()
or
-.B feholdexcept
+.BR feholdexcept ()
or equal to
.BR FE_DFL_ENV .
This call does not raise exceptions.
.LP
The
-.B feupdateenv
+.BR feupdateenv ()
function installs the floating-point environment represented by
the object
.RI * envp ,
.fi
.LP
The
-.B feenableexcept
+.BR feenableexcept ()
and
-.B fedisableexcept
+.BR fedisableexcept ()
functions enable (disable) traps for each of the exceptions represented by
.I excepts
and return the previous set of enabled exceptions when successful,
and \-1 otherwise.
The
-.B fegetexcept
+.BR fegetexcept ()
function returns the set of all currently enabled exceptions.
.SH NOTES
.BI "int fileno(FILE *" stream );
.SH DESCRIPTION
The function
-.B clearerr
+.BR clearerr ()
clears the end-of-file and error indicators for the stream pointed to by
.IR stream .
.PP
The function
-.B feof
+.BR feof ()
tests the end-of-file indicator for the stream pointed to by
.IR stream ,
returning non-zero if it is set. The end-of-file indicator can only be
cleared by the function
-.BR clearerr .
+.BR clearerr ().
.PP
The function
-.B ferror
+.BR ferror ()
tests the error indicator for the stream pointed to by
.IR stream ,
returning non-zero if it is set. The error indicator can only be reset by
the
-.B clearerr
+.BR clearerr ()
function.
.PP
The function
-.B fileno
+.BR fileno ()
examines the argument
.I stream
and returns its integer descriptor.
These functions should not fail and do not set the external variable
.IR errno .
(However, in case
-.B fileno
+.BR fileno ()
detects that its argument is not a valid stream, it must
return \-1 and set
.I errno
.BR EBADF .)
.SH "CONFORMING TO"
The functions
-.BR clearerr ,
-.BR feof ,
+.BR clearerr (),
+.BR feof (),
and
-.BR ferror
+.BR ferror ()
conform to X3.159-1989 (``ANSI C'').
.SH "SEE ALSO"
.BR open (2),
.BI "int fflush(FILE *" stream );
.SH DESCRIPTION
The function
-.B fflush
+.BR fflush ()
forces a write of all user-space buffered data for the given output or update
.I stream
via the stream's underlying write function. The open status of the stream
.I stream
argument is
.BR NULL ,
-.B fflush
+.BR fflush ()
flushes
.I all
open output streams.
is not an open stream, or is not open for writing.
.PP
The function
-.B fflush
+.BR fflush ()
may also fail and set
.I errno
for any of the errors specified for the routine
.BI "wint_t getwc(FILE *" stream );
.fi
.SH DESCRIPTION
-The \fBfgetwc\fP function is the wide-character equivalent of the \fBfgetc\fP
+The \fBfgetwc\fP() function is the wide-character equivalent of the \fBfgetc\fP
function. It reads a wide character from \fIstream\fP and returns it. If
the end of stream is reached, or if \fIferror(stream)\fP becomes true,
it returns WEOF. If a wide character conversion error occurs, it sets
\fBerrno\fP to \fBEILSEQ\fP and returns WEOF.
.PP
-The \fBgetwc\fP function or macro functions identically to \fBfgetwc\fP.
+The \fBgetwc\fP() function or macro functions identically to \fBfgetwc\fP().
It may be implemented as a macro, and may evaluate its argument
more than once. There is no reason ever to use it.
.PP
For non-locking counterparts, see
.BR unlocked_stdio (3).
.SH "RETURN VALUE"
-The \fBfgetwc\fP function returns the next wide-character from the stream, or
+The \fBfgetwc\fP() function returns the next wide-character from the stream, or
WEOF.
.SH ERRORS
Apart from the usual ones, there is
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH NOTES
-The behaviour of \fBfgetwc\fP depends on the LC_CTYPE category of the
+The behaviour of \fBfgetwc\fP() depends on the LC_CTYPE category of the
current locale.
.PP
In the absence of additional information passed to the fopen call, it is
-reasonable to expect that \fBfgetwc\fP will actually read a multibyte sequence
+reasonable to expect that \fBfgetwc\fP() will actually read a multibyte sequence
from the stream and then convert it to a wide character.
.SH "SEE ALSO"
.BR fgetws (3),
.BI "wchar_t *fgetws(wchar_t *" ws ", int " n ", FILE *" stream );
.fi
.SH DESCRIPTION
-The \fBfgetws\fP function is the wide-character equivalent of the \fBfgets\fP
+The \fBfgetws\fP() function is the wide-character equivalent of the \fBfgets\fP
function. It reads a string of at most \fIn-1\fP wide characters into the
wide-character array pointed to by \fIws\fP, and adds a terminating L'\\0'
character. It stops reading wide characters after it has encountered and
For a non-locking counterpart, see
.BR unlocked_stdio (3).
.SH "RETURN VALUE"
-The \fBfgetws\fP function, if successful, returns \fIws\fP. If end of stream
+The \fBfgetws\fP() function, if successful, returns \fIws\fP. If end of stream
was already reached or if an error occurred, it returns NULL.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH NOTES
-The behaviour of \fBfgetws\fP depends on the LC_CTYPE category of the
+The behaviour of \fBfgetws\fP() depends on the LC_CTYPE category of the
current locale.
.PP
In the absence of additional information passed to the fopen call, it is
-reasonable to expect that \fBfgetws\fP will actually read a multibyte string
+reasonable to expect that \fBfgetws\fP() will actually read a multibyte string
from the stream and then convert it to a wide character string.
.PP
This function is unreliable, because it does not permit to deal properly with
.fi
.SH DESCRIPTION
The
-.B finite
+.BR finite ()
functions return a non-zero value if \fIx\fP is neither infinite
nor a "not-a-number" (NaN) value, and 0 otherwise.
The
-.B isnan
+.BR isnan ()
functions return a non-zero value if \fIx\fP is a NaN value,
and 0 otherwise.
The
-.B isinf
+.BR isinf ()
functions return 1 if \fIx\fP is plus infinity, \-1 is \fIx\fP
is minus infinity, and 0 otherwise.
is defined.
.SH HISTORY
The
-.B finite
+.BR finite ()
function occurs in 4.3BSD.
.\" see IEEE.3 in the 4.3BSD manual
.SH "SEE ALSO"
.BI "FILE *freopen(const char *" path ", const char *" mode ", FILE *" stream );
.SH DESCRIPTION
The
-.B fopen
+.BR fopen ()
function opens the file whose name is the string pointed to by
.I path
and associates a stream with it.
call.
.PP
The
-.B fdopen
+.BR fdopen ()
function associates a stream with the existing file descriptor,
.IR fildes .
The
Modes "w" or "w+" do not cause truncation of the file.
The file descriptor is not dup'ed, and will be closed when
the stream created by
-.B fdopen
+.BR fdopen ()
is closed.
The result of applying
-.B fdopen
+.BR fdopen ()
to a shared memory object is undefined.
.PP
The
-.B freopen
+.BR freopen ()
function opens the file whose name is the string pointed to by
.I path
and associates the stream pointed to by
with it. The original stream (if it exists) is closed. The
.I mode
argument is used just as in the
-.B fopen
+.BR fopen ()
function. The primary use of the
-.B freopen
+.BR freopen ()
function is to change the file associated with a standard text stream
.IR "" ( stderr ", " stdin ", or " stdout ).
.SH "RETURN VALUE"
Upon successful completion
-.BR fopen ,
-.B fdopen
+.BR fopen (),
+.BR fdopen ()
and
-.B freopen
+.BR freopen ()
return a
.B FILE
pointer. Otherwise,
The
.I mode
provided to
-.BR fopen ,
-.BR fdopen ,
+.BR fopen (),
+.BR fdopen (),
or
-.B freopen
+.BR freopen ()
was invalid.
.PP
The
-.BR fopen ,
-.B fdopen
+.BR fopen (),
+.BR fdopen ()
and
-.B freopen
+.BR freopen ()
functions may also fail and set
.I errno
for any of the errors specified for the routine
.BR malloc (3).
.PP
The
-.B fopen
+.BR fopen ()
function may also fail and set
.I errno
for any of the errors specified for the routine
.BR open (2).
.PP
The
-.B fdopen
+.BR fdopen ()
function may also fail and set
.I errno
for any of the errors specified for the routine
.BR fcntl (2).
.PP
The
-.B freopen
+.BR freopen ()
function may also fail and set
.I errno
for any of the errors specified for the routines
.BR fflush (3).
.SH "CONFORMING TO"
The
-.B fopen
+.BR fopen ()
and
-.B freopen
+.BR freopen ()
functions conform to ANSI X3.159-1989 (``ANSI C''). The
-.B fdopen
+.BR fdopen ()
function conforms to IEEE Std1003.1-1988 (``POSIX.1'').
.SH "SEE ALSO"
.BR open (2),
.BI "wint_t putwc(wchar_t " wc ", FILE *" stream );
.fi
.SH DESCRIPTION
-The \fBfputwc\fP function is the wide-character equivalent of the \fBfputc\fP
+The \fBfputwc\fP() function is the wide-character equivalent of the \fBfputc\fP
function. It writes the wide character \fIwc\fP to \fIstream\fP. If
\fIferror(stream)\fP becomes true, it returns WEOF. If a wide character
conversion error occurs, it sets \fBerrno\fP to \fBEILSEQ\fP and returns WEOF.
Otherwise it returns \fIwc\fP.
.PP
-The \fBputwc\fP function or macro functions identically to \fBfputwc\fP.
+The \fBputwc\fP() function or macro functions identically to \fBfputwc\fP().
It may be implemented as a macro, and may evaluate its argument
more than once. There is no reason ever to use it.
.PP
For non-locking counterparts, see
.BR unlocked_stdio (3).
.SH "RETURN VALUE"
-The \fBfputwc\fP function returns \fIwc\fP if no error occurred, or WEOF to
+The \fBfputwc\fP() function returns \fIwc\fP if no error occurred, or WEOF to
indicate an error.
.SH ERRORS
Apart from the usual ones, there is
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH NOTES
-The behaviour of \fBfputwc\fP depends on the LC_CTYPE category of the
+The behaviour of \fBfputwc\fP() depends on the LC_CTYPE category of the
current locale.
.PP
In the absence of additional information passed to the fopen call, it is
-reasonable to expect that \fBfputwc\fP will actually write the multibyte
+reasonable to expect that \fBfputwc\fP() will actually write the multibyte
sequence corresponding to the wide character \fIwc\fP.
.SH "SEE ALSO"
.BR fgetwc (3),
.BI "int fputws(const wchar_t *" ws ", FILE *" stream );
.fi
.SH DESCRIPTION
-The \fBfputws\fP function is the wide-character equivalent of the \fBfputs\fP
+The \fBfputws\fP() function is the wide-character equivalent of the \fBfputs\fP
function. It writes the wide character string starting at \fIws\fP, up to but
not including the terminating L'\\0' character, to \fIstream\fP.
.PP
For a non-locking counterpart, see
.BR unlocked_stdio (3).
.SH "RETURN VALUE"
-The \fBfputws\fP function returns a nonnegative integer if the operation was
+The \fBfputws\fP() function returns a nonnegative integer if the operation was
successful, or \-1 to indicate an error.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH NOTES
-The behaviour of \fBfputws\fP depends on the LC_CTYPE category of the
+The behaviour of \fBfputws\fP() depends on the LC_CTYPE category of the
current locale.
.PP
In the absence of additional information passed to the fopen call, it is
-reasonable to expect that \fBfputws\fP will actually write the multibyte
+reasonable to expect that \fBfputws\fP() will actually write the multibyte
string corresponding to the wide character string \fIws\fP.
.SH "SEE ALSO"
.BR fputwc (3),
.BI "FILE *" stream );
.SH DESCRIPTION
The function
-.B fread
+.BR fread ()
reads
.I nmemb
elements of data, each
.IR ptr .
.PP
The function
-.B fwrite
+.BR fwrite ()
writes
.I nmemb
elements of data, each
For non-locking counterparts, see
.BR unlocked_stdio (3).
.SH "RETURN VALUE"
-.B fread
+.BR fread ()
and
-.B fwrite
+.BR fwrite ()
return the number of items successfully read or written (i.e., not the
number of characters). If an error occurs, or the end-of-file is
reached, the return value is a short item count (or zero).
.PP
-.B fread
+.BR fread ()
does not distinguish between end-of-file and error, and callers must use
.BR feof (3)
and
to determine which occurred.
.SH "CONFORMING TO"
The functions
-.B fread
+.BR fread ()
and
-.B fwrite
+.BR fwrite ()
conform to ANSI X3.159-1989 (``ANSI C'').
.SH "SEE ALSO"
.BR read (2),
.BI "int fsetpos(FILE *" stream ", fpos_t *" pos );
.SH DESCRIPTION
The
-.B fseek
+.BR fseek ()
function sets the file position indicator for the stream pointed to by
.IR stream .
The new position, measured in bytes, is obtained by adding
.BR SEEK_END ,
the offset is relative to the start of the file, the current position
indicator, or end-of-file, respectively. A successful call to the
-.B fseek
+.BR fseek ()
function clears the end-of-file indicator for the stream and undoes
any effects of the
.BR ungetc (3)
function on the same stream.
.PP
The
-.B ftell
+.BR ftell ()
function obtains the current value of the file position indicator for the
stream pointed to by
.IR stream .
.PP
The
-.B rewind
+.BR rewind ()
function sets the file position indicator for the stream pointed to by
.I stream
to the beginning of the file. It is equivalent to:
.BR clearerr (3)).
.PP
The
-.B fgetpos
+.BR fgetpos ()
and
-.B fsetpos
+.BR fsetpos ()
functions are alternate interfaces equivalent to
-.B ftell
+.BR ftell ()
and
-.B fseek
+.BR fseek ()
(with whence set to
.BR SEEK_SET ),
setting and storing the current value of the file offset into or from the
portably reposition a text stream.
.SH "RETURN VALUE"
The
-.B rewind
+.BR rewind ()
function returns no value. Upon successful completion,
-.BR fgetpos ,
-.BR fseek ,
-.B fsetpos
+.BR fgetpos (),
+.BR fseek (),
+.BR fsetpos ()
return 0,
and
-.B ftell
+.BR ftell ()
returns the current offset. Otherwise, \-1 is returned and the global
variable errno is set to indicate the error.
.SH ERRORS
The
.I whence
argument to
-.B fseek
+.BR fseek ()
was not
.BR SEEK_SET ,
.BR SEEK_END ,
.BR SEEK_CUR .
.PP
The function
-.BR fgetpos ,
-.BR fseek ,
-.BR fsetpos ,
+.BR fgetpos (),
+.BR fseek (),
+.BR fsetpos (),
and
-.B ftell
+.BR ftell ()
may also fail and set
.I errno
for any of the errors specified for the routines
.BR malloc (3).
.SH "CONFORMING TO"
The
-.BR fgetpos ,
-.BR fsetpos ,
-.BR fseek ,
-.BR ftell ,
+.BR fgetpos (),
+.BR fsetpos (),
+.BR fseek (),
+.BR ftell (),
and
-.BR rewind
+.BR rewind ()
functions conform to ANSI X3.159-1989 (``ANSI C'').
.SH "SEE ALSO"
.BR lseek (2),
They are not present in libc4, libc5, glibc 2.0 but available since glibc 2.1.
.SH "CONFORMING TO"
The
-.B fseeko
+.BR fseeko ()
and
-.B ftello
+.BR ftello ()
functions conform to SUSv2.
.SH "SEE ALSO"
.BR fseek (3)
.BI "key_t ftok(const char *" pathname ", int " proj_id );
.SH DESCRIPTION
The
-.B ftok
+.BR ftok ()
function uses the identity of the file named by the given
.I pathname
(which must refer to an existing, accessible file)
.BI "int fwide(FILE *" stream ", int " mode );
.fi
.SH DESCRIPTION
-When \fImode\fP is zero, the \fBfwide\fP function determines the current
+When \fImode\fP is zero, the \fBfwide\fP() function determines the current
orientation of \fIstream\fP. It returns a value > 0 if \fIstream\fP is
wide-character oriented, i.e. if wide character I/O is permitted but char
I/O is disallowed. It returns a value < 0 if \fIstream\fP is byte oriented,
Once a stream has an orientation, it cannot be changed and persists until
the stream is closed.
.PP
-When \fImode\fP is non-zero, the \fBfwide\fP function first attempts to set
+When \fImode\fP is non-zero, the \fBfwide\fP() function first attempts to set
\fIstream\fP's orientation (to wide-character oriented if \fImode\fP > 0, or
to byte oriented if \fImode\fP < 0). It then returns a value denoting the
current orientation, as above.
.SH "RETURN VALUE"
-The \fBfwide\fP function returns the stream's orientation, after possibly
+The \fBfwide\fP() function returns the stream's orientation, after possibly
changing it. A return value > 0 means wide-character oriented. A return value
< 0 means byte oriented. A return value zero means undecided.
.SH "CONFORMING TO"
.B free()
the buffers if they have been obtained this way.
-.BR get_current_dir_name ,
+.BR get_current_dir_name (),
which is only prototyped if
.B _GNU_SOURCE
is defined, will
.B PWD
is set, and its value is correct, then that value will be returned.
-.BR getwd ,
+.BR getwd (),
which is only prototyped if
.B _BSD_SOURCE
or
argument should be a pointer to an array at least
.B PATH_MAX
bytes long.
-.BR getwd
+.BR getwd ()
does only return the first
.B PATH_MAX
bytes of the actual pathname.
.B PATH_MAX
need not be a compile-time constant; it may depend on the filesystem
and may even be unlimited. For portability and security reasons, use of
-.B getwd
+.BR getwd ()
is deprecated.
.SH "RETURN VALUE"
.B NULL
.RI * basep
is updated with the new position after reading.
.SH "RETURN VALUE"
-.B getdirentries
+.BR getdirentries ()
returns the number of bytes read or zero when at the end of the directory.
If an error occurs, \-1 is returned, and
.I errno
.sp
.BI "char *cuserid(char *" string );
.SH DESCRIPTION
-\fBgetlogin\fP returns a pointer to a string containing the name of
+\fBgetlogin\fP() returns a pointer to a string containing the name of
the user logged in on the controlling terminal of the process, or a
null pointer if this information cannot be determined. The string is
statically allocated and might be overwritten on subsequent calls to
-this function or to \fBcuserid\fP.
+this function or to \fBcuserid\fP().
.PP
-\fBgetlogin_r\fP returns this same user name in the array
+\fBgetlogin_r\fP() returns this same user name in the array
.I buf
of size
.IR bufsize .
.PP
-\fBcuserid\fP returns a pointer to a string containing a user name
+\fBcuserid\fP() returns a pointer to a string containing a user name
associated with the effective user ID of the process. If \fIstring\fP
is not a null pointer, it should be an array that can hold at least
\fBL_cuserid\fP characters; the string is returned in this array.
Otherwise, a pointer to a string in a static area is returned. This
string is statically allocated and might be overwritten on subsequent
-calls to this function or to \fBgetlogin\fP.
+calls to this function or to \fBgetlogin\fP().
.PP
The macro \fBL_cuserid\fP is an integer constant that indicates how
long an array you might need to store a user name. \fBL_cuserid\fP is
\fBLOGNAME\fP to find out who the user is. This is more flexible
precisely because the user can set \fBLOGNAME\fP arbitrarily.
.SH "RETURN VALUE"
-\fBgetlogin\fP returns a pointer to the user name when successful,
+\fBgetlogin\fP() returns a pointer to the user name when successful,
and NULL on failure.
-\fBgetlogin_r\fP returns 0 when successful, and non-zero on failure.
+\fBgetlogin_r\fP() returns 0 when successful, and non-zero on failure.
.SH ERRORS
POSIX specifies
.TP
some libc versions used \fI/var/adm/utmp\fP)
.fi
.SH "CONFORMING TO"
-POSIX.1. System V has a \fBcuserid\fP function which uses the real
-user ID rather than the effective user ID. The \fBcuserid\fP function
+POSIX.1. System V has a \fBcuserid\fP() function which uses the real
+user ID rather than the effective user ID. The \fBcuserid\fP() function
was included in the 1988 version of POSIX, but removed from the 1990 version.
.LP
-OpenBSD has \fBgetlogin\fP and \fBsetlogin\fP, and a username
+OpenBSD has \fBgetlogin\fP() and \fBsetlogin\fP, and a username
associated with a session, even if it has no controlling tty.
.SH BUGS
Unfortunately, it is often rather easy to fool getlogin().
.I optstring
is a string containing the legitimate option characters. If such a
character is followed by a colon, the option requires an argument, so
-\fBgetopt\fP places a pointer to the following text in the same
+\fBgetopt\fP() places a pointer to the following text in the same
\fIargv\fP-element, or the text of the following \fIargv\fP-element, in
.IR optarg .
Two colons mean an option takes
\fBgetopt_long\fP() and \fBgetopt_long_only\fP() also return the option
character when a short option is recognized. For a long option, they
return \fIval\fP if \fIflag\fP is \fBNULL\fP, and 0 otherwise. Error
-and \-1 returns are the same as for \fBgetopt\fP (), plus '?' for an
+and \-1 returns are the same as for \fBgetopt\fP() (), plus '?' for an
ambiguous match or an extraneous parameter.
.SH "ENVIRONMENT VARIABLES"
.TP
again.
.SH "RETURN VALUE"
The function
-.B getpass
+.BR getpass ()
returns a pointer to a static buffer containing the
(first PASS_MAX bytes of) the password without the trailing
newline, terminated by a NUL.
.BR crypt (3)
.SH HISTORY
A
-.B getpass
+.BR getpass ()
function appeared in Version 7 AT&T UNIX.
.SH BUGS
The calling process should zero the password as soon as possible to avoid
(either directly, or indirectly through one of
the other \*(lqgetrpc\*(rq calls).
.LP
-.B endrpcent
+.BR endrpcent ()
closes the file.
.LP
.B getrpcbyname()
.BI "int putw(int " w ", FILE *" stream );
.nl
.SH DESCRIPTION
-\fBgetw\fP reads a word (that is, an \fBint\fP) from \fIstream\fP. It's
+\fBgetw\fP() reads a word (that is, an \fBint\fP) from \fIstream\fP. It's
provided for compatibility with SVID. We recommend you use
\fBfread\fP(3) instead.
.P
-\fBputw\fP writes the word \fIw\fP (that is, an \fBint\fP) to \fIstream\fP. It
+\fBputw\fP() writes the word \fIw\fP (that is, an \fBint\fP) to \fIstream\fP. It
is provided for compatibility with SVID, but we recommend you use
\fBfwrite\fP(3) instead.
.SH "RETURN VALUE"
-Normally, \fBgetw\fP returns the word read, and \fBputw\fP returns 0.
+Normally, \fBgetw\fP() returns the word read, and \fBputw\fP() returns 0.
On error, they return \fBEOF\fP.
.SH BUGS
The value returned on error is also a legitimate data value.
.BI "wint_t getwchar(void);"
.fi
.SH DESCRIPTION
-The \fBgetwchar\fP function is the wide-character equivalent of the
+The \fBgetwchar\fP() function is the wide-character equivalent of the
\fBgetchar\fP function. It reads a wide character from \fBstdin\fP and returns
it. If the end of stream is reached, or if \fIferror(stdin)\fP becomes
true, it returns WEOF. If a wide character conversion error occurs, it sets
For a non-locking counterpart, see
.BR unlocked_stdio (3).
.SH "RETURN VALUE"
-The \fBgetwchar\fP function returns the next wide-character from
+The \fBgetwchar\fP() function returns the next wide-character from
standard input, or WEOF.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH NOTES
-The behaviour of \fBgetwchar\fP depends on the LC_CTYPE category of the
+The behaviour of \fBgetwchar\fP() depends on the LC_CTYPE category of the
current locale.
.PP
-It is reasonable to expect that \fBgetwchar\fP will actually read a multibyte
+It is reasonable to expect that \fBgetwchar\fP() will actually read a multibyte
sequence from standard input and then convert it to a wide character.
.SH "SEE ALSO"
.BR fgetwc (3),
.BI "void hdestroy_r(struct hsearch_data *" tab );
.SH DESCRIPTION
The three functions
-.BR hcreate ,
-.BR hsearch ,
+.BR hcreate (),
+.BR hsearch (),
and
-.BR hdestroy
+.BR hdestroy ()
allow the user to create a hash table (only one at a time)
which associates a key with any data.
.PP
\fBNULL\fP.
.PP
The three functions
-.BR hcreate_r ,
-.BR hsearch_r ,
-.BR hdestroy_r
+.BR hcreate_r (),
+.BR hsearch_r (),
+.BR hdestroy_r ()
are reentrant versions that allow the use of more than one table.
The last argument used identifies the table. The struct it points to
must be zeroed before the first call to
is found in the table.
.SH "CONFORMS TO"
The functions
-.BR hcreate ,
-.BR hsearch ,
+.BR hcreate (),
+.BR hsearch (),
and
-.BR hdestroy
+.BR hdestroy ()
are from SVID, and are described in POSIX 1003.1-2001.
The functions
-.BR hcreate_r ,
-.BR hsearch_r ,
-.BR hdestroy_r
+.BR hcreate_r (),
+.BR hsearch_r (),
+.BR hdestroy_r ()
are GNU extensions.
.SH BUGS
SVID and POSIX 1003.1-2001 specify that \fIaction\fP
function \fBiconv_open\fP.
.PP
The main case is when \fIinbuf\fP is not NULL and \fI*inbuf\fP is not NULL.
-In this case, the \fBiconv\fP function converts the multibyte sequence
+In this case, the \fBiconv\fP() function converts the multibyte sequence
starting at \fI*inbuf\fP to a multibyte sequence starting at \fI*outbuf\fP.
At most \fI*inbytesleft\fP bytes, starting at \fI*inbuf\fP, will be read.
At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written.
.PP
-The \fBiconv\fP function converts one multibyte character at a time, and for
+The \fBiconv\fP() function converts one multibyte character at a time, and for
each character conversion it increments \fI*inbuf\fP and decrements
\fI*inbytesleft\fP by the number of converted input bytes, it increments
\fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of converted
is left pointing to the beginning of the invalid multibyte sequence.
.PP
2. The input byte sequence has been entirely converted, i.e. \fI*inbytesleft\fP
-has gone down to 0. In this case \fBiconv\fP returns the number of
+has gone down to 0. In this case \fBiconv\fP() returns the number of
non-reversible conversions performed during this call.
.PP
3. An incomplete multibyte sequence is encountered in the input, and the
.PP
A different case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, but
\fIoutbuf\fP is not NULL and \fI*outbuf\fP is not NULL. In this case, the
-\fBiconv\fP function attempts to set \fIcd\fP's conversion state to the
+\fBiconv\fP() function attempts to set \fIcd\fP's conversion state to the
initial state and store a corresponding shift sequence at \fI*outbuf\fP.
At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written.
If the output buffer has no more room for this reset sequence, it sets
written.
.PP
A third case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, and
-\fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL. In this case, the \fBiconv\fP
+\fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL. In this case, the \fBiconv\fP()
function sets \fIcd\fP's conversion state to the initial state.
.SH "RETURN VALUE"
-The \fBiconv\fP function returns the number of characters converted in a
+The \fBiconv\fP() function returns the number of characters converted in a
non-reversible way during this call; reversible conversions are not counted.
In case of error, it sets \fBerrno\fP and returns (size_t)(\-1).
.SH ERRORS
.BI "int iconv_close(iconv_t " cd );
.fi
.SH DESCRIPTION
-The \fBiconv_close\fP function deallocates a conversion descriptor \fIcd\fP
+The \fBiconv_close\fP() function deallocates a conversion descriptor \fIcd\fP
previously allocated using \fBiconv_open\fP.
.SH "RETURN VALUE"
-When successful, the \fBiconv_close\fP function returns 0.
+When successful, the \fBiconv_close\fP() function returns 0.
In case of error, it sets
.I errno
and returns \-1.
.BI "iconv_t iconv_open(const char *" tocode ", const char *" fromcode );
.fi
.SH DESCRIPTION
-The \fBiconv_open\fP function allocates a conversion descriptor suitable
+The \fBiconv_open\fP() function allocates a conversion descriptor suitable
for converting byte sequences from character encoding \fIfromcode\fP to
character encoding \fItocode\fP.
.PP
of times. It remains valid until deallocated using \fBiconv_close\fP.
.PP
A conversion descriptor contains a conversion state. After creation using
-\fBiconv_open\fP, the state is in the initial state. Using \fBiconv\fP
+\fBiconv_open\fP(), the state is in the initial state. Using \fBiconv\fP
modifies the descriptor's conversion state. (This implies that a conversion
descriptor can not be used in multiple threads simultaneously.) To bring the
state back to the initial state, use \fBiconv\fP with NULL as \fIinbuf\fP
argument.
.SH "RETURN VALUE"
-The \fBiconv_open\fP function returns a freshly allocated conversion
+The \fBiconv_open\fP() function returns a freshly allocated conversion
descriptor. In case of error, it sets \fBerrno\fP and returns (iconv_t)(\-1).
.SH ERRORS
The following error can occur, among others:
.SH DESCRIPTION
\fBinet_aton()\fP converts the Internet host address \fIcp\fP from the
standard numbers-and-dots notation into binary data and stores it in
-the structure that \fIinp\fP points to. \fBinet_aton\fP returns
+the structure that \fIinp\fP points to. \fBinet_aton\fP() returns
non-zero if the address is valid, zero if not.
.PP
The \fBinet_addr()\fP function converts the Internet host address
\fIcp\fP from numbers-and-dots notation into binary data in network
byte order. If the input is invalid, INADDR_NONE (usually \-1) is returned.
-This is an \fIobsolete\fP interface to \fBinet_aton\fP, described
+This is an \fIobsolete\fP interface to \fBinet_aton\fP(), described
immediately above; it is obsolete because \-1 is a valid address
-(255.255.255.255), and \fBinet_aton\fP provides a cleaner way
+(255.255.255.255), and \fBinet_aton\fP() provides a cleaner way
to indicate error return.
.PP
The \fBinet_network()\fP function extracts the network number in
.B INET6_ADDRSTRLEN
bytes long.
.SH "RETURN VALUE"
-.B inet_ntop
+.BR inet_ntop ()
returns a non-null pointer to
.IR dst .
NULL is returned if there was an error, with
.IR inet_pton ,
which rejects them.
.SH "RETURN VALUE"
-.B inet_pton
+.BR inet_pton ()
returns a negative value and sets
.I errno
to
SVID 3, 4.3BSD
.SH NOTES
The prototype for
-.B initgroups
+.BR initgroups ()
is only available if
.B _BSD_SOURCE
is defined (either explicitly, or implicitly, by not defining
.BI "int iswalnum(wint_t " wc );
.fi
.SH DESCRIPTION
-The \fBiswalnum\fP function is the wide-character equivalent of the
+The \fBiswalnum\fP() function is the wide-character equivalent of the
\fBisalnum\fP function. It tests whether \fIwc\fP is a wide character
belonging to the wide character class "alnum".
.PP
The wide character class "alnum" always contains at least the letters 'A'
to 'Z', 'a' to 'z' and the digits '0' to '9'.
.SH "RETURN VALUE"
-The \fBiswalnum\fP function returns non-zero if \fIwc\fP is a wide character
+The \fBiswalnum\fP() function returns non-zero if \fIwc\fP is a wide character
belonging to the wide character class "alnum". Otherwise it returns zero.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR isalnum (3),
.BR iswctype (3)
.SH NOTES
-The behaviour of \fBiswalnum\fP depends on the LC_CTYPE category of the
+The behaviour of \fBiswalnum\fP() depends on the LC_CTYPE category of the
current locale.
.BI "int iswalpha(wint_t " wc );
.fi
.SH DESCRIPTION
-The \fBiswalpha\fP function is the wide-character equivalent of the
+The \fBiswalpha\fP() function is the wide-character equivalent of the
\fBisalpha\fP function. It tests whether \fIwc\fP is a wide character
belonging to the wide character class "alpha".
.PP
The wide character class "alpha" always contains at least the letters 'A'
to 'Z' and 'a' to 'z'.
.SH "RETURN VALUE"
-The \fBiswalpha\fP function returns non-zero if \fIwc\fP is a wide character
+The \fBiswalpha\fP() function returns non-zero if \fIwc\fP is a wide character
belonging to the wide character class "alpha". Otherwise it returns zero.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR isalpha (3),
.BR iswctype (3)
.SH NOTES
-The behaviour of \fBiswalpha\fP depends on the LC_CTYPE category of the
+The behaviour of \fBiswalpha\fP() depends on the LC_CTYPE category of the
current locale.
.BI "int iswblank(wint_t " wc );
.fi
.SH DESCRIPTION
-The \fBiswblank\fP function is the wide-character equivalent of the
+The \fBiswblank\fP() function is the wide-character equivalent of the
\fBisblank\fP function. It tests whether \fIwc\fP is a wide character
belonging to the wide character class "blank".
.PP
The wide character class "blank" always contains at least the space character
and the control character '\\t'.
.SH "RETURN VALUE"
-The \fBiswblank\fP function returns non-zero if \fIwc\fP is a wide character
+The \fBiswblank\fP() function returns non-zero if \fIwc\fP is a wide character
belonging to the wide character class "blank". Otherwise it returns zero.
.SH "CONFORMING TO"
This function is a GNU extension.
.BR isblank (3),
.BR iswctype (3)
.SH NOTES
-The behaviour of \fBiswblank\fP depends on the LC_CTYPE category of the
+The behaviour of \fBiswblank\fP() depends on the LC_CTYPE category of the
current locale.
.BI "int iswcntrl(wint_t " wc );
.fi
.SH DESCRIPTION
-The \fBiswcntrl\fP function is the wide-character equivalent of the
+The \fBiswcntrl\fP() function is the wide-character equivalent of the
\fBiscntrl\fP function. It tests whether \fIwc\fP is a wide character
belonging to the wide character class "cntrl".
.PP
For an unsigned char \fIc\fP, \fIiscntrl(c)\fP implies \fIiswcntrl(btowc(c))\fP,
but not vice versa.
.SH "RETURN VALUE"
-The \fBiswcntrl\fP function returns non-zero if \fIwc\fP is a wide character
+The \fBiswcntrl\fP() function returns non-zero if \fIwc\fP is a wide character
belonging to the wide character class "cntrl". Otherwise it returns zero.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR iscntrl (3),
.BR iswctype (3)
.SH NOTES
-The behaviour of \fBiswcntrl\fP depends on the LC_CTYPE category of the
+The behaviour of \fBiswcntrl\fP() depends on the LC_CTYPE category of the
current locale.
.SH DESCRIPTION
If \fIwc\fP is a wide character having the character property designated by
\fIdesc\fP (or in other words: belongs to the character class designated by
-\fIdesc\fP), the \fBiswctype\fP function returns non-zero. Otherwise it
+\fIdesc\fP), the \fBiswctype\fP() function returns non-zero. Otherwise it
returns zero. If \fIwc\fP is WEOF, zero is returned.
.PP
\fIdesc\fP must be a character property descriptor returned by the \fBwctype\fP
function.
.SH "RETURN VALUE"
-The \fBiswctype\fP function returns non-zero if the \fIwc\fP has the designated
+The \fBiswctype\fP() function returns non-zero if the \fIwc\fP has the designated
property. Otherwise it returns 0.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR iswxdigit (3),
.BR wctype (3)
.SH NOTES
-The behaviour of \fBiswctype\fP depends on the LC_CTYPE category of the
+The behaviour of \fBiswctype\fP() depends on the LC_CTYPE category of the
current locale.
.BI "int iswdigit(wint_t " wc );
.fi
.SH DESCRIPTION
-The \fBiswdigit\fP function is the wide-character equivalent of the
+The \fBiswdigit\fP() function is the wide-character equivalent of the
\fBisdigit\fP function. It tests whether \fIwc\fP is a wide character
belonging to the wide character class "digit".
.PP
.PP
The wide character class "digit" always contains exactly the digits '0' to '9'.
.SH "RETURN VALUE"
-The \fBiswdigit\fP function returns non-zero if \fIwc\fP is a wide character
+The \fBiswdigit\fP() function returns non-zero if \fIwc\fP is a wide character
belonging to the wide character class "digit". Otherwise it returns zero.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR isdigit (3),
.BR iswctype (3)
.SH NOTES
-The behaviour of \fBiswdigit\fP depends on the LC_CTYPE category of the
+The behaviour of \fBiswdigit\fP() depends on the LC_CTYPE category of the
current locale.
.BI "int iswgraph(wint_t " wc );
.fi
.SH DESCRIPTION
-The \fBiswgraph\fP function is the wide-character equivalent of the
+The \fBiswgraph\fP() function is the wide-character equivalent of the
\fBisgraph\fP function. It tests whether \fIwc\fP is a wide character
belonging to the wide character class "graph".
.PP
wide character class "print" except the space character. It therefore contains
the wide character classes "alnum" and "punct".
.SH "RETURN VALUE"
-The \fBiswgraph\fP function returns non-zero if \fIwc\fP is a wide character
+The \fBiswgraph\fP() function returns non-zero if \fIwc\fP is a wide character
belonging to the wide character class "graph". Otherwise it returns zero.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR isgraph (3),
.BR iswctype (3)
.SH NOTES
-The behaviour of \fBiswgraph\fP depends on the LC_CTYPE category of the
+The behaviour of \fBiswgraph\fP() depends on the LC_CTYPE category of the
current locale.
.BI "int iswlower(wint_t " wc );
.fi
.SH DESCRIPTION
-The \fBiswlower\fP function is the wide-character equivalent of the
+The \fBiswlower\fP() function is the wide-character equivalent of the
\fBislower\fP function. It tests whether \fIwc\fP is a wide character
belonging to the wide character class "lower".
.PP
The wide character class "lower" always contains at least the letters 'a'
to 'z'.
.SH "RETURN VALUE"
-The \fBiswlower\fP function returns non-zero if \fIwc\fP is a wide character
+The \fBiswlower\fP() function returns non-zero if \fIwc\fP is a wide character
belonging to the wide character class "lower". Otherwise it returns zero.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR iswctype (3),
.BR towlower (3)
.SH NOTES
-The behaviour of \fBiswlower\fP depends on the LC_CTYPE category of the
+The behaviour of \fBiswlower\fP() depends on the LC_CTYPE category of the
current locale.
.PP
This function is not very appropriate for dealing with Unicode characters,
.BI "int iswprint(wint_t " wc );
.fi
.SH DESCRIPTION
-The \fBiswprint\fP function is the wide-character equivalent of the
+The \fBiswprint\fP() function is the wide-character equivalent of the
\fBisprint\fP function. It tests whether \fIwc\fP is a wide character
belonging to the wide character class "print".
.PP
.PP
The wide character class "print" contains the wide character class "graph".
.SH "RETURN VALUE"
-The \fBiswprint\fP function returns non-zero if \fIwc\fP is a wide character
+The \fBiswprint\fP() function returns non-zero if \fIwc\fP is a wide character
belonging to the wide character class "print". Otherwise it returns zero.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR isprint (3),
.BR iswctype (3)
.SH NOTES
-The behaviour of \fBiswprint\fP depends on the LC_CTYPE category of the
+The behaviour of \fBiswprint\fP() depends on the LC_CTYPE category of the
current locale.
.BI "int iswpunct(wint_t " wc );
.fi
.SH DESCRIPTION
-The \fBiswpunct\fP function is the wide-character equivalent of the
+The \fBiswpunct\fP() function is the wide-character equivalent of the
\fBispunct\fP function. It tests whether \fIwc\fP is a wide character
belonging to the wide character class "punct".
.PP
"punct" is disjoint from the wide character class "space" and its subclass
"blank".
.SH "RETURN VALUE"
-The \fBiswpunct\fP function returns non-zero if \fIwc\fP is a wide character
+The \fBiswpunct\fP() function returns non-zero if \fIwc\fP is a wide character
belonging to the wide character class "punct". Otherwise it returns zero.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR ispunct (3),
.BR iswctype (3)
.SH NOTES
-The behaviour of \fBiswpunct\fP depends on the LC_CTYPE category of the
+The behaviour of \fBiswpunct\fP() depends on the LC_CTYPE category of the
current locale.
.PP
This function's name is a misnomer when dealing with Unicode characters,
.BI "int iswspace(wint_t " wc );
.fi
.SH DESCRIPTION
-The \fBiswspace\fP function is the wide-character equivalent of the
+The \fBiswspace\fP() function is the wide-character equivalent of the
\fBisspace\fP function. It tests whether \fIwc\fP is a wide character
belonging to the wide character class "space".
.PP
The wide character class "space" always contains at least the space character
and the control characters '\\f', '\\n', '\\r', '\\t', '\\v'.
.SH "RETURN VALUE"
-The \fBiswspace\fP function returns non-zero if \fIwc\fP is a wide character
+The \fBiswspace\fP() function returns non-zero if \fIwc\fP is a wide character
belonging to the wide character class "space". Otherwise it returns zero.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR isspace (3),
.BR iswctype (3)
.SH NOTES
-The behaviour of \fBiswspace\fP depends on the LC_CTYPE category of the
+The behaviour of \fBiswspace\fP() depends on the LC_CTYPE category of the
current locale.
.BI "int iswupper(wint_t " wc );
.fi
.SH DESCRIPTION
-The \fBiswupper\fP function is the wide-character equivalent of the
+The \fBiswupper\fP() function is the wide-character equivalent of the
\fBisupper\fP function. It tests whether \fIwc\fP is a wide character
belonging to the wide character class "upper".
.PP
The wide character class "upper" always contains at least the letters 'A'
to 'Z'.
.SH "RETURN VALUE"
-The \fBiswupper\fP function returns non-zero if \fIwc\fP is a wide character
+The \fBiswupper\fP() function returns non-zero if \fIwc\fP is a wide character
belonging to the wide character class "upper". Otherwise it returns zero.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR iswctype (3),
.BR towupper (3)
.SH NOTES
-The behaviour of \fBiswupper\fP depends on the LC_CTYPE category of the
+The behaviour of \fBiswupper\fP() depends on the LC_CTYPE category of the
current locale.
.PP
This function is not very appropriate for dealing with Unicode characters,
.BI "int iswxdigit(wint_t " wc );
.fi
.SH DESCRIPTION
-The \fBiswxdigit\fP function is the wide-character equivalent of the
+The \fBiswxdigit\fP() function is the wide-character equivalent of the
\fBisxdigit\fP function. It tests whether \fIwc\fP is a wide character
belonging to the wide character class "xdigit".
.PP
The wide character class "xdigit" always contains at least the letters 'A'
to 'F', 'a' to 'f' and the digits '0' to '9'.
.SH "RETURN VALUE"
-The \fBiswxdigit\fP function returns non-zero if \fIwc\fP is a wide character
+The \fBiswxdigit\fP() function returns non-zero if \fIwc\fP is a wide character
belonging to the wide character class "xdigit". Otherwise it returns zero.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR iswctype (3),
.BR isxdigit (3)
.SH NOTES
-The behaviour of \fBiswxdigit\fP depends on the LC_CTYPE category of the
+The behaviour of \fBiswxdigit\fP() depends on the LC_CTYPE category of the
current locale.
On Linux, this call is just an interface for
.BR fcntl (2).
(In general, the relation between
-.B lockf
+.BR lockf ()
and
.B fcntl
is unspecified.)
is zero.
.SH HISTORY
The
-.B logb
+.BR logb ()
function occurs in 4.3BSD.
.\" see IEEE.3 in the 4.3BSD manual
.SH "CONFORMING TO"
.SH "CONFORMING TO"
POSIX
.SH NOTES
-POSIX does not specify whether \fBlongjmp\fP will restore the signal
+POSIX does not specify whether \fBlongjmp\fP() will restore the signal
context. If you want to save and restore signal masks, use
-\fBsiglongjmp\fP.
+\fBsiglongjmp\fP().
.P
\fBlongjmp()\fP and \fBsiglongjmp()\fP make programs hard to
understand and maintain. If possible an alternative should be used.
.BI "int mblen(const char *" s ", size_t " n );
.fi
.SH DESCRIPTION
-If \fIs\fP is not a NULL pointer, the \fBmblen\fP function inspects at most
+If \fIs\fP is not a NULL pointer, the \fBmblen\fP() function inspects at most
\fIn\fP bytes of the multibyte string starting at \fIs\fP and extracts the
next complete multibyte character. It uses a static anonymous shift state only
known to the mblen function. If the multibyte character is not the null wide
the multibyte character is the null wide character, it returns 0.
.PP
If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte
-character, \fBmblen\fP returns \fI-1\fP. This can happen even if
+character, \fBmblen\fP() returns \fI-1\fP. This can happen even if
\fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift
sequences.
.PP
If the multibyte string starting at \fIs\fP contains an invalid multibyte
-sequence before the next complete character, \fBmblen\fP also returns \fI-1\fP.
+sequence before the next complete character, \fBmblen\fP() also returns \fI-1\fP.
.PP
-If \fIs\fP is a NULL pointer, the \fBmblen\fP function
+If \fIs\fP is a NULL pointer, the \fBmblen\fP() function
.\" The Dinkumware doc and the Single Unix specification say this, but
.\" glibc doesn't implement this.
resets the shift state, only known to this function, to the initial state, and
returns non-zero if the encoding has non-trivial shift state, or zero if the
encoding is stateless.
.SH "RETURN VALUE"
-The \fBmblen\fP function returns the number of bytes parsed from the multibyte
+The \fBmblen\fP() function returns the number of bytes parsed from the multibyte
sequence starting at \fIs\fP, if a non-null wide character was recognized.
It returns 0, if a null wide character was recognized. It returns \-1, if an
invalid multibyte sequence was encountered or if it couldn't parse a complete
.SH "SEE ALSO"
.BR mbrlen (3)
.SH NOTES
-The behaviour of \fBmblen\fP depends on the LC_CTYPE category of the
+The behaviour of \fBmblen\fP() depends on the LC_CTYPE category of the
current locale.
.PP
The function \fBmbrlen\fP provides a better interface to the same
.BI "size_t mbrlen(const char *" s ", size_t " n ", mbstate_t *" ps );
.fi
.SH DESCRIPTION
-The \fBmbrlen\fP function inspects at most \fIn\fP bytes of the multibyte
+The \fBmbrlen\fP() function inspects at most \fIn\fP bytes of the multibyte
string starting at \fIs\fP and extracts the next complete multibyte character.
It updates the shift state \fI*ps\fP. If the multibyte character is not the
null wide character, it returns the number of bytes that were consumed from
shift state \fI*ps\fP to the initial state and returns 0.
.PP
If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte
-character, \fBmbrlen\fP returns \fI(size_t)(\-2)\fP. This can happen even if
+character, \fBmbrlen\fP() returns \fI(size_t)(\-2)\fP. This can happen even if
\fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift
sequences.
.PP
If the multibyte string starting at \fIs\fP contains an invalid multibyte
-sequence before the next complete character, \fBmbrlen\fP returns
+sequence before the next complete character, \fBmbrlen\fP() returns
\fI(size_t)(\-1)\fP and sets \fBerrno\fP to \fBEILSEQ\fP. In this case,
the effects on \fI*ps\fP are undefined.
.PP
If \fIps\fP is a NULL pointer, a static anonymous state only known to the
mbrlen function is used instead.
.SH "RETURN VALUE"
-The \fBmbrlen\fP function returns the number of bytes parsed from the multibyte
+The \fBmbrlen\fP() function returns the number of bytes parsed from the multibyte
sequence starting at \fIs\fP, if a non-null wide character was recognized.
It returns 0, if a null wide character was recognized. It returns (size_t)(\-1)
and sets \fBerrno\fP to \fBEILSEQ\fP, if an invalid multibyte sequence was
.SH "SEE ALSO"
.BR mbrtowc (3)
.SH NOTES
-The behaviour of \fBmbrlen\fP depends on the LC_CTYPE category of the
+The behaviour of \fBmbrlen\fP() depends on the LC_CTYPE category of the
current locale.
.fi
.SH DESCRIPTION
The main case for this function is when \fIs\fP is not NULL and \fIpwc\fP is
-not NULL. In this case, the \fBmbrtowc\fP function inspects at most \fIn\fP
+not NULL. In this case, the \fBmbrtowc\fP() function inspects at most \fIn\fP
bytes of the multibyte string starting at \fIs\fP, extracts the next complete
multibyte character, converts it to a wide character and stores it at
\fI*pwc\fP. It updates the shift state \fI*ps\fP. If the converted wide
state \fI*ps\fP to the initial state and returns 0.
.PP
If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte
-character, \fBmbrtowc\fP returns \fI(size_t)(\-2)\fP. This can happen even if
+character, \fBmbrtowc\fP() returns \fI(size_t)(\-2)\fP. This can happen even if
\fIn\fP >= \fIMB_CUR_MAX\fP, if the multibyte string contains redundant shift
sequences.
.PP
If the multibyte string starting at \fIs\fP contains an invalid multibyte
-sequence before the next complete character, \fBmbrtowc\fP returns
+sequence before the next complete character, \fBmbrtowc\fP() returns
\fI(size_t)(\-1)\fP and sets \fBerrno\fP to \fBEILSEQ\fP. In this case,
the effects on \fI*ps\fP are undefined.
.PP
A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL. In this
-case the \fBmbrtowc\fP function behaves as above, excepts that it does not
+case the \fBmbrtowc\fP() function behaves as above, excepts that it does not
store the converted wide character in memory.
.PP
A third case is when \fIs\fP is NULL. In this case, \fIpwc\fP and \fIn\fP are
ignored. If the conversion state represented by \fI*ps\fP denotes an
-incomplete multibyte character conversion, the \fBmbrtowc\fP function
+incomplete multibyte character conversion, the \fBmbrtowc\fP() function
returns \fI(size_t)(\-1)\fP, sets \fBerrno\fP to \fBEILSEQ\fP, and
-leaves \fI*ps\fP in an undefined state. Otherwise, the \fBmbrtowc\fP function
+leaves \fI*ps\fP in an undefined state. Otherwise, the \fBmbrtowc\fP() function
puts \fI*ps\fP in the initial state and returns 0.
.PP
In all of the above cases, if \fIps\fP is a NULL pointer, a static anonymous
memset(&a, 0, sizeof(a));
.RE
.SH "RETURN VALUE"
-The \fBmbrtowc\fP function returns the number of bytes parsed from the
+The \fBmbrtowc\fP() function returns the number of bytes parsed from the
multibyte sequence starting at \fIs\fP, if a non-L'\\0' wide character
was recognized.
It returns 0, if a L'\\0' wide character was recognized.
.SH "SEE ALSO"
.BR mbsrtowcs (3)
.SH NOTES
-The behaviour of \fBmbrtowc\fP depends on the LC_CTYPE category of the
+The behaviour of \fBmbrtowc\fP() depends on the LC_CTYPE category of the
current locale.
mbstate_t state = { 0 };
.fi
.PP
-The function \fBmbsinit\fP tests whether \fI*ps\fP corresponds to an
+The function \fBmbsinit\fP() tests whether \fI*ps\fP corresponds to an
initial state.
.SH "RETURN VALUE"
-\fBmbsinit\fP returns non-zero if \fI*ps\fP is an initial state, or if
+\fBmbsinit\fP() returns non-zero if \fI*ps\fP is an initial state, or if
\fIps\fP is a null pointer. Otherwise it returns 0.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR mbsrtowcs (3),
.BR wcsrtombs (3)
.SH NOTES
-The behaviour of \fBmbsinit\fP depends on the LC_CTYPE category of the
+The behaviour of \fBmbsinit\fP() depends on the LC_CTYPE category of the
current locale.
.BI " size_t " nms ", size_t " len ", mbstate_t *" ps );
.fi
.SH DESCRIPTION
-The \fBmbsnrtowcs\fP function is like the \fBmbsrtowcs\fP function, except that
+The \fBmbsnrtowcs\fP() function is like the \fBmbsrtowcs\fP function, except that
the number of bytes to be converted, starting at \fI*src\fP, is limited to
\fInms\fP.
.PP
-If \fIdest\fP is not a NULL pointer, the \fBmbsnrtowcs\fP function converts at
+If \fIdest\fP is not a NULL pointer, the \fBmbsnrtowcs\fP() function converts at
most \fInms\fP bytes from the
multibyte string \fI*src\fP to a wide-character string starting at \fIdest\fP.
At most \fIlen\fP wide characters are written to \fIdest\fP. The shift state
The programmer must ensure that there is room for at least \fIlen\fP wide
characters at \fIdest\fP.
.SH "RETURN VALUE"
-The \fBmbsnrtowcs\fP function returns the number of wide characters that make
+The \fBmbsnrtowcs\fP() function returns the number of wide characters that make
up the converted part of the wide character string, not including the
terminating null wide character. If an invalid multibyte sequence was
encountered, (size_t)(\-1) is returned, and \fBerrno\fP set to \fBEILSEQ\fP.
.BR iconv (3),
.BR mbsrtowcs (3)
.SH NOTES
-The behaviour of \fBmbsnrtowcs\fP depends on the LC_CTYPE category of the
+The behaviour of \fBmbsnrtowcs\fP() depends on the LC_CTYPE category of the
current locale.
.PP
Passing NULL as \fIps\fP is not multi-thread safe.
.BI " size_t " len ", mbstate_t *" ps );
.fi
.SH DESCRIPTION
-If \fIdest\fP is not a NULL pointer, the \fBmbsrtowcs\fP function converts the
+If \fIdest\fP is not a NULL pointer, the \fBmbsrtowcs\fP() function converts the
multibyte string \fI*src\fP to a wide-character string starting at \fIdest\fP.
At most \fIlen\fP wide characters are written to \fIdest\fP. The shift state
\fI*ps\fP is updated. The conversion is effectively performed by repeatedly
The programmer must ensure that there is room for at least \fIlen\fP wide
characters at \fIdest\fP.
.SH "RETURN VALUE"
-The \fBmbsrtowcs\fP function returns the number of wide characters that make
+The \fBmbsrtowcs\fP() function returns the number of wide characters that make
up the converted part of the wide character string, not including the
terminating null wide character. If an invalid multibyte sequence was
encountered, (size_t)(\-1) is returned, and \fBerrno\fP set to \fBEILSEQ\fP.
.BR mbsnrtowcs (3),
.BR mbstowcs (3)
.SH NOTES
-The behaviour of \fBmbsrtowcs\fP depends on the LC_CTYPE category of the
+The behaviour of \fBmbsrtowcs\fP() depends on the LC_CTYPE category of the
current locale.
.PP
Passing NULL as \fIps\fP is not multi-thread safe.
.BI "size_t mbstowcs(wchar_t *" dest ", const char *" src ", size_t " n );
.fi
.SH DESCRIPTION
-If \fIdest\fP is not a NULL pointer, the \fBmbstowcs\fP function converts the
+If \fIdest\fP is not a NULL pointer, the \fBmbstowcs\fP() function converts the
multibyte string \fIsrc\fP to a wide-character string starting at \fIdest\fP.
At most \fIn\fP wide characters are written to \fIdest\fP. The conversion starts
in the initial state. The conversion can stop for three reasons:
In order to avoid the case 2 above, the programmer should make sure \fIn\fP is
greater or equal to \fImbstowcs(NULL,src,0)+1\fP.
.SH "RETURN VALUE"
-The \fBmbstowcs\fP function returns the number of wide characters that make
+The \fBmbstowcs\fP() function returns the number of wide characters that make
up the converted part of the wide character string, not including the
terminating null wide character. If an invalid multibyte sequence was
encountered, (size_t)(\-1) is returned.
.SH "SEE ALSO"
.BR mbsrtowcs (3)
.SH NOTES
-The behaviour of \fBmbstowcs\fP depends on the LC_CTYPE category of the
+The behaviour of \fBmbstowcs\fP() depends on the LC_CTYPE category of the
current locale.
.PP
The function \fBmbsrtowcs\fP provides a better interface to the same
.fi
.SH DESCRIPTION
The main case for this function is when \fIs\fP is not NULL and \fIpwc\fP is
-not NULL. In this case, the \fBmbtowc\fP function inspects at most \fIn\fP
+not NULL. In this case, the \fBmbtowc\fP() function inspects at most \fIn\fP
bytes of the multibyte string starting at \fIs\fP, extracts the next complete
multibyte character, converts it to a wide character and stores it at
\fI*pwc\fP. It updates an internal shift state only known to the mbtowc
of bytes that were consumed from \fIs\fP, otherwise it returns 0.
.PP
If the \fIn\fP bytes starting at \fIs\fP do not contain a complete multibyte
-character, or if they contain an invalid multibyte sequence, \fBmbtowc\fP
+character, or if they contain an invalid multibyte sequence, \fBmbtowc\fP()
returns \fI-1\fP. This can happen even if \fIn\fP >= \fIMB_CUR_MAX\fP,
if the multibyte string contains redundant shift sequences.
.PP
A different case is when \fIs\fP is not NULL but \fIpwc\fP is NULL. In this
-case the \fBmbtowc\fP function behaves as above, excepts that it does not
+case the \fBmbtowc\fP() function behaves as above, excepts that it does not
store the converted wide character in memory.
.PP
A third case is when \fIs\fP is NULL. In this case, \fIpwc\fP and \fIn\fP are
-ignored. The \fBmbtowc\fP function
+ignored. The \fBmbtowc\fP() function
.\" The Dinkumware doc and the Single Unix specification say this, but
.\" glibc doesn't implement this.
resets the shift state, only known to this function, to the initial state, and
returns non-zero if the encoding has non-trivial shift state, or zero if the
encoding is stateless.
.SH "RETURN VALUE"
-If \fIs\fP is not NULL, the \fBmbtowc\fP function returns the number of
+If \fIs\fP is not NULL, the \fBmbtowc\fP() function returns the number of
consumed bytes starting at \fIs\fP, or 0 if \fIs\fP points to a null byte,
or \-1 upon failure.
.PP
-If \fIs\fP is NULL, the \fBmbtowc\fP function returns non-zero if the encoding
+If \fIs\fP is NULL, the \fBmbtowc\fP() function returns non-zero if the encoding
has non-trivial shift state, or zero if the encoding is stateless.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR mbrtowc (3),
.BR mbstowcs (3)
.SH NOTES
-The behaviour of \fBmbtowc\fP depends on the LC_CTYPE category of the
+The behaviour of \fBmbtowc\fP() depends on the LC_CTYPE category of the
current locale.
.PP
This function is not multi-thread safe. The function \fBmbrtowc\fP provides
.BI "int mkfifo(const char *" pathname ", mode_t " mode );
.fi
.SH DESCRIPTION
-\fBmkfifo\fP makes a FIFO special file with name \fIpathname\fP.
+\fBmkfifo\fP() makes a FIFO special file with name \fIpathname\fP.
\fImode\fP specifies the FIFO's permissions. It is modified by the
process's \fBumask\fP in the usual way: the permissions of the created
file are \fB(\fP\fImode\fP\fB & ~umask)\fP.
A FIFO special file is similar to a pipe, except that it is created
in a different way. Instead of being an anonymous communications
channel, a FIFO special file is entered into the file system by
-calling \fBmkfifo\fP.
+calling \fBmkfifo\fP().
.PP
Once you have created a FIFO special file in this way, any process can
open it for reading or writing, in the same way as an ordinary file.
.I template
must not be a string constant, but should be declared as a character array.
The file is opened with the O_EXCL flag, guaranteeing that when
-.B mkstemp
+.BR mkstemp ()
returns successfully we are the only user.
.SH "RETURN VALUE"
On success, the \fBmkstemp()\fP function returns the file descriptor
More generally, the POSIX specification does not say anything
about file modes, so the application should make sure its umask
is set appropriately before calling
-.BR mkstemp .
+.BR mkstemp ().
.SH "CONFORMING TO"
4.3BSD, POSIX 1003.1-2001
.SH NOTE
.BI "char *nl_langinfo(nl_item " item );
.fi
.SH DESCRIPTION
-The \fBnl_langinfo\fP function provides access to locale information
+The \fBnl_langinfo\fP() function provides access to locale information
in a more flexible way than
.BR localeconv (3)
does. Individual and additional elements of the locale categories can
.IR "The GNU C Library Reference Manual" .
.SH "RETURN VALUE"
If no locale has been selected for the appropriate category,
-\fBnl_langinfo\fP returns a pointer to the corresponding string in the
+\fBnl_langinfo\fP() returns a pointer to the corresponding string in the
"C" locale.
.PP
If \fIitem\fP is not valid, a pointer to an empty string is returned.
.PP
This pointer may point to static data that may be overwritten on the
-next call to \fBnl_langinfo\fP or \fBsetlocale\fP.
+next call to \fBnl_langinfo\fP() or \fBsetlocale\fP.
.SH "CONFORMING TO"
The Single UNIX\*R Specification, Version 2
.SH "SEE ALSO"
this call may well change this variable, even though it succeeds,
for example because it internally used some other library function that failed.
Thus, if a failing call is not immediately followed by a call to
-.BR perror ,
+.BR perror (),
the value of
.I errno
should be saved.
unless this is altered by the command itself. Conversely, reading from a
``popened'' stream reads the command's standard output, and the command's
standard input is the same as that of the process that called
-.BR popen .
+.BR popen ().
.PP
Note that output
-.B popen
+.BR popen ()
streams are fully buffered by default.
.PP
The
-.B pclose
+.BR pclose ()
function waits for the associated process to terminate and returns the exit
status of the command as returned by
.BR wait4 .
.SH "RETURN VALUE"
The
-.B popen
+.BR popen ()
function returns
.B NULL
if the
calls fail, or if it cannot allocate memory.
.PP
The
-.B pclose
+.BR pclose ()
function returns \-1 if
.\" These conditions actually give undefined results, so I commented
.\" them out.
returns an error, or some other error is detected.
.SH ERRORS
The
-.B popen
+.BR popen ()
function does not set
.I errno
if memory allocation fails. If the underlying
process. The latter can be avoided by calling
.BR fflush (3)
before
-.BR popen .
+.BR popen ().
.PP
Failure to execute the shell is indistinguishable from the shell's failure
to execute command, or an immediate exit of the command. The only hint is
.BI "int vsnprintf(char *" str ", size_t " size ", const char *" format ", va_list " ap );
.SH DESCRIPTION
The functions in the
-.B printf
+.BR printf ()
family produce output according to a
.I format
as described below. The functions
-.B printf
+.BR printf ()
and
-.B vprintf
+.BR vprintf ()
write output to
.IR stdout ,
the standard output stream;
-.B fprintf
+.BR fprintf ()
and
-.B vfprintf
+.BR vfprintf ()
write output to the given output
.IR stream ;
-.BR sprintf ,
-.BR snprintf ,
-.B vsprintf
+.BR sprintf (),
+.BR snprintf (),
+.BR vsprintf ()
and
-.B vsnprintf
+.BR vsnprintf ()
write to the character string
.IR str .
.PP
The functions
-.BR vprintf ,
-.BR vfprintf ,
-.BR vsprintf ,
-.B vsnprintf
+.BR vprintf (),
+.BR vfprintf (),
+.BR vsprintf (),
+.BR vsnprintf ()
are equivalent to the functions
-.BR printf ,
-.BR fprintf ,
-.BR sprintf ,
-.BR snprintf ,
+.BR printf (),
+.BR fprintf (),
+.BR sprintf (),
+.BR snprintf (),
respectively, except that they are called with a va_list instead
of a variable number of arguments. These functions do not call the
.I va_end
.SH NOTES
The glibc implementation of the functions
-.B snprintf
+.BR snprintf ()
and
-.B vsnprintf
+.BR vsnprintf ()
conforms to the C99 standard, i.e., behaves as described above,
since glibc version 2.1. Until glibc 2.0.6 they would return \-1
when the output was truncated.
.SH "CONFORMING TO"
The
-.BR fprintf ,
-.BR printf ,
-.BR sprintf ,
-.BR vprintf ,
-.BR vfprintf ,
+.BR fprintf (),
+.BR printf (),
+.BR sprintf (),
+.BR vprintf (),
+.BR vfprintf (),
and
-.B vsprintf
+.BR vsprintf ()
functions conform to ANSI X3.159-1989 (``ANSI C'') and ISO/IEC 9899:1999
(``ISO C99'').
The
-.B snprintf
+.BR snprintf ()
and
-.B vsnprintf
+.BR vsnprintf ()
functions conform to ISO/IEC 9899:1999.
.PP
Concerning the return value of
-.BR snprintf ,
+.BR snprintf (),
the SUSv2 and the C99 standard contradict each other: when
-.B snprintf
+.BR snprintf ()
is called with
.IR size =0
then SUSv2 stipulates an unspecified return value less than 1,
flag character I.
.SH HISTORY
Unix V7 defines the three routines
-.BR printf ,
-.BR fprintf ,
-.BR sprintf ,
+.BR printf (),
+.BR fprintf (),
+.BR sprintf (),
and has the flag \-, the width or precision *, the length modifier l,
and the conversions doxfegcsu, and also D,O,U,X as synonyms for ld,lo,lu,lx.
This is still true for 2.9.1BSD, but 2.10BSD has the flags
#, + and <space> and no longer mentions D,O,U,X.
2.11BSD has
-.BR vprintf ,
-.BR vfprintf ,
-.BR vsprintf ,
+.BR vprintf (),
+.BR vfprintf (),
+.BR vsprintf (),
and warns not to use D,O,U,X.
4.3BSD Reno has the flag 0, the length modifiers h and L,
and the conversions n, p, E, G, X (with current meaning)
and deprecates D,O,U.
4.4BSD introduces the functions
-.B snprintf
+.BR snprintf ()
and
-.BR vsnprintf ,
+.BR vsnprintf (),
and the length modifier q.
FreeBSD also has functions
.I asprintf
and
.IR vasprintf ,
that allocate a buffer large enough for
-.BR sprintf .
+.BR sprintf ().
In glibc there are functions
.I dprintf
and
that print to a file descriptor instead of a stream.
.SH BUGS
Because
-.B sprintf
+.BR sprintf ()
and
-.B vsprintf
+.BR vsprintf ()
assume an arbitrarily long string, callers must be careful not to overflow
the actual space; this is often impossible to assure. Note that the length
of the strings produced is locale-dependent and difficult to predict.
Use
-.B snprintf
+.BR snprintf ()
and
-.B vsnprintf
+.BR vsnprintf ()
instead (or
.B asprintf
and
.BR vasprintf ).
.PP
Linux libc4.[45] does not have a
-.BR snprintf ,
+.BR snprintf (),
but provides a libbsd that contains an
-.B snprintf
+.BR snprintf ()
equivalent to
-.BR sprintf ,
+.BR sprintf (),
i.e., one that ignores the
.I size
argument.
Thus, the use of
-.B snprintf
+.BR snprintf ()
with early libc4 leads to serious security problems.
.PP
Code such as
may contain a % character. If
.I foo
comes from untrusted user input, it may contain %n, causing the
-.B printf
+.BR printf ()
call to write to memory and creating a security hole.
.\" .PP
.\" Some floating point conversions under early libc4
.SH "RETURN VALUE"
Zero is always returned.
.SH BUGS
-.B profil
+.BR profil ()
cannot be used on a program that also uses
.B ITIMER_PROF
itimers.
.BI "wint_t putwchar(wchar_t " wc );
.fi
.SH DESCRIPTION
-The \fBputwchar\fP function is the wide-character equivalent of the
+The \fBputwchar\fP() function is the wide-character equivalent of the
\fBputchar\fP function. It writes the wide character \fIwc\fP to \fBstdout\fP.
If \fIferror(stdout)\fP becomes true, it returns WEOF. If a wide character
conversion error occurs, it sets \fBerrno\fP to \fBEILSEQ\fP and returns WEOF.
For a non-locking counterpart, see
.BR unlocked_stdio (3).
.SH "RETURN VALUE"
-The \fBputwchar\fP function returns \fIwc\fP if no error occurred, or WEOF to
+The \fBputwchar\fP() function returns \fIwc\fP if no error occurred, or WEOF to
indicate an error.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH NOTES
-The behaviour of \fBputwchar\fP depends on the LC_CTYPE category of the
+The behaviour of \fBputwchar\fP() depends on the LC_CTYPE category of the
current locale.
.PP
-It is reasonable to expect that \fBputwchar\fP will actually write
+It is reasonable to expect that \fBputwchar\fP() will actually write
the multibyte sequence corresponding to the wide character \fIwc\fP.
.SH "SEE ALSO"
.BR fputwc (3),
.BI "char *qgcvt(long double " number ", int " ndigit ", char *" buf );
.SH DESCRIPTION
The functions
-.BR qecvt ,
-.BR qfcvt
+.BR qecvt (),
+.BR qfcvt ()
and
-.BR qgcvt
+.BR qgcvt ()
are identical to
.BR ecvt ,
.BR fcvt
.br
.BI "int re_exec(char *" string );
.SH DESCRIPTION
-.B re_comp
+.BR re_comp ()
is used to compile the null-terminated regular expression pointed to by
.IR regex .
The compiled pattern occupies a static area, the pattern buffer,
which is overwritten by subsequent use of
-.BR re_comp .
+.BR re_comp ().
If
.I regex
is
no operation is performed and the pattern buffer's contents are not
altered.
-.B re_exec
+.BR re_exec ()
is used to assess whether the null-terminated string pointed to by
.I string
matches the previously compiled
.IR regex .
.SH "RETURN VALUE"
-.B re_comp
+.BR re_comp ()
returns
.B NULL
on successful compilation of
.I regex
otherwise it returns a pointer to an appropriate error message.
-.B re_exec
+.BR re_exec ()
returns 1 for a successful match, zero for failure.
.SH "CONFORMING TO"
4.3BSD
.xx \w'\fBvoid\ regfree(\fR'
.BI "void\ regfree(regex_t *" preg );
.SH "POSIX REGEX COMPILING"
-.B regcomp
+.BR regcomp ()
is used to compile a regular expression into a form that is suitable
for subsequent
-.B regexec
+.BR regexec ()
searches.
-.B regcomp
+.BR regcomp ()
is supplied with
.IR preg ,
a pointer to a pattern buffer storage area;
All regular expression searching must be done via a compiled pattern
buffer, thus
-.B regexec
+.BR regexec ()
must always be supplied with the address of a
-.B regcomp
+.BR regcomp ()
initialized pattern buffer.
.I cflags
.TP
.B REG_ICASE
Do not differentiate case. Subsequent
-.B regexec
+.BR regexec ()
searches using this pattern buffer will be case insensitive.
.TP
.B REG_NOSUB
and
.I pmatch
parameters to
-.B regexec
+.BR regexec ()
are ignored if the pattern buffer supplied was compiled with this flag set.
.TP
.B REG_NEWLINE
whether
.IR eflags ,
the execution flags of
-.BR regexec ,
+.BR regexec (),
contains
.BR REG_NOTBOL .
contains
.BR REG_NOTEOL .
.SH "POSIX REGEX MATCHING"
-.B regexec
+.BR regexec ()
is used to match a null-terminated string
against the precompiled pattern buffer,
.IR preg .
.B REG_NEWLINE
above)
This flag may be used when different portions of a string are passed to
-.B regexec
+.BR regexec ()
and the beginning of the string should not be interpreted as the
beginning of the line.
.TP
.I nmatch
elements.
These are filled in by
-.BR regexec
+.BR regexec ()
with substring match addresses. Any unused structure elements
will contain the value \-1.
.I rm_eo
element indicates the end offset of the match.
.SH "POSIX ERROR REPORTING"
-.B regerror
+.BR regerror ()
is used to turn the error codes that can be returned by both
-.B regcomp
+.BR regcomp ()
and
-.B regexec
+.BR regexec ()
into error message strings.
-.B regerror
+.BR regerror ()
is passed the error code,
.IR errcode ,
the pattern buffer,
characters of the error message and a terminating null.
.SH "POSIX PATTERN BUFFER FREEING"
Supplying
-.B regfree
+.BR regfree ()
with a precompiled pattern buffer,
.I preg
will free the memory allocated to the pattern buffer by the compiling
process,
-.BR regcomp .
+.BR regcomp ().
.SH "RETURN VALUE"
-.B regcomp
+.BR regcomp ()
returns zero for a successful compilation or an error code for failure.
-.B regexec
+.BR regexec ()
returns zero for a successful match or
.B REG_NOMATCH
for failure.
.SH ERRORS
The following errors can be returned by
-.BR regcomp :
+.BR regcomp ():
.TP
.B REG_BADBR
Invalid use of back reference operator.
.sp
.BI "int remove(const char *" pathname );
.SH DESCRIPTION
-.B remove
+.BR remove ()
deletes a name from the filesystem.
It calls
.I unlink
disappearance of files which are still being used.
.SH NOTE
Under libc4 and libc5,
-.B remove
+.BR remove ()
was an alias for unlink (and hence would not remove directories).
.SH "SEE ALSO"
.BR rm (1),
Link with \-lm.
.SH DESCRIPTION
The
-.B nearbyint
+.BR nearbyint ()
functions round their argument to an integer value in floating point
format, using the current rounding direction and without raising the
.I inexact
exception.
.LP
The
-.B rint
+.BR rint ()
functions do the same, but will raise the
.I inexact
exception when the result differs in value from the argument.
.ad
.SH DESCRIPTION
The
-.B scanf
+.BR scanf ()
family of functions scans input according to
.I format
as described below. This format may contain
arguments are evaluated, but are otherwise ignored.
The
-.B scanf
+.BR scanf ()
function reads input from the standard input stream
.IR stdin ,
-.B fscanf
+.BR fscanf ()
reads input from the stream pointer
.IR stream ,
and
-.B sscanf
+.BR sscanf ()
reads its input from the character string pointed to by
.IR str .
.PP
The
-.B vfscanf
+.BR vfscanf ()
function is analogous to
.BR vfprintf (3)
and reads input from the stream pointer
using a variable argument list of pointers (see
.BR stdarg (3).
The
-.B vscanf
+.BR vscanf ()
function scans a variable argument list from the standard input and the
-.B vsscanf
+.BR vsscanf ()
function scans it from a string; these are analogous to the
.B vprintf
and
.IR directives
which describe how to process the sequence of input characters.
If processing of a directive fails, no further input is read, and
-.B scanf
+.BR scanf ()
returns.
A "failure" can be either of the following:
.IR "input failure" ,
.TP
\(bu
An optional '*' assignment-suppression character:
-.B scanf
+.BR scanf ()
reads input as directed by the conversion specification,
but discards the input.
No corresponding
.I pointer
argument is required, and this specification is not
included in the count of successful assignments returned by
-.BR scanf .
+.BR scanf ().
.TP
\(bu
An optional 'a' character.
This is used with string conversions, and relieves the caller of the
need to allocate a corresponding buffer to hold the input: instead,
-.B scanf
+.BR scanf ()
allocates a buffer of sufficient size,
and assigns the address of this buffer to the corresponding
.I pointer
.BR strtoul (3)
.SH "CONFORMING TO"
The functions
-.BR fscanf ,
-.BR scanf ,
+.BR fscanf (),
+.BR scanf (),
and
-.BR sscanf
+.BR sscanf ()
conform to ANSI X3.159-1989 (``ANSI C'').
.PP
The
is always unbuffered by default.
.PP
The
-.B setvbuf
+.BR setvbuf ()
function may be used on any open stream to change its buffer.
The
.I mode
.BR NULL ,
only the mode is affected; a new buffer will be allocated on the next read
or write operation. The
-.B setvbuf
+.BR setvbuf ()
function may only be used after opening a stream and before any other
operations have been performed on it.
.PP
The other three calls are, in effect, simply aliases for calls to
-.BR setvbuf .
+.BR setvbuf ().
The
-.B setbuf
+.BR setbuf ()
function is exactly equivalent to the call
.PP
.RS
.RE
.PP
The
-.B setbuffer
+.BR setbuffer ()
function is the same, except that the size of the buffer is up to the
caller, rather than being determined by the default
.BR BUFSIZ .
The
-.B setlinebuf
+.BR setlinebuf ()
function is exactly equivalent to the call:
.PP
.RS
.RE
.SH "RETURN VALUE"
The function
-.B setvbuf
+.BR setvbuf ()
returns 0 on success.
It can return any value on failure, but returns non-zero when
.I mode
The other functions are void.
.SH "CONFORMING TO"
The
-.B setbuf
+.BR setbuf ()
and
-.B setvbuf
+.BR setvbuf ()
functions conform to ANSI X3.159-1989 (``ANSI C'').
.SH BUGS
The
-.B setbuffer
+.BR setbuffer ()
and
-.B setlinebuf
+.BR setlinebuf ()
functions are not portable to versions of BSD before 4.2BSD, and
are available under Linux since libc 4.5.21. On 4.2BSD and 4.3BSD systems,
-.B setbuf
+.BR setbuf ()
always uses a suboptimal buffer size and should be avoided.
.P
You must make sure that both
.SH "CONFORMING TO"
POSIX, ISO 9899 (C99)
.SH NOTES
-POSIX does not specify whether \fBsetjmp\fP will save the
+POSIX does not specify whether \fBsetjmp\fP() will save the
signal context. (In SYSV it will not. In 4.3BSD will, and there
is a function \fB_setjmp\fP that will not.)
-If you want to save signal masks, use \fBsigsetjmp\fP.
+If you want to save signal masks, use \fBsigsetjmp\fP().
.P
-\fBsetjmp()\fP and \fBsigsetjmp\fP make programs hard to understand
+\fBsetjmp()\fP and \fBsigsetjmp\fP() make programs hard to understand
and maintain. If possible an alternative should be used.
.SH "SEE ALSO"
.BR longjmp (3),
.IR category .
Such a string is either a well-known constant like "C" or "da_DK"
(see below), or an opaque string that was returned by another call of
-.BR setlocale .
+.BR setlocale ().
.PP
If
.I locale
The first existing environment variable is used.
If its value is not a valid locale specification, the locale
is unchanged, and
-.B setlocale
+.BR setlocale ()
returns NULL.
.\" The environment variable LANGUAGE may contain several, colon-separated,
.\" locale names.
.BR sigsetops (3)
functions allow the manipulation of POSIX signal sets.
.PP
-.B sigemptyset
+.BR sigemptyset ()
initializes the signal set given by
.I set
to empty, with all signals excluded from the set.
.PP
-.B sigfillset
+.BR sigfillset ()
initializes
.I set
to full, including all signals.
.PP
-.B sigaddset
+.BR sigaddset ()
and
-.B sigdelset
+.BR sigdelset ()
add and delete respectively signal
.I signum
from
.IR set .
.PP
-.B sigismember
+.BR sigismember ()
tests whether
.I signum
is a member of
.SH "RETURN VALUE"
.BR sigemptyset ", " sigfillset ", " sigaddset
and
-.B sigdelset
+.BR sigdelset ()
return 0 on success and \-1 on error.
.PP
-.B sigismember
+.BR sigismember ()
returns 1 if
.I signum
is a member of
The called function must declare an object of type
.B va_list
which is used by the macros
-.BR va_start ,
-.BR va_arg ,
+.BR va_start (),
+.BR va_arg (),
and
-.BR va_end .
+.BR va_end ().
.SS va_start
The
-.B va_start
+.BR va_start ()
macro initializes
.I ap
for subsequent use by
-.B va_arg
+.BR va_arg ()
and
-.BR va_end ,
+.BR va_end (),
and must be called first.
.PP
The parameter
the last parameter of which the calling function knows the type.
.PP
Because the address of this parameter may be used in the
-.B va_start
+.BR va_start ()
macro, it should not be declared as a register variable,
or as a function or an array type.
.SS va_arg
The
-.B va_arg
+.BR va_arg ()
macro expands to an expression that has the type and value of the next
argument in the call. The parameter
.I ap
.B va_list
.I ap
initialized by
-.BR va_start .
+.BR va_start ().
Each call to
-.B va_arg
+.BR va_arg ()
modifies
.I ap
so that the next call returns the next argument. The parameter
.IR type .
.PP
The first use of the
-.B va_arg
+.BR va_arg ()
macro after that of the
-.B va_start
+.BR va_start ()
macro returns the argument after
.IR last .
Successive invocations return the values of the remaining arguments.
is undefined after the return of that function.
.SS va_end
Each invocation of
-.B va_start
+.BR va_start ()
must be matched by a corresponding invocation of
-.B va_end
+.BR va_end ()
in the same function. After the call
.BI va_end( ap )
the variable
.I ap
is undefined. Multiple transversals of the list, each
bracketed by
-.B va_start
+.BR va_start ()
and
-.B va_end
+.BR va_end ()
are possible.
-.B va_end
+.BR va_end ()
may be a macro or a function.
.SS va_copy
.\" Proposal from clive@demon.net, 1997-02-28
.RE
Finally, on systems where parameters are passed in registers,
it may be necessary for
-.B va_start
+.BR va_start ()
to allocate memory, store the parameters there, and also
an indication of which parameter is next, so that
-.B va_arg
+.BR va_arg ()
can step through the list. Now
-.B va_end
+.BR va_end ()
can free the allocated memory again.
To accommodate this situation, C99 adds a macro
-.BR va_copy ,
+.BR va_copy (),
so that the above assignment can be replaced by
.RS
.nf
.fi
.RE
Each invocation of
-.B va_copy
+.BR va_copy ()
must be matched by a corresponding invocation of
-.B va_end
+.BR va_end ()
in the same function.
Some systems that do not supply
-.B va_copy
+.BR va_copy ()
have
.B __va_copy
instead, since that was the name used in the draft proposal.
.RE
.SH "CONFORMING TO"
The
-.BR va_start ,
-.BR va_arg ,
+.BR va_start (),
+.BR va_arg (),
and
-.B va_end
+.BR va_end ()
macros conform to ANSI X3.159-1989 (``C89'').
C99 defines the
-.B va_copy
+.BR va_copy ()
macro.
.SH COMPATIBILITY
These macros are
\fIdest\fP (that is, the address of the terminating null character)
rather than the beginning.
.SH EXAMPLE
-For example, this program uses \fBstpcpy\fP to concatenate \fBfoo\fP and
+For example, this program uses \fBstpcpy\fP() to concatenate \fBfoo\fP and
\fBbar\fP to produce \fBfoobar\fP, which it then prints.
.nf
.BI "char *stpncpy(char *" dest ", const char *" src ", size_t " n );
.fi
.SH DESCRIPTION
-The \fBstpncpy\fP function copies at most \fIn\fP characters from the string
+The \fBstpncpy\fP() function copies at most \fIn\fP characters from the string
pointed to by \fIsrc\fP, including the terminating '\\0' character, to the
array pointed to by \fIdest\fP. Exactly \fIn\fP characters are written at
\fIdest\fP. If the length \fIstrlen(src)\fP is smaller than \fIn\fP, the
The programmer must ensure that there is room for at least \fIn\fP characters
at \fIdest\fP.
.SH "RETURN VALUE"
-\fBstpncpy\fP returns a pointer to the terminating null
+\fBstpncpy\fP() returns a pointer to the terminating null
in \fIdest\fP, or, if \fIdest\fP is not null-terminated,
\fIdest + n\fP.
.SH "CONFORMING TO"
\fIn\fP characters. If \fIs\fP is longer than \fIn\fP, only \fIn\fP
characters are copied, and a terminating NUL is added.
-\fBstrdupa\fP and \fBstrndupa\fP are similar, but use \fBalloca(3)\fP
+\fBstrdupa\fP() and \fBstrndupa\fP() are similar, but use \fBalloca(3)\fP
to allocate the buffer. They are only available when using the GNU
GCC suite, and suffer from the same limitations described in \fBalloca(3)\fP.
POSIX.1 only refers to ANSI C; POSIX.2 describes under
.BR date (1)
several extensions that could apply to
-.B strftime
+.BR strftime ()
as well.
The %F conversion is in C99 and POSIX 1003.1-2001.
.BI "size_t strnlen(const char *" s ", size_t " maxlen );
.fi
.SH DESCRIPTION
-The \fBstrnlen\fP function returns the number of characters in the string
+The \fBstrnlen\fP() function returns the number of characters in the string
pointed to by \fIs\fP, not including the terminating '\\0' character, but
-at most \fImaxlen\fP. In doing this, \fBstrnlen\fP looks only at the first
+at most \fImaxlen\fP. In doing this, \fBstrnlen\fP() looks only at the first
\fImaxlen\fP characters at \fIs\fP and never beyond \fIs+maxlen\fP.
.SH "RETURN VALUE"
-The \fBstrnlen\fP function returns \fIstrlen(s)\fP, if that is less than
+The \fBstrnlen\fP() function returns \fIstrlen(s)\fP, if that is less than
\fImaxlen\fP, or \fImaxlen\fP if there is no '\\0' character among the first
\fImaxlen\fP characters pointed to by \fIs\fP.
.SH "CONFORMING TO"
.fi
.SH "GNU EXTENSIONS"
For reasons of symmetry, glibc tries to support for
-.B strptime
+.BR strptime ()
the same format characters as for
.BR strftime .
(In most cases the corresponding fields are parsed, but no field in \fItm\fP
.BI "long double strtold(const char *" nptr ", char **" endptr );
.SH DESCRIPTION
The
-.BR strtod ,
-.BR strtof ,
+.BR strtod (),
+.BR strtof (),
and
-.B strtold
+.BR strtold ()
functions convert the initial portion of the string pointed to by
.I nptr
to
Overflow or underflow occurred.
.SH "CONFORMING TO"
ANSI C describes
-.BR strtod ,
+.BR strtod (),
C99
describes the other two functions.
.SH "SEE ALSO"
which is implemented using
.BR versionsort (3),
which again uses
-.BR strverscmp .
+.BR strverscmp ().
Thus, the task of
-.B strverscmp
+.BR strverscmp ()
is to compare two strings and find the "right" order, while
.B strcmp
only finds the lexicographic order. This function does not use
in most versions of Unix.
.SH HISTORY
A
-.B syslog
+.BR syslog ()
function call appeared in 4.2BSD.
4.3BSD documents
.IR openlog (),
The input and output baud rates are stored in the \fBtermios\fP
structure.
.LP
-\fBcfmakeraw\fP sets the terminal attributes as follows:
+\fBcfmakeraw\fP() sets the terminal attributes as follows:
.nf
termios_p->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
|INLCR|IGNCR|ICRNL|IXON);
two constants EXTA, EXTB ("External A" and "External B").
Many systems extend the list with much higher baud rates.
.LP
-The effect of a non-zero \fIduration\fP with \fBtcsendbreak\fP varies.
+The effect of a non-zero \fIduration\fP with \fBtcsendbreak\fP() varies.
SunOS specifies a break of
.IB duration * N
seconds, where \fIN\fP is at least 0.25, and not more than 0.5.
FreeBSD and NetBSD and HP-UX and MacOS ignore the value of
.IR duration .
Under Solaris and Unixware,
-.B tcsendbreak
+.BR tcsendbreak ()
with non-zero
.I duration
behaves like
-.BR tcdrain .
+.BR tcdrain ().
.\" libc4 until 4.7.5, glibc for sysv: EINVAL for duration > 0.
.\" libc4.7.6, libc5, glibc for unix: duration in ms.
.\" glibc for bsd: duration in us
.BI "wint_t towctrans(wint_t " wc ", wctrans_t " desc );
.fi
.SH DESCRIPTION
-If \fIwc\fP is a wide character, the \fBtowctrans\fP function translates it
+If \fIwc\fP is a wide character, the \fBtowctrans\fP() function translates it
according to the transliteration descriptor \fIdesc\fP. If \fIwc\fP is WEOF,
WEOF is returned.
.PP
\fIdesc\fP must be a transliteration descriptor returned by the \fBwctrans\fP
function.
.SH "RETURN VALUE"
-The \fBtowctrans\fP function returns the translated wide character, or WEOF if
+The \fBtowctrans\fP() function returns the translated wide character, or WEOF if
\fIwc\fP is WEOF.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR towupper (3),
.BR wctrans (3)
.SH NOTES
-The behaviour of \fBtowctrans\fP depends on the LC_CTYPE category of the
+The behaviour of \fBtowctrans\fP() depends on the LC_CTYPE category of the
current locale.
.BI "wint_t towlower(wint_t " wc );
.fi
.SH DESCRIPTION
-The \fBtowlower\fP function is the wide-character equivalent of the
+The \fBtowlower\fP() function is the wide-character equivalent of the
\fBtolower\fP function. If \fIwc\fP is a wide character, it is converted to
lowercase. Characters which do not have case are returned unchanged.
If \fIwc\fP is WEOF, WEOF is returned.
.SH "RETURN VALUE"
-The \fBtowlower\fP function returns the lowercase equivalent of \fIwc\fP,
+The \fBtowlower\fP() function returns the lowercase equivalent of \fIwc\fP,
or WEOF if \fIwc\fP is WEOF.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR towctrans (3),
.BR towupper (3)
.SH NOTES
-The behaviour of \fBtowlower\fP depends on the LC_CTYPE category of the
+The behaviour of \fBtowlower\fP() depends on the LC_CTYPE category of the
current locale.
.PP
This function is not very appropriate for dealing with Unicode characters,
.BI "wint_t towupper(wint_t " wc );
.fi
.SH DESCRIPTION
-The \fBtowupper\fP function is the wide-character equivalent of the
+The \fBtowupper\fP() function is the wide-character equivalent of the
\fBtoupper\fP function. If \fIwc\fP is a wide character, it is converted to
uppercase. Characters which do not have case are returned unchanged.
If \fIwc\fP is WEOF, WEOF is returned.
.SH "RETURN VALUE"
-The \fBtowupper\fP function returns the uppercase equivalent of \fIwc\fP,
+The \fBtowupper\fP() function returns the uppercase equivalent of \fIwc\fP,
or WEOF if \fIwc\fP is WEOF.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR towctrans (3),
.BR towlower (3)
.SH NOTES
-The behaviour of \fBtowupper\fP depends on the LC_CTYPE category of the
+The behaviour of \fBtowupper\fP() depends on the LC_CTYPE category of the
current locale.
.PP
This function is not very appropriate for dealing with Unicode characters,
.RE
.fi
.SH DESCRIPTION
-\fBtsearch\fP, \fBtfind\fP, \fBtwalk\fP, and \fBtdelete\fP manage a
+\fBtsearch\fP(), \fBtfind\fP(), \fBtwalk\fP(), and \fBtdelete\fP() manage a
binary tree. They are generalized from Knuth (6.2.2) Algorithm T.
The first field in each node of the tree is a pointer to the
corresponding data item. (The calling program must store the actual
zero, or positive, depending on whether the first item is less than,
equal to, or greater than the second.
.PP
-\fBtsearch\fP searches the tree for an item. \fIkey\fP
+\fBtsearch\fP() searches the tree for an item. \fIkey\fP
points to the item to be searched for. \fIrootp\fP points to a
variable which points to the root of the tree. If the tree is empty,
then the variable that \fIrootp\fP points to should be set to \fBNULL\fP.
-If the item is found in the tree, then \fBtsearch\fP returns a pointer
-to it. If it is not found, then \fBtsearch\fP adds it, and returns a
+If the item is found in the tree, then \fBtsearch\fP() returns a pointer
+to it. If it is not found, then \fBtsearch\fP() adds it, and returns a
pointer to the newly added item.
.PP
-\fBtfind\fP is like \fBtsearch\fP, except that if the item is not
-found, then \fBtfind\fP returns \fBNULL\fP.
+\fBtfind\fP() is like \fBtsearch\fP(), except that if the item is not
+found, then \fBtfind\fP() returns \fBNULL\fP.
.PP
-\fBtdelete\fP deletes an item from the tree. Its arguments are the
-same as for \fBtsearch\fP.
+\fBtdelete\fP() deletes an item from the tree. Its arguments are the
+same as for \fBtsearch\fP().
.PP
-\fBtwalk\fP performs depth-first, left-to-right traversal of a binary
+\fBtwalk\fP() performs depth-first, left-to-right traversal of a binary
tree. \fIroot\fP points to the starting node for the traversal. If
that node is not the root, then only part of the tree will be visited.
-\fBtwalk\fP calls the user function \fIaction\fP each time a node is
+\fBtwalk\fP() calls the user function \fIaction\fP each time a node is
visited (that is, three times for an internal node, and once for a
leaf). \fIaction\fP, in turn, takes three arguments. The first is a
pointer to the node being visited. The second is an integer which
and after visiting the children. Thus, the choice of name \fBpost\%order\fP
is rather confusing.)
.PP
-\fBtdestroy\fP removes the whole tree pointed to by \fIrootp\fP,
-freeing all resources allocated by the \fBtsearch\fP function. For
+\fBtdestroy\fP() removes the whole tree pointed to by \fIrootp\fP,
+freeing all resources allocated by the \fBtsearch\fP() function. For
the data in each tree node the function \fIfree_node\fP is called.
The pointer to the data is passed as the argument to the function. If
no such work is necessary \fIfree_node\fP must point to a function
doing nothing.
.SH "RETURN VALUE"
-\fBtsearch\fP returns a pointer to a matching item in the tree, or to
+\fBtsearch\fP() returns a pointer to a matching item in the tree, or to
the newly added item, or \fBNULL\fP if there was insufficient memory
-to add the item. \fBtfind\fP returns a pointer to the item, or
+to add the item. \fBtfind\fP() returns a pointer to the item, or
\fBNULL\fP if no match is found. If there
are multiple elements that match the key, the element returned is
unspecified.
.PP
-\fBtdelete\fP returns a pointer to the parent of the item deleted, or
+\fBtdelete\fP() returns a pointer to the parent of the item deleted, or
\fBNULL\fP if the item was not found.
.PP
-\fBtsearch\fP, \fBtfind\fP, and \fBtdelete\fP also
+\fBtsearch\fP(), \fBtfind\fP(), and \fBtdelete\fP() also
return \fBNULL\fP if \fIrootp\fP was \fBNULL\fP on entry.
.SH WARNINGS
-\fBtwalk\fP takes a pointer to the root, while the other functions
+\fBtwalk\fP() takes a pointer to the root, while the other functions
take a pointer to a variable which points to the root.
.PP
-\fBtwalk\fP uses \fBpostorder\fP to mean "after the left subtree, but
+\fBtwalk\fP() uses \fBpostorder\fP to mean "after the left subtree, but
before the right subtree". Some authorities would call this
"inorder", and reserve "postorder" to mean "after both subtrees".
.PP
-\fBtdelete\fP frees the memory required for the node in the tree.
+\fBtdelete\fP() frees the memory required for the node in the tree.
The user is responsible for freeing the memory for the corresponding
data.
.PP
-The example program depends on the fact that \fBtwalk\fP makes no
+The example program depends on the fact that \fBtwalk\fP() makes no
further reference to a node after calling the user function with
argument "endorder" or "leaf". This works with the GNU library
implementation, but is not in the SysV documentation.
provided by glibc. Use getrlimit(2), setrlimit(2) and sysconf(3)
instead.
For the shell command
-.BR ulimit ,
+.BR ulimit (),
see
.BR bash (1).
The
-.B ulimit
+.BR ulimit ()
call will get or set some limit for the current process.
The
.I cmd
.SH "RETURN VALUE"
On success,
-.B ulimit
+.BR ulimit ()
returns a nonnegative value.
On error, \-1 is returned, and
.I errno
.BI "wint_t ungetwc(wint_t " wc ", FILE *" stream );
.fi
.SH DESCRIPTION
-The \fBungetwc\fP function is the wide-character equivalent of the \fBungetc\fP
+The \fBungetwc\fP() function is the wide-character equivalent of the \fBungetc\fP
function. It pushes back a wide character onto \fIstream\fP and returns it.
.PP
If \fIwc\fP is WEOF, it returns WEOF. If \fIwc\fP is an invalid wide character,
pushed-back wide characters will be read in reverse order; however, only one
level of push-back is guaranteed.
.SH "RETURN VALUE"
-The \fBungetwc\fP function returns \fIwc\fP when successful, or WEOF upon
+The \fBungetwc\fP() function returns \fIwc\fP when successful, or WEOF upon
failure.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH "SEE ALSO"
.BR fgetwc (3)
.SH NOTES
-The behaviour of \fBungetwc\fP depends on the LC_CTYPE category of the
+The behaviour of \fBungetwc\fP() depends on the LC_CTYPE category of the
current locale.
.SH AVAILABILITY
Both functions are available under glibc2, but not under libc5.
However,
-.B logwtmp
+.BR logwtmp ()
used to occur in the old libbsd. These days, the
-.B logwtmp
+.BR logwtmp ()
function is included in libutil. (Hence you'll need to add
.B \-lutil
to your compiler command line to get it.)
.BI "wchar_t *wcpcpy(wchar_t *" dest ", const wchar_t *" src );
.fi
.SH DESCRIPTION
-The \fBwcpcpy\fP function is the wide-character equivalent of the \fBstpcpy\fP
+The \fBwcpcpy\fP() function is the wide-character equivalent of the \fBstpcpy\fP
function. It copies the wide character string pointed to by \fIsrc\fP,
including the terminating L'\\0' character, to the array pointed to by
\fIdest\fP.
The programmer must ensure that there is room for at least \fIwcslen(src)+1\fP
wide characters at \fIdest\fP.
.SH "RETURN VALUE"
-\fBwcpcpy\fP returns a pointer to the end of the wide-character string
+\fBwcpcpy\fP() returns a pointer to the end of the wide-character string
\fIdest\fP, that is, a pointer to the terminating L'\\0' character.
.SH "CONFORMING TO"
This function is a GNU extension.
.BI "wchar_t *wcpncpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n );
.fi
.SH DESCRIPTION
-The \fBwcpncpy\fP function is the wide-character equivalent of the \fBstpncpy\fP
+The \fBwcpncpy\fP() function is the wide-character equivalent of the \fBstpncpy\fP
function. It copies at most \fIn\fP wide characters from the wide-character
string pointed to by \fIsrc\fP, including the terminating L'\\0' character,
to the array pointed to by \fIdest\fP. Exactly \fIn\fP wide characters are
The programmer must ensure that there is room for at least \fIn\fP wide
characters at \fIdest\fP.
.SH "RETURN VALUE"
-\fBwcpncpy\fP returns a pointer to the last wide character written, i.e.
+\fBwcpncpy\fP() returns a pointer to the last wide character written, i.e.
\fIdest + n \- 1\fP.
.SH "CONFORMING TO"
This function is a GNU extension.
.SH DESCRIPTION
The main case for this function is when \fIs\fP is not NULL and \fIwc\fP is not
L'\\0'.
-In this case, the \fBwcrtomb\fP function converts the wide character \fIwc\fP
+In this case, the \fBwcrtomb\fP() function converts the wide character \fIwc\fP
to its multibyte representation and stores it at the beginning of the character
array pointed to by \fIs\fP. It updates the shift state \fI*ps\fP, and
returns the length of said multibyte representation, i.e. the number of bytes
written at \fIs\fP.
.PP
A different case is when \fIs\fP is not NULL but \fIwc\fP is L'\\0'. In this
-case the \fBwcrtomb\fP function stores at the character array pointed to by
+case the \fBwcrtomb\fP() function stores at the character array pointed to by
\fIs\fP the shift sequence needed to bring \fI*ps\fP back to the initial state,
followed by a '\\0' byte. It updates the shift state \fI*ps\fP (i.e. brings
it into the initial state), and returns the length of the shift sequence plus
In all of the above cases, if \fIps\fP is a NULL pointer, a static anonymous
state only known to the wcrtomb function is used instead.
.SH "RETURN VALUE"
-The \fBwcrtomb\fP function returns the number of bytes that have been or would
+The \fBwcrtomb\fP() function returns the number of bytes that have been or would
have been written to the byte array at \fIs\fP. If \fIwc\fP can not be
represented as a multibyte sequence (according to the current locale),
(size_t)(\-1) is returned, and \fBerrno\fP set to \fBEILSEQ\fP.
.SH "SEE ALSO"
.BR wcsrtombs (3)
.SH NOTES
-The behaviour of \fBwcrtomb\fP depends on the LC_CTYPE category of the
+The behaviour of \fBwcrtomb\fP() depends on the LC_CTYPE category of the
current locale.
.PP
Passing NULL as \fIps\fP is not multi-thread safe.
.BI "int wcscasecmp(const wchar_t *" s1 ", const wchar_t *" s2 );
.fi
.SH DESCRIPTION
-The \fBwcscasecmp\fP function is the wide-character equivalent of the
+The \fBwcscasecmp\fP() function is the wide-character equivalent of the
\fBstrcasecmp\fP function. It compares the wide-character string pointed to
by \fIs1\fP and the wide-character string pointed to by \fIs2\fP, ignoring
case differences (\fBtowupper\fP, \fBtowlower\fP).
.SH "RETURN VALUE"
-The \fBwcscasecmp\fP function returns zero if the wide-character strings at
+The \fBwcscasecmp\fP() function returns zero if the wide-character strings at
\fIs1\fP and \fIs2\fP are equal except for case distinctions. It returns a
positive integer if \fIs1\fP is greater than \fIs2\fP, ignoring case. It
returns a negative integer if \fIs1\fP is smaller than \fIs2\fP, ignoring case.
.BR strcasecmp (3),
.BR wcscmp (3)
.SH NOTES
-The behaviour of \fBwcscasecmp\fP depends on the LC_CTYPE category of the
+The behaviour of \fBwcscasecmp\fP() depends on the LC_CTYPE category of the
current locale.
.BI "wchar_t *wcscat(wchar_t *" dest ", const wchar_t *" src );
.fi
.SH DESCRIPTION
-The \fBwcscat\fP function is the wide-character equivalent of the \fBstrcat\fP
+The \fBwcscat\fP() function is the wide-character equivalent of the \fBstrcat\fP
function. It copies the wide-character string pointed to by \fIsrc\fP,
including the terminating L'\\0' character, to the end of the wide-character
string pointed to by \fIdest\fP.
The programmer must ensure that there is room for at least
\fIwcslen(dest)+wcslen(src)+1\fP wide characters at \fIdest\fP.
.SH "RETURN VALUE"
-\fBwcscat\fP returns \fIdest\fP.
+\fBwcscat\fP() returns \fIdest\fP.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH "SEE ALSO"
.BI "wchar_t *wcschr(const wchar_t *" wcs ", wchar_t " wc );
.fi
.SH DESCRIPTION
-The \fBwcschr\fP function is the wide-character equivalent of the \fBstrchr\fP
+The \fBwcschr\fP() function is the wide-character equivalent of the \fBstrchr\fP
function. It searches the first occurrence of \fIwc\fP in the wide-character
string pointed to by \fIwcs\fP.
.SH "RETURN VALUE"
-The \fBwcschr\fP function returns a pointer to the first occurrence of
+The \fBwcschr\fP() function returns a pointer to the first occurrence of
\fIwc\fP in the wide-character string pointed to by \fIwcs\fP, or NULL if
\fIwc\fP does not occur in the string.
.SH "CONFORMING TO"
.BI "int wcscmp(const wchar_t *" s1 ", const wchar_t *" s2 );
.fi
.SH DESCRIPTION
-The \fBwcscmp\fP function is the wide-character equivalent of the \fBstrcmp\fP
+The \fBwcscmp\fP() function is the wide-character equivalent of the \fBstrcmp\fP
function. It compares the wide-character string pointed to by \fIs1\fP and the
wide-character string pointed to by \fIs2\fP.
.SH "RETURN VALUE"
-The \fBwcscmp\fP function returns zero if the wide-character strings at
+The \fBwcscmp\fP() function returns zero if the wide-character strings at
\fIs1\fP and \fIs2\fP are equal. It returns an integer greater than zero if
at the first differing position \fIi\fP, the corresponding wide-character
\fIs1[i]\fP is greater than \fIs2[i]\fP. It returns an integer less than zero if
.BI "wchar_t *wcscpy(wchar_t *" dest ", const wchar_t *" src );
.fi
.SH DESCRIPTION
-The \fBwcscpy\fP function is the wide-character equivalent of the \fBstrcpy\fP
+The \fBwcscpy\fP() function is the wide-character equivalent of the \fBstrcpy\fP
function. It copies the wide character string pointed to by \fIsrc\fP,
including the terminating L'\\0' character, to the array pointed to by
\fIdest\fP.
The programmer must ensure that there is room for at least \fIwcslen(src)+1\fP
wide characters at \fIdest\fP.
.SH "RETURN VALUE"
-\fBwcscpy\fP returns \fIdest\fP.
+\fBwcscpy\fP() returns \fIdest\fP.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH "SEE ALSO"
.BI "size_t wcscspn(const wchar_t *" wcs ", const wchar_t *" reject );
.fi
.SH DESCRIPTION
-The \fBwcscspn\fP function is the wide-character equivalent of the \fBstrcspn\fP
+The \fBwcscspn\fP() function is the wide-character equivalent of the \fBstrcspn\fP
function. It determines the length of the longest initial segment of \fIwcs\fP
which consists entirely of wide-characters not listed in \fIreject\fP. In
other words, it searches for the first occurrence in the wide-character
string \fIwcs\fP of any of the characters in the wide-character string
\fIreject\fP.
.SH "RETURN VALUE"
-The \fBwcscspn\fP function returns the number of wide characters in the longest
+The \fBwcscspn\fP() function returns the number of wide characters in the longest
initial segment of \fIwcs\fP which consists entirely of wide-characters not
listed in \fIreject\fP. In other words, it returns the position of the first
occurrence in the wide-character string \fIwcs\fP of any of the characters in
.BI "wchar_t *wcsdup(const wchar_t *" s );
.fi
.SH DESCRIPTION
-The \fBwcsdup\fP function is the wide-character equivalent of the \fBstrdup\fP
+The \fBwcsdup\fP() function is the wide-character equivalent of the \fBstrdup\fP
function. It allocates and returns a new wide-character string whose initial
contents is a duplicate of the wide-character string pointed to by \fIs\fP.
.PP
Memory for the new wide-character string is obtained with \fBmalloc\fP(3), and
can be freed with \fBfree\fP(3).
.SH "RETURN VALUE"
-The \fBwcsdup\fP function returns a pointer to the new wide-character string,
+The \fBwcsdup\fP() function returns a pointer to the new wide-character string,
or NULL if sufficient memory was not available.
.SH ERRORS
.TP
.BI "size_t wcslen(const wchar_t *" s );
.fi
.SH DESCRIPTION
-The \fBwcslen\fP function is the wide-character equivalent of the \fBstrlen\fP
+The \fBwcslen\fP() function is the wide-character equivalent of the \fBstrlen\fP
function. It determines the length of the wide-character string pointed to
by \fIs\fP, not including the terminating L'\\0' character.
.SH "RETURN VALUE"
-The \fBwcslen\fP function returns the number of wide characters in \fIs\fP.
+The \fBwcslen\fP() function returns the number of wide characters in \fIs\fP.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH "SEE ALSO"
.BI "int wcsncasecmp(const wchar_t *" s1 ", const wchar_t *" s2 ", size_t " n );
.fi
.SH DESCRIPTION
-The \fBwcsncasecmp\fP function is the wide-character equivalent of the
+The \fBwcsncasecmp\fP() function is the wide-character equivalent of the
\fBstrncasecmp\fP function. It compares the wide-character string pointed to
by \fIs1\fP and the wide-character string pointed to by \fIs2\fP, but at most
\fIn\fP wide characters from each string, ignoring case differences
(\fBtowupper\fP, \fBtowlower\fP).
.SH "RETURN VALUE"
-The \fBwcsncasecmp\fP function returns zero if the wide-character strings at
+The \fBwcsncasecmp\fP() function returns zero if the wide-character strings at
\fIs1\fP and \fIs2\fP, truncated to at most length \fIn\fP, are equal except
for case distinctions. It returns a positive integer if truncated \fIs1\fP is
greater than truncated \fIs2\fP, ignoring case. It returns a negative integer
.BR strncasecmp (3),
.BR wcsncmp (3)
.SH NOTES
-The behaviour of \fBwcsncasecmp\fP depends on the LC_CTYPE category of the
+The behaviour of \fBwcsncasecmp\fP() depends on the LC_CTYPE category of the
current locale.
.BI "wchar_t *wcsncat(wchar_t *" dest ", const wchar_t *" src ", size_t " n );
.fi
.SH DESCRIPTION
-The \fBwcsncat\fP function is the wide-character equivalent of the \fBstrncat\fP
+The \fBwcsncat\fP() function is the wide-character equivalent of the \fBstrncat\fP
function. It copies at most \fIn\fP wide characters from the wide-character
string pointed to by \fIsrc\fP to the end of the wide-character string pointed
to by \fIdest\fP, and adds a terminating L'\\0' character.
The programmer must ensure that there is room for at least
\fIwcslen(dest)+n+1\fP wide characters at \fIdest\fP.
.SH "RETURN VALUE"
-\fBwcsncat\fP returns \fIdest\fP.
+\fBwcsncat\fP() returns \fIdest\fP.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH "SEE ALSO"
.BI "int wcsncmp(const wchar_t *" s1 ", const wchar_t *" s2 ", size_t " n );
.fi
.SH DESCRIPTION
-The \fBwcsncmp\fP function is the wide-character equivalent of the \fBstrncmp\fP
+The \fBwcsncmp\fP() function is the wide-character equivalent of the \fBstrncmp\fP
function. It compares the wide-character string pointed to by \fIs1\fP and the
wide-character string pointed to by \fIs2\fP, but at most \fIn\fP wide
characters from each string. In each string, the comparison extends only up
to the first occurrence of a L'\\0' character, if any.
.SH "RETURN VALUE"
-The \fBwcsncmp\fP function returns zero if the wide-character strings at
+The \fBwcsncmp\fP() function returns zero if the wide-character strings at
\fIs1\fP and \fIs2\fP, truncated to at most length \fIn\fP, are equal.
It returns an integer greater than zero if at the first differing position
\fIi\fP (\fIi\fP < \fIn\fP), the corresponding wide-character \fIs1[i]\fP is
.BI "wchar_t *wcsncpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n );
.fi
.SH DESCRIPTION
-The \fBwcsncpy\fP function is the wide-character equivalent of the \fBstrncpy\fP
+The \fBwcsncpy\fP() function is the wide-character equivalent of the \fBstrncpy\fP
function. It copies at most \fIn\fP wide characters from the wide-character
string pointed to by \fIsrc\fP, including the terminating L'\\0' character,
to the array pointed to by \fIdest\fP. Exactly \fIn\fP wide characters are
The programmer must ensure that there is room for at least \fIn\fP wide
characters at \fIdest\fP.
.SH "RETURN VALUE"
-\fBwcsncpy\fP returns \fIdest\fP.
+\fBwcsncpy\fP() returns \fIdest\fP.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH "SEE ALSO"
.BI "size_t wcsnlen(const wchar_t *" s ", size_t " maxlen );
.fi
.SH DESCRIPTION
-The \fBwcsnlen\fP function is the wide-character equivalent of the \fBstrnlen\fP
+The \fBwcsnlen\fP() function is the wide-character equivalent of the \fBstrnlen\fP
function. It returns the number of wide-characters in the string pointed to by
\fIs\fP, not including the terminating L'\\0' character, but at most
-\fImaxlen\fP. In doing this, \fBwcsnlen\fP looks only at the first \fImaxlen\fP
+\fImaxlen\fP. In doing this, \fBwcsnlen\fP() looks only at the first \fImaxlen\fP
wide-characters at \fIs\fP and never beyond \fIs+maxlen\fP.
.SH "RETURN VALUE"
-The \fBwcsnlen\fP function returns \fIwcslen(s)\fP, if that is less than
+The \fBwcsnlen\fP() function returns \fIwcslen(s)\fP, if that is less than
\fImaxlen\fP, or \fImaxlen\fP if there is no L'\\0' character among the
first \fImaxlen\fP wide characters pointed to by \fIs\fP.
.SH "CONFORMING TO"
.BI " size_t " len ", mbstate_t *" ps );
.fi
.SH DESCRIPTION
-The \fBwcsnrtombs\fP function is like the \fBwcsrtombs\fP function, except that
+The \fBwcsnrtombs\fP() function is like the \fBwcsrtombs\fP function, except that
the number of wide characters to be converted, starting at \fI*src\fP, is
limited to \fInwc\fP.
.PP
-If \fIdest\fP is not a NULL pointer, the \fBwcsnrtombs\fP function converts
+If \fIdest\fP is not a NULL pointer, the \fBwcsnrtombs\fP() function converts
at most \fInwc\fP wide characters from
the wide-character string \fI*src\fP to a multibyte string starting at
\fIdest\fP. At most \fIlen\fP bytes are written to \fIdest\fP. The shift state
The programmer must ensure that there is room for at least \fIlen\fP bytes
at \fIdest\fP.
.SH "RETURN VALUE"
-The \fBwcsnrtombs\fP function returns the number of bytes that make up the
+The \fBwcsnrtombs\fP() function returns the number of bytes that make up the
converted part of multibyte sequence, not including the terminating null byte.
If a wide character was encountered which could not be converted, (size_t)(\-1)
is returned, and \fBerrno\fP set to \fBEILSEQ\fP.
.BR iconv (3),
.BR wcsrtombs (3)
.SH NOTES
-The behaviour of \fBwcsnrtombs\fP depends on the LC_CTYPE category of the
+The behaviour of \fBwcsnrtombs\fP() depends on the LC_CTYPE category of the
current locale.
.PP
Passing NULL as \fIps\fP is not multi-thread safe.
.BI "wchar_t *wcspbrk(const wchar_t *" wcs ", const wchar_t *" accept );
.fi
.SH DESCRIPTION
-The \fBwcspbrk\fP function is the wide-character equivalent of the \fBstrpbrk\fP
+The \fBwcspbrk\fP() function is the wide-character equivalent of the \fBstrpbrk\fP
function. It searches for the first occurrence in the wide-character
string pointed to by \fIwcs\fP of any of the characters in the wide-character
string pointed to by \fIaccept\fP.
.SH "RETURN VALUE"
-The \fBwcspbrk\fP function returns a pointer to the first occurrence in
+The \fBwcspbrk\fP() function returns a pointer to the first occurrence in
\fIwcs\fP of any of the characters listed in \fIaccept\fP. If \fIwcs\fP
contains none of these characters, NULL is returned.
.SH "CONFORMING TO"
.BI "wchar_t *wcsrchr(const wchar_t *" wcs ", wchar_t " wc );
.fi
.SH DESCRIPTION
-The \fBwcsrchr\fP function is the wide-character equivalent of the \fBstrrchr\fP
+The \fBwcsrchr\fP() function is the wide-character equivalent of the \fBstrrchr\fP
function. It searches the last occurrence of \fIwc\fP in the wide-character
string pointed to by \fIwcs\fP.
.SH "RETURN VALUE"
-The \fBwcsrchr\fP function returns a pointer to the last occurrence of
+The \fBwcsrchr\fP() function returns a pointer to the last occurrence of
\fIwc\fP in the wide-character string pointed to by \fIwcs\fP, or NULL if
\fIwc\fP does not occur in the string.
.SH "CONFORMING TO"
.BI " size_t " len ", mbstate_t *" ps );
.fi
.SH DESCRIPTION
-If \fIdest\fP is not a NULL pointer, the \fBwcsrtombs\fP function converts
+If \fIdest\fP is not a NULL pointer, the \fBwcsrtombs\fP() function converts
the wide-character string \fI*src\fP to a multibyte string starting at
\fIdest\fP. At most \fIlen\fP bytes are written to \fIdest\fP. The shift state
\fI*ps\fP is updated. The conversion is effectively performed by repeatedly
The programmer must ensure that there is room for at least \fIlen\fP bytes
at \fIdest\fP.
.SH "RETURN VALUE"
-The \fBwcsrtombs\fP function returns the number of bytes that make up the
+The \fBwcsrtombs\fP() function returns the number of bytes that make up the
converted part of multibyte sequence, not including the terminating null byte.
If a wide character was encountered which could not be converted, (size_t)(\-1)
is returned, and
.BR wcsnrtombs (3),
.BR wcstombs (3)
.SH NOTES
-The behaviour of \fBwcsrtombs\fP depends on the LC_CTYPE category of the
+The behaviour of \fBwcsrtombs\fP() depends on the LC_CTYPE category of the
current locale.
.PP
Passing NULL as \fIps\fP is not multi-thread safe.
.BI "wcsspn(const wchar_t *" wcs ", const wchar_t *" accept );
.fi
.SH DESCRIPTION
-The \fBwcsspn\fP function is the wide-character equivalent of the \fBstrspn\fP
+The \fBwcsspn\fP() function is the wide-character equivalent of the \fBstrspn\fP
function. It determines the length of the longest initial segment of \fIwcs\fP
which consists entirely of wide-characters listed in \fIaccept\fP. In other
words, it searches for the first occurrence in the wide-character string
\fIwcs\fP of a wide-character not contained in the wide-character string
\fIaccept\fP.
.SH "RETURN VALUE"
-The \fBwcsspn\fP function returns the number of wide characters in the longest
+The \fBwcsspn\fP() function returns the number of wide characters in the longest
initial segment of \fIwcs\fP which consists entirely of wide-characters listed
in \fIaccept\fP. In other words, it returns the position of the first
occurrence in the wide-character string \fIwcs\fP of a wide-character not
.BI "wchar_t *wcsstr(const wchar_t *" haystack ", const wchar_t *" needle );
.fi
.SH DESCRIPTION
-The \fBwcsstr\fP function is the wide-character equivalent of the \fBstrstr\fP
+The \fBwcsstr\fP() function is the wide-character equivalent of the \fBstrstr\fP
function. It searches for the first occurrence of the wide-character string
\fIneedle\fP (without its terminating L'\\0' character) as a substring in
the wide-character string \fIhaystack\fP.
.SH "RETURN VALUE"
-The \fBwcsstr\fP function returns a pointer to the first occurrence of
+The \fBwcsstr\fP() function returns a pointer to the first occurrence of
\fIneedle\fP in \fIhaystack\fP. It returns NULL if \fIneedle\fP does not occur
as a substring in \fIhaystack\fP.
.PP
.BI "wchar_t *wcstok(wchar_t *" wcs ", const wchar_t *" delim ", wchar_t **" ptr );
.fi
.SH DESCRIPTION
-The \fBwcstok\fP function is the wide-character equivalent of the \fBstrtok\fP
+The \fBwcstok\fP() function is the wide-character equivalent of the \fBstrtok\fP
function, with an added argument to make it multithread-safe. It can be used
to split a wide-character string \fIwcs\fP into tokens, where a token is
defined as a substring not containing any wide-characters from \fIdelim\fP.
The search starts at \fIwcs\fP, if \fIwcs\fP is not NULL, or at \fI*ptr\fP, if
\fIwcs\fP is NULL. First, any delimiter wide-characters are skipped, i.e. the
pointer is advanced beyond any wide-characters which occur in \fIdelim\fP.
-If the end of the wide-character string is now reached, \fBwcstok\fP returns
+If the end of the wide-character string is now reached, \fBwcstok\fP() returns
NULL, to indicate that no tokens were found, and stores an appropriate value
-in \fI*ptr\fP, so that subsequent calls to \fBwcstok\fP will continue to return
-NULL. Otherwise, the \fBwcstok\fP function recognizes the beginning of a token
+in \fI*ptr\fP, so that subsequent calls to \fBwcstok\fP() will continue to return
+NULL. Otherwise, the \fBwcstok\fP() function recognizes the beginning of a token
and returns a pointer to it, but before doing that, it zero-terminates the
token by replacing the next wide-character which occurs in \fIdelim\fP with
a L'\\0' character, and it updates \fI*ptr\fP so that subsequent calls will
continue searching after the end of recognized token.
.SH "RETURN VALUE"
-The \fBwcstok\fP function returns a pointer to the next token, or NULL if no
+The \fBwcstok\fP() function returns a pointer to the next token, or NULL if no
further token was found.
.SH NOTES
The original \fIwcs\fP wide-character string is destructively modified during
.BI "size_t wcstombs(char *" dest ", const wchar_t *" src ", size_t " n );
.fi
.SH DESCRIPTION
-If \fIdest\fP is not a NULL pointer, the \fBwcstombs\fP function converts
+If \fIdest\fP is not a NULL pointer, the \fBwcstombs\fP() function converts
the wide-character string \fIsrc\fP to a multibyte string starting at
\fIdest\fP. At most \fIn\fP bytes are written to \fIdest\fP. The conversion
starts in the initial state. The conversion can stop for three reasons:
In order to avoid the case 2 above, the programmer should make sure \fIn\fP
is greater or equal to \fIwcstombs(NULL,src,0)+1\fP.
.SH "RETURN VALUE"
-The \fBwcstombs\fP function returns the number of bytes that make up the
+The \fBwcstombs\fP() function returns the number of bytes that make up the
converted part of multibyte sequence, not including the terminating null byte.
If a wide character was encountered which could not be converted, (size_t)(\-1)
is returned.
.SH "SEE ALSO"
.BR wcsrtombs (3)
.SH NOTES
-The behaviour of \fBwcstombs\fP depends on the LC_CTYPE category of the
+The behaviour of \fBwcstombs\fP() depends on the LC_CTYPE category of the
current locale.
.PP
The function \fBwcsrtombs\fP provides a thread safe interface to the same
.BI "int wcswidth(const wchar_t *" s ", size_t " n );
.fi
.SH DESCRIPTION
-The \fBwcswidth\fP function returns the number of columns needed to represent
+The \fBwcswidth\fP() function returns the number of columns needed to represent
the wide-character string pointed to by \fIs\fP, but at most \fIn\fP wide
characters. If a non-printable wide character occurs among these characters,
-1 is returned.
.SH "RETURN VALUE"
-The \fBwcswidth\fP function returns the number of column positions for the
+The \fBwcswidth\fP() function returns the number of column positions for the
wide-character string \fIs\fP, truncated to at most length \fIn\fP.
.SH "CONFORMING TO"
UNIX98
.BR iswprint (3),
.BR wcwidth (3)
.SH NOTES
-The behaviour of \fBwcswidth\fP depends on the LC_CTYPE category of the
+The behaviour of \fBwcswidth\fP() depends on the LC_CTYPE category of the
current locale.
.BI "int wctob(wint_t " c );
.fi
.SH DESCRIPTION
-The \fBwctob\fP function tests whether the multi-byte representation of the
+The \fBwctob\fP() function tests whether the multi-byte representation of the
wide character \fIc\fP, starting in the initial state, consists of a single
byte. If so, it is returned as an unsigned char.
.PP
programs. Internationalized programs must never distinguish single-byte and
multi-byte characters.
.SH "RETURN VALUE"
-The \fBwctob\fP function returns the single-byte representation of \fIc\fP,
+The \fBwctob\fP() function returns the single-byte representation of \fIc\fP,
if it exists, of EOF otherwise.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH "SEE ALSO"
.BR wctomb (3)
.SH NOTES
-The behaviour of \fBwctob\fP depends on the LC_CTYPE category of the
+The behaviour of \fBwctob\fP() depends on the LC_CTYPE category of the
current locale.
.PP
This function should never be used. Internationalized programs must never
.BI "int wctomb(char *" s ", wchar_t " wc );
.fi
.SH DESCRIPTION
-If \fIs\fP is not NULL, the \fBwctomb\fP function converts the wide character
+If \fIs\fP is not NULL, the \fBwctomb\fP() function converts the wide character
\fIwc\fP to its multibyte representation and stores it at the beginning of
the character array pointed to by \fIs\fP. It updates the shift state, which
is stored in a static anonymous variable only known to the wctomb function,
The programmer must ensure that there is room for at least \fBMB_CUR_MAX\fP
bytes at \fIs\fP.
.PP
-If \fIs\fP is NULL, the \fBwctomb\fP function
+If \fIs\fP is NULL, the \fBwctomb\fP() function
.\" The Dinkumware doc and the Single Unix specification say this, but
.\" glibc doesn't implement this.
resets the shift state, only known to this function, to the initial state, and
returns non-zero if the encoding has non-trivial shift state, or zero if the
encoding is stateless.
.SH "RETURN VALUE"
-If \fIs\fP is not NULL, the \fBwctomb\fP function returns the number of bytes
+If \fIs\fP is not NULL, the \fBwctomb\fP() function returns the number of bytes
that have been written to the byte array at \fIs\fP. If \fIwc\fP can not be
represented as a multibyte sequence (according to the current locale), \-1 is
returned.
.PP
-If \fIs\fP is NULL, the \fBwctomb\fP function returns non-zero if the
+If \fIs\fP is NULL, the \fBwctomb\fP() function returns non-zero if the
encoding has non-trivial shift state, or zero if the encoding is stateless.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.BR wcrtomb (3),
.BR wcstombs (3)
.SH NOTES
-The behaviour of \fBwctomb\fP depends on the LC_CTYPE category of the
+The behaviour of \fBwctomb\fP() depends on the LC_CTYPE category of the
current locale.
.PP
This function is not multi-thread safe. The function \fBwcrtomb\fP provides
values can be passed to the \fBtowctrans\fP function to actually perform
the wide character mapping.
.PP
-The \fBwctrans\fP function returns a mapping, given by its name. The set of
+The \fBwctrans\fP() function returns a mapping, given by its name. The set of
valid names depends on the LC_CTYPE category of the current locale, but the
following names are valid in all locales.
.nf
"toupper" \- realizes the \fBtoupper\fP(3) mapping
.fi
.SH "RETURN VALUE"
-The \fBwctrans\fP function returns a mapping descriptor if the \fIname\fP
+The \fBwctrans\fP() function returns a mapping descriptor if the \fIname\fP
is valid. Otherwise it returns \fI(wctrans_t)0\fP.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH "SEE ALSO"
.BR wctrans (3)
.SH NOTES
-The behaviour of \fBwctrans\fP depends on the LC_CTYPE category of the
+The behaviour of \fBwctrans\fP() depends on the LC_CTYPE category of the
current locale.
can be passed to the \fBiswctype\fP function to actually test whether a given
wide character has the property.
.PP
-The \fBwctype\fP function returns a property, given by its name. The set of
+The \fBwctype\fP() function returns a property, given by its name. The set of
valid names depends on the LC_CTYPE category of the current locale, but the
following names are valid in all locales.
.nf
"xdigit" \- realizes the \fBisxdigit\fP classification function
.fi
.SH "RETURN VALUE"
-The \fBwctype\fP function returns a property descriptor if the \fIname\fP is
+The \fBwctype\fP() function returns a property descriptor if the \fIname\fP is
valid. Otherwise it returns \fI(wctype_t)0\fP.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH "SEE ALSO"
.BR iswctype (3)
.SH NOTES
-The behaviour of \fBwctype\fP depends on the LC_CTYPE category of the
+The behaviour of \fBwctype\fP() depends on the LC_CTYPE category of the
current locale.
.BI "int wcwidth(wchar_t " c );
.fi
.SH DESCRIPTION
-The \fBwcwidth\fP function returns the number of columns needed to represent
+The \fBwcwidth\fP() function returns the number of columns needed to represent
the wide character \fIc\fP. If \fIc\fP is a printable wide character, the value
is at least 0. If \fIc\fP is L'\\0', the value is 0. Otherwise \-1 is returned.
.SH "RETURN VALUE"
-The \fBwcwidth\fP function returns the number of column positions for \fIc\fP.
+The \fBwcwidth\fP() function returns the number of column positions for \fIc\fP.
.SH "CONFORMING TO"
UNIX98, POSIX 1003.1-2001
Note that glibc before 2.2.5 used the prototype
.BR iswprint (3),
.BR wcswidth (3)
.SH NOTES
-The behaviour of \fBwcwidth\fP depends on the LC_CTYPE category of the
+The behaviour of \fBwcwidth\fP() depends on the LC_CTYPE category of the
current locale.
.BI "wchar_t *wmemchr(const wchar_t *" s ", wchar_t " c ", size_t " n );
.fi
.SH DESCRIPTION
-The \fBwmemchr\fP function is the wide-character equivalent of the \fBmemchr\fP
+The \fBwmemchr\fP() function is the wide-character equivalent of the \fBmemchr\fP
function. It searches the \fIn\fP wide characters starting at \fIs\fP for
the first occurrence of the wide character \fIc\fP.
.SH "RETURN VALUE"
-The \fBwmemchr\fP function returns a pointer to the first occurrence of \fIc\fP
+The \fBwmemchr\fP() function returns a pointer to the first occurrence of \fIc\fP
among the \fIn\fP wide characters starting at \fIs\fP, or NULL if \fIc\fP does
not occur among these.
.SH "CONFORMING TO"
.BI "int wmemcmp(const wchar_t *" s1 ", const wchar_t *" s2 ", size_t " n );
.fi
.SH DESCRIPTION
-The \fBwmemcmp\fP function is the wide-character equivalent of the \fBmemcmp\fP
+The \fBwmemcmp\fP() function is the wide-character equivalent of the \fBmemcmp\fP
function. It compares the \fIn\fP wide-characters starting at \fIs1\fP and the
\fIn\fP wide-characters starting at \fIs2\fP.
.SH "RETURN VALUE"
-The \fBwmemcmp\fP function returns zero if the wide-character arrays of size
+The \fBwmemcmp\fP() function returns zero if the wide-character arrays of size
\fIn\fP at \fIs1\fP and \fIs2\fP are equal. It returns an integer greater than
zero if at the first differing position \fIi\fP (\fIi\fP < \fIn\fP), the
corresponding wide-character \fIs1[i]\fP is greater than \fIs2[i]\fP. It
.BI "wchar_t *wmemcpy(wchar_t *" dest ", const wchar_t *" src ", size_t " n );
.fi
.SH DESCRIPTION
-The \fBwmemcpy\fP function is the wide-character equivalent of the \fBmemcpy\fP
+The \fBwmemcpy\fP() function is the wide-character equivalent of the \fBmemcpy\fP
function. It copies \fIn\fP wide characters from the array starting at
\fIsrc\fP to the array starting at \fIdest\fP.
.PP
The programmer must ensure that there is room for at least \fIn\fP wide
characters at \fIdest\fP.
.SH "RETURN VALUE"
-\fBwmemcpy\fP returns \fIdest\fP.
+\fBwmemcpy\fP() returns \fIdest\fP.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH "SEE ALSO"
.BI "wchar_t *wmemmove(wchar_t *" dest ", const wchar_t *" src ", size_t " n );
.fi
.SH DESCRIPTION
-The \fBwmemmove\fP function is the wide-character equivalent of the
+The \fBwmemmove\fP() function is the wide-character equivalent of the
\fBmemmove\fP function. It copies \fIn\fP wide characters from the array
starting at \fIsrc\fP to the array starting at \fIdest\fP. The arrays may
overlap.
The programmer must ensure that there is room for at least \fIn\fP wide
characters at \fIdest\fP.
.SH "RETURN VALUE"
-\fBwmemmove\fP returns \fIdest\fP.
+\fBwmemmove\fP() returns \fIdest\fP.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH "SEE ALSO"
.BI "wchar_t *wmemset(wchar_t *" wcs ", wchar_t " wc ", size_t " n );
.fi
.SH DESCRIPTION
-The \fBwmemset\fP function is the wide-character equivalent of the \fBmemset\fP
+The \fBwmemset\fP() function is the wide-character equivalent of the \fBmemset\fP
function. It fills the array of \fIn\fP wide-characters starting at \fIwcs\fP
with \fIn\fP copies of the wide character \fIwc\fP.
.SH "RETURN VALUE"
-\fBwmemset\fP returns \fIwcs\fP.
+\fBwmemset\fP() returns \fIwcs\fP.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH "SEE ALSO"
.BI " const wchar_t *" format ", va_list " args );
.fi
.SH DESCRIPTION
-The \fBwprintf\fP family of functions is the wide-character equivalent of the
+The \fBwprintf\fP() family of functions is the wide-character equivalent of the
\fBprintf\fP family of functions. It performs formatted output of wide
characters.
.PP
-The \fBwprintf\fP and \fBvwprintf\fP functions perform wide character output
+The \fBwprintf\fP() and \fBvwprintf\fP() functions perform wide character output
to \fBstdout\fP. \fBstdout\fP must not be byte oriented; see function
\fBfwide\fP for more information.
.PP
-The \fBfwprintf\fP and \fBvfwprintf\fP functions perform wide character output
+The \fBfwprintf\fP() and \fBvfwprintf\fP() functions perform wide character output
to \fIstream\fP. \fIstream\fP must not be byte oriented; see function
\fBfwide\fP for more information.
.PP
-The \fBswprintf\fP and \fBvswprintf\fP functions perform wide character output
+The \fBswprintf\fP() and \fBvswprintf\fP() functions perform wide character output
to an array of wide characters.
The programmer must ensure that there is room for at least \fImaxlen\fP wide
characters at \fIwcs\fP.
The output consists of wide characters, not bytes.
.TP
.B \(bu
-\fBswprintf\fP and \fBvswprintf\fP take a \fImaxlen\fP argument,
+\fBswprintf\fP() and \fBvswprintf\fP() take a \fImaxlen\fP argument,
\fBsprintf\fP and \fBvsprintf\fP do not. (\fBsnprintf\fP and \fBvsnprintf\fP
take a \fImaxlen\fP argument, but these functions do not return \-1 upon
buffer overflow on Linux.)
to the number of wide characters in the array.
.SH "RETURN VALUE"
The functions return the number of wide characters written, excluding the
-terminating null wide character in case of the functions \fBswprintf\fP and
-\fBvswprintf\fP. They return \-1 when an error occurs.
+terminating null wide character in case of the functions \fBswprintf\fP() and
+\fBvswprintf\fP(). They return \-1 when an error occurs.
.SH "CONFORMING TO"
ISO/ANSI C, UNIX98
.SH "SEE ALSO"
.BR snprintf (3),
.BR wscanf (3)
.SH NOTES
-The behaviour of \fBwprintf\fP et al. depends on the LC_CTYPE category of the
+The behaviour of \fBwprintf\fP() et al. depends on the LC_CTYPE category of the
current locale.
.PP
If the \fIformat\fP string contains non-ASCII wide characters, the program
projects / thirdparty / man-pages.git / commitdiff
